MDAC Technical Articles

IObjectAccessControl::SetObjectAccessRights

Sets, adds, or revokes access rights of a trustee for a specific object.

HRESULT SetObjectAccessRights ( 
   SEC_OBJECT *         pObject,
   ULONG                cAccessEntries,
   EXPLICIT_ACCESS *    prgAccessEntries
);

Parameters

pObject
[in]
Address of an initialized SEC_OBJECT structure that indicates the database object on which permissions are to be set.
cAccessEntries
[in]
The number of access control entries listed in prgAccessEntries.
prgAccessEntries
[in, out]
Array of access control entries to set. See Comments.

Return Code

S_OK
The access rights were successfully set.
DB_S_ERRORSOCCURRED
One or more access control entries were not set, but at least one access control entry was successfully set. The consumer checks the array of EXPLICIT_ACCESS structures at prgAccessEntries; the entries that failed will have the grfAccessMode entry set to NOT_USED_ACCESS.
DB_E_ERRORSOCCURRED
No access control entries were set. Every EXPLICIT_ACCESS structure in prgAccessEntries will have the grfAccessMode entry set to NOT_USED_ACCESS.
SEC_E_PERMISSIONDENIED
Requester does not have permissions for the operation.
SEC_E_INVALIDACCESSENTRYLIST
One or more elements of *prgAccessEntries was invalid.
SEC_E_INVALIDOBJECT
The object that was supplied is invalid or unknown to the provider.
E_INVALIDARG
pObject was a null pointer, or cAccessEntries was not zero and prgAccessEntries was a null pointer.
E_FAIL
A provider-specific error occurred.

Comments

The caller initializes pObject to specify the database object whose permissions are being set. See SEC_OBJECT for an explanation on initializing this structure.

The grfAccessMode member of each EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values from the ACCESS_MODE enumeration.

Value Meaning
GRANT_ACCESS Creates a new access-allowed entry that combines the specified rights with any existing rights of the trustee. The new entry replaces any existing access-allowed entry for the trustee. The provider, in implementing this method , should modify or delete any existing access-denied entry for the trustee that denies the specified rights.
SET_ACCESS Similar to GRANT_ACCESS except that the new access-allowed entry allows only the specified rights, discarding any existing rights. This flag also removes any existing access-denied entry for the trustee.
DENY_ACCESS Creates a new access-denied entry that replaces any existing access-denied entry for the trustee. The new entry denies the specified rights in addition to any currently denied rights of the trustee. The provider should modify or delete any existing access-allowed entry for the trustee that allows the specified rights.
REVOKE_ACCESS Removes any existing entries for the specified trustee. The provider should ignore the rights specified in the grfAccessPermissions member of the EXPLICIT_ACCESS structure.

To set and deny properties in a single call to SetObjectAccessRights, the following restrictions apply to the access entries:

See Also

EXPLICIT_ACCESS, IObjectAccessControl, IObjectAccessControl::GetObjectAccessRights, IObjectAccessControl::IsObjectAccessAllowed, SEC_OBJECT, TRUSTEE