IObjectAccessControl::GetObjectAccessRights

Gets a list of all access rights or the rights of a specific trustee for a specific object.

HRESULT GetObjectAccessRights (
   SEC_OBJECT *         pObject,
   ULONG *              pcAccessEntries,
   EXPLICIT_ACCESS **   prgAccessEntries
);

Parameters

pObject

[in]
Address of an initialized SEC_OBJECT structure that indicates the database object on which permissions are to be retrieved.

pcAccessEntries

[in, out]
Address of a ULONG variable that contains the number of access entries requested or receives the number of access entries returned. See Comments.

prgAccessEntries

[in, out]
Address of an array of EXPLICIT_ACCESS structures.

Return Code

S_OK

The access rights were successfully retrieved.

DB_S_ERRORSOCCURRED

An error occurred while retrieving access entries, but at least one access entry was successfully returned. Access entries that could not be returned are marked with grfAccessMode set to NOT_USED_ACCESS.

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.

SEC_E_PERMISSIONDENIED

Caller does not have enough permission to complete the operation.

E_INVALIDARG

pObject, pcAccessEntries, or prgAccessEntries was a null pointer, or *pcAccessEntries was not equal to zero and *prgAccessEntries was a null pointer.

E_FAIL

A provider-specific error occurred.

Comments

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

This method can retrieve access permissions for one trustee, or it can retrieve all the access permissions for all trustees.

To retrieve access permissions for one trustee, *pcAccessEntries must be nonzero on input. *prgAccessEntries must be a pointer to an array of exactly one or two EXPLICIT_ACCESS structures. The Trustee element of each element in the array should point to the TRUSTEE that is being checked. If the caller sets *pcAccessEntries to one, the grfAccessMode element of that structure must be set to either SET_ACCESS or DENY_ACCESS, indicating which type of permissions the caller is interested in. Otherwise, *pcAccessEntries should be set to two and the grfAccessMode element will be set to SET_ACCESS in one structure and to DENY_ACCESS in the other structure.

If *pcAccessEntries is nonzero on input, the provider will fill in the EXPLICIT_ACCESS structures passed in using *prgAccessEntries. The provider should examine the grfAccessMode element of each structure to determine how to fill in the grfAccessPermissions element. The only expected ACCESS_MODE values in the grfAccessMode element are SET_ACCESS and DENY_ACCESS. The provider will not change any part of the TRUSTEE structures in the pTrustee elements.

To retrieve access permissions for all trustees of an object, *pcAccessEntries must be zero on input and prgAccessEntries must be the address of an EXPLICIT_ADDRESS pointer, which will be set by the provider.

If *pcAccessEntries is zero on input, the provider calls CoTaskMemAlloc to allocate an array of EXPLICIT_ACCESS structures large enough to return all explicit access rights for the object specified by pObject. The provider must set *pcAccessEntries to the number of structures in the array and set *prgAccessEntries to point to that array.

When the caller is finished with the array of EXPLICIT_ACCESS structures, it releases the array. It is possible that the pTrustee element of each EXPLICIT_ACCESS structure refers to multiple trustees. If so, *pMultipleTrustee in the TRUSTEE structure will not be set to NULL. The caller traverses the linked list of TRUSTEE structures that start with the head *pMultipleTrustee element and releases them in reverse order. The caller also frees the memory allocated for each ptstrName element. It should call CoTaskMemFree for all of these tasks.