Interfaces

  • Article

 

Microsoft Corporation

This section of the OLE DB security administration guide defines the methods and arguments of the following interfaces for OLE DB security administration:

  • IObjectAccessControl
  • ISecurityInfo
  • ITrusteeAdmin
  • ITrusteeGroupAdmin

IObjectAccessControl

The IObjectAccessControl interface enables the management of access to objects and containers managed by data providers.

IObjectAccessControl is based on the general form of the COM interface IAccessControl. The main difference between the two interfaces is that IObjectAccessControl requires the object identity as an explicit parameter in the various methods, while for IAccessControl the object is implicit. OLE DB has a different requirement than COM, in that access control operations may be directed to data items that are not necessarily COM objects.

When to Implement

The provider will implement IObjectAccessControl on the data source object to expose security administration features of the data store. This interface is optional for all OLE DB providers.

When to Use

When the data source object has been initialized, the consumer uses this interface to examine or change specific details about access control for the data source objects and their trustees.

Method Description
GetObjectAccessRights Gets a list of all access rights or the rights of a specific trustee for a specific object.
GetObjectOwner Returns the owner of a database object.
IsObjectAccessAllowed Determines whether the given trustee has specific permissions (access rights) to the database object.
SetObjectAccessRights Sets, adds, or revokes access rights of a trustee for a specific object.
SetObjectOwner Sets the owner of an object.

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.

See Also

EXPLICIT_ACCESS, IObjectAccessControl, IObjectAccessControl::IsObjectAccessAllowed, IObjectAccessControl::SetObjectAccessRights, SEC_OBJECT, TRUSTEE

IObjectAccessControl::GetObjectOwner

Returns the owner of a database object.

HRESULT GetObjectOwner ( 
   SEC_OBJECT *   pObject,
   TRUSTEE **     ppOwner
);

Parameters

  • pObject
    [in]
    Address of an initialized SEC_OBJECT structure that indicates the database object whose owner is to be retrieved.
  • ppOwner
    [out]
    Address of a TRUSTEE pointer variable that receives the trustee information of the owner of the database object.

Return Code

  • S_OK
    The owner was successfully retrieved.
  • SEC_E_NOOWNER
    No owner exists for the object.
  • 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 or ppOwner was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

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

The provider calls CoTaskMemAlloc to allocate a TRUSTEE structure, into which it places the identity of the owner of the database object. It places the address of this structure into the address indicated by *ppOwner.

When the caller is finished with the TRUSTEE structure, it calls CoTaskMemFree to release the ptstrName element and then the TRUSTEE structure itself.

See Also

IObjectAccessControl, IObjectAccessControl::SetObjectOwner, SEC_OBJECT, TRUSTEE

IObjectAccessControl::IsObjectAccessAllowed

Determines whether the given trustee has specific permissions (access rights) to the database object.

HRESULT IsObjectAccessAllowed ( 
   SEC_OBJECT *         pObject,
   EXPLICIT_ACCESS *    pAccessEntry,
   BOOL *               pfResult
);

Parameters

  • pObject
    [in]
    Address of an initialized SEC_OBJECT structure that indicates the database object on which permissions are to be checked.
  • pAccessEntry
    [in]
    Address of an initialized EXPLICIT_ACCESS structure that indicates the TRUSTEE and the permissions to check.
  • pfResult
    [out]
    Address of a BOOL variable that receives the result of the check.

Return Code

  • S_OK
    The method succeeded, whether the TRUSTEE has the permissions requested or not.
  • SEC_E_PERMISSIONDENIED
    Caller does not have enough permission to complete the operation.
  • SEC_E_INVALIDACCESSENTRY
    One or more permissions in the grfAccessPermissions element of the EXPLICIT_ACCESS structure are invalid.
  • SEC_E_INVALIDOBJECT
    The object that was supplied is invalid or unknown to the provider.
  • E_INVALIDARG
    pObject, pAccessEntry, or pfResult 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.

The provider determines whether the trustee has all of the permissions specified in the grfAccessPermissions entry in the EXPLICIT_ACCESS **** structure given in pAccessEntry. When it has determined that each permission requested is allowed and not denied, the provider sets the BOOLEAN variable pointed to by *pfResult to TRUE. Otherwise, if any permission is denied or not specifically allowed, the provider sets *pfResult to FALSE.

The provider is permitted, while determining whether access is allowed, to use additional information related to the security attributes for the specified trustee. This includes any roles or groups of which the trustee is a member. The information used need not be given in the parameters to this method. The exact implementation of this is left to the provider.

For example, the consumer calls the provider to determine whether GENERIC_READ permission is allowed for trustee NewUser on the data source object NewTable. The provider checks the access control entry lists for NewTable and determines that NewUser does not have a GRANT_ACCESS entry for the GENERIC_READ permission. The provider also determines that NewUser does not have a DENY_ACCESS entry at all. If this were all the information provided in this call to the provider, NewUser would be denied read access to NewTable. However, the provider is allowed to check any groups to which NewUser belongs. The provider finds that NewUser is a member of the group trustee NewGroup. The provider checks the access control entry lists for NewTable and determines that NewGroup does have a SET_ACCESS entry for both GENERIC_READ and GENERIC_WRITE permissions, and after completing its check, the provider finds no DENY_ACCESS entries. Therefore, the provider chooses to allow NewUser to read NewTable and sets *pfResult to TRUE.

See Also

EXPLICIT_ACCESS, IObjectAccessControl, IObjectAccessControl::GetObjectAccessRights, IObjectAccessControl::SetObjectAccessRights, SEC_OBJECT, TRUSTEE

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:

  • The elements of prgAccessEntries are processed in order.
  • Any EXPLICIT_ACCESS structures denying permissions need to come before any EXPLICIT_ACCESS structures that grant permissions.
  • The EXPLICIT_ACCESS **** structure granting permissions must use GRANT rather than SET.

See Also

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

IObjectAccessControl::SetObjectOwner

Sets the owner of an object.

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

HRESULT SetObjectOwner ( 
   SEC_OBJECT *   pObject,
   TRUSTEE *      pOwner
);

Parameters

  • pObject
    [in]
    Address of an initialized SEC_OBJECT structure that indicates the database object whose owner is to be set.
  • pOwner
    [in]
    Address of an initialized TRUSTEE structure that has the trustee information of the new owner of the object.

Return Code

  • S_OK
    The owner was successfully set.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_INVALIDOWNER
    The trustee supplied as owner is invalid or unknown to the provider.
  • SEC_E_INVALIDOBJECT
    The object that was supplied is invalid or unknown to the provider.
  • SEC_E_NOOWNER
    An attempt was made to set ownership for an object that cannot be owned by any trustee.
  • E_INVALIDARG
    pObject or pOwner was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

IObjectAccessControl, IObjectAccessControl::GetObjectOwner, SEC_OBJECT, TRUSTEE

ISecurityInfo

The ISecurityInfo interface provides information to the consumer about the security administration support given by the provider.

When to Implement

The provider will implement ISecurityInfo to expose general security information about the data source object. This interface is optional for all OLE DB providers but is required if the provider implements the IObjectAccessControl interface.

When to Use

When the data source object has been initialized, the consumer uses this interface to determine the current trustee, the available permissions, or the types of object that support permissions.

Method Description
GetCurrentTrustee Returns the current trustee.
GetObjectTypes Returns an array of object types that can be secured with access control entries.
GetPermissions Returns the available permissions for a given object type.

ISecurityInfo::GetCurrentTrustee

Returns the current trustee.

HRESULT GetCurrentTrustee ( 
   TRUSTEE **     ppTrustee
);

Parameters

  • ppTrustee
    [out]
    Address of a TRUSTEE pointer variable that receives the trustee information of the current user.

Return Code

  • S_OK
    The current trustee was successfully retrieved.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • E_INVALIDARG
    ppTrustee was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The provider allocates memory for the TRUSTEE structure by calling CoTaskMemAlloc and returns the address of this memory in the *ppTrustee variable.

When the caller is finished with the structure, it is responsible for releasing the memory allocated. Before the caller releases the TRUSTEE structure, it should release the memory allocated in the ptstrName element. 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 should call CoTaskMemFree for all of these tasks.

If an error occurs, the provider does not allocate any memory and sets *ppTrustee to a null pointer.

See Also

ISecurityInfo, TRUSTEE

ISecurityInfo::GetObjectTypes

Returns an array of object types that can be secured with access control entries.

HRESULT GetObjectTypes ( 
   ULONG *     cObjectTypes,
   GUID **     rgObjectTypes
);

Parameters

  • cObjectTypes
    [out]
    Address of a ULONG variable that receives the number of types of objects.
  • rgObjectTypes
    [out]
    Address of an array of GUIDs that represent types of objects.

Return Code

  • S_OK
    The array of object types was successfully returned.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • E_INVALIDARG
    cObjectTypes or rgObjectTypes was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The provider calls CoTaskMemAlloc to allocate an array of GUIDs that represent all the types of objects that can have permissions settings applied to them. OLE DB defines several standard object type GUIDs. Additionally, the provider may define provider-specific GUIDs to identify object types unique to the data store; these types should be clearly documented by the provider's developer.

The consumer releases the allocated array at rgObjectTypes by calling CoTaskMemFree when it is finished.

See Also

SEC_OBJECT

ISecurityInfo::GetPermissions

Returns the available permissions for a given object type.

The provider sets the appropriate bits in an ACCESS_MASK structure to identify the permissions for any trustee that can possibly be set on the object type given in ObjectType.

HRESULT GetPermissions ( 
   GUID              ObjectType,
   ACCESS_MASK *     pPermissions
);

Parameters

  • ObjectType
    [in]
    The GUID of the object type for which permissions are being obtained.
  • pPermissions
    [out]
    Address of an ACCESS_MASK structure that receives the permissions supported for the object.

Return Code

  • S_OK
    The available permissions were successfully retrieved.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_INVALIDOBJECT
    The object that was supplied is invalid or unknown to the provider.
  • E_INVALIDARG
    pPermissions was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The GUID in ObjectType can be either a standard object type GUID or a provider-specific GUID for nonstandard objects types.

See Also

ACCESS_MASK Constants, Standard Object Type GUIDs

ITrusteeAdmin

The ITrusteeAdmin interface allows the consumer to add, remove, and compare trustees. It also allows the consumer to modify trustee properties used for authentication, such as passwords and a descriptive user name.

When to Implement

The provider will implement the ITrusteeAdmin interface on the data source object if it supports administration of trustees. Trustees can be users, groups, roles, services, and so on. This interface is optional for all providers but is required if the ITrusteeGroupAdmin interface is implemented.

When to Call

After it initializes the data source object, the consumer uses this interface to examine or change trustees that are known by the provider.

Method Description
CompareTrustees Determines whether two trustees are identical.
CreateTrustee Adds a trustee to the collection of trustees known by the data source object. Also sets initial properties for the trustee, such as authentication information and display name.
DeleteTrustee Removes a trustee from the collection of trustees known by the data source object.
GetTrusteeProperties Gets the properties for the trustee, such as the display name or authentication information.
SetTrusteeProperties Sets properties for the trustee, such as the display name or authentication information.

ITrusteeAdmin::CompareTrustees

Determines whether two trustees are identical.

The consumer passes in the addresses of two initialized TRUSTEE structures to this method. The provider compares the trustee in any manner it chooses and returns the result of that comparison in the HRESULT return code.

HRESULT CompareTrustees ( 
   TRUSTEE *   pTrustee1,
   TRUSTEE *   pTrustee2
);

Parameters

  • pTrustee1
    [in]
    Address of the first TRUSTEE structure to compare.
  • pTrustee2
    [in]
    Address of the second TRUSTEE structure to compare.

Return Code

  • S_OK
    The two trustees are equal.
  • S_FALSE
    The two trustees are not equal.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pTrustee1 or pTrustee2 did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pTrustee1 or pTrustee2 was not a trustee for the current data source object.
  • E_INVALIDARG
    pTrustee1 or pTrustee2 was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

ITrusteeAdmin, TRUSTEE

ITrusteeAdmin::CreateTrustee

Adds a trustee to the collection of trustees known by the data source object. Also sets initial properties for the trustee, such as authentication information and display name.

HRESULT CreateTrustee ( 
   TRUSTEE *   pTrustee,
   ULONG       cPropertySets,
   DBPROPSET   rgPropertySets[]
);

Parameters

  • pTrustee
    [in]
    Address of the initialized TRUSTEE structure to add.

  • cPropertySets
    [in]
    Number of structures in the array rgPropertySets. Set to zero to add the trustee with no properties.

  • rgPropertySets
    [in, out]
    Array of DBPROPSET structures for the properties to be set on the trustee.

    The property IDs specified in this structure must belong to the Trustee property group.

    If cPropertySets is zero, rgPropertySets is ignored.

Return Code

  • S_OK
    The trustee was successfully added to the collection of trustees known by the data source object.

  • DB_S_ERRORSOCCURRED
    The trustee was created, but one or more optional properties could not be set. Optional properties have the dwOptions element of the DBPROP structure set to DBPROPOPTIONS_OPTIONAL. The consumer checks the dwStatus element of the DBPROP structures to determine which properties were not set.

  • DB_E_ERRORSOCCURRED
    The trustee was not created because one or more required properties could not be set. Required properties have the dwOptions element of the DBPROP structure set to DBPROPOPTIONS_REQUIRED. The consumer checks the dwStatus element of the DBPROP structures to determine which properties were not set.

  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.

  • SEC_E_BADTRUSTEEID
    pTrustee did not point to a valid TRUSTEE structure.

  • E_INVALIDARG
    pTrustee was a null pointer

    -or-

    cPropertySets was greater than zero and rgPropertySets was a null pointer

    -or-

    In a DBPROPSET structure in the array rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

  • E_FAIL
    A provider-specific error occurred.

Comments

If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used.

The DBPROPSTATUS enumerated type in the OLE DB Programmer's Reference lists the possible status values returned in the dwStatus element of the DBPROP structures.

See Also

DBPROPSTATUS, ITrusteeAdmin, ITrusteeAdmin::DeleteTrustee, Properties Overview, TRUSTEE, Trustee property group

ITrusteeAdmin::DeleteTrustee

Removes a trustee from the collection of trustees known by the data source object.

HRESULT DeleteTrustee ( 
   TRUSTEE *   pTrustee
);

Parameters

  • pTrustee
    [in]
    Address of a TRUSTEE structure identifying the trustee to be removed.

Return Code

  • S_OK
    The trustee was successfully removed.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pTrustee was not a trustee for the current data source object.
  • E_INVALIDARG
    pTrustee was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

ITrusteeAdmin, ITrusteeAdmin::CreateTrustee, TRUSTEE

ITrusteeAdmin::GetTrusteeProperties

Gets the properties for the trustee, such as the display name or authentication information.

HRESULT GetTrusteeProperties ( 
   TRUSTEE *            pTrustee,
   const ULONG          cPropertyIDSets,
   const DBPROPIDSET    rgPropertyIDSets[],
   ULONG *              pcPropertySets,
   DBPROPSET **         prgPropertySets
);

Parameters

  • pTrustee
    [in]
    Address of an initialized TRUSTEE structure that identifies the trustee whose properties are to be retrieved.

  • cPropertyIDSets
    [in]
    Number of DBPROPIDSET structures in rgPropertyIDSets. Set to zero to retrieve the values of all the properties for the trustee.

  • rgPropertyIDSets
    [in]
    Array of DBPROPIDSET structures that describe the properties to be retrieved from the trustee.

    The property IDs specified in this structure must belong to the Trustee property group.

    If cPropertyIDSets is zero, rgPropertyIDSets is ignored.

  • pcPropertySets
    [out]
    Address of a ULONG variable that receives the number of DBPROPSET structures returned using prgPropertySets.

  • prgPropertySets
    [out]
    Address of a DBPROPSET pointer variable that receives the address of an array of DBPROPSET structures.

Return Code

  • S_OK
    The properties for the trustee were successfully retrieved.
  • DB_S_ERRORSOCCURRED
    No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structures of prgPropertySets to determine which properties were not returned and why.
  • DB_E_ERRORSOCCURRED
    Values were not returned for any properties, although the provider still allocates memory for prgPropertySets and sets pcPropertySets. The consumer checks dwStatus in the DBPROP structures of prgPropertySets to determine why properties were not returned.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pTrustee was not a trustee for the current data source object.
  • E_INVALIDARG
    pTrustee was a null pointer; or cPropertyIDSets was not zero and rgPropertyIDSets was a null pointer; or pcPropertySets or prgPropertySets was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The consumer can call this method in one of two ways: It can request values for specific properties for the trustee, or it can request all of the trustee's properties and their values.

To request values for specific properties, the consumer will allocate and initialize an array of DBPROPIDSET structures. Since only the Trustee property group is allowed for this method, the array will have one element in it. The consumer will also set cPropertyIDSets to the number of DBPROPIDSET structures in the array at rgPropertySets. Again, because only the Trustee property group can be requested, cPropertyIDSets will be set to 1.

To request all of the properties for pTrustee and their values, the consumer sets cPropertyIDSets to zero. It does not need to initialize rgPropertySets.

The provider will allocate an array of DBPROPSET **** structures to return the properties and their values. How it initializes this array depends on whether the consumer requested specific property values or all of the properties.

If the consumer requested specific properties, cPropertyIDSets will be greater than zero. If so, the provider sets *pcPropertySets equal to cPropertyIDSets. The provider calls CoTaskMemAlloc to allocate an array of DBPROPSET structures. This array of DBPROPSET structures will correspond one-for-one with the array of DBPROPIDSET structures passed in using rgPropertyIDSets, so there will be *pcPropertySets elements in the DBPROPSET array. The provider sets the guidPropertySet element of each of the DBPROPSET structures so that they are in the same order as they are given in the DBPROPIDSET array.

For each DBPROPIDSET that has its cPropertyIDs element set greater than zero, the provider will set the cProperties element of the corresponding DBPROPSET structure equal to cPropertyIDs. It also calls CoTaskMemAlloc to allocate an array of DBPROP structures for the rgProperties elements of the DBPROPSET structures. This array of DBPROP structures will correspond one-for-one with the array of DBPROPID values in the rgPropertyIDs elements of the DBPROPIDSET structures, so there will be cProperties elements in the DBPROP array. The provider sets the dwPropertyID element of each DBPROP structure so that they are in the same order as they are given in the DBPROPID array.

If the consumer requested all of the properties and their values, cPropertyIDSets will be equal to zero. If so, one DBPROPSET **** structure is returned for each property set that contains at least one property belonging to the Trustee property group. The provider ignores rgPropertyIDSets. The provider sets *pcPropertySets to the total number of property sets for which the provider supports at least one property in the Trustee property group.

If any error occurs, other than DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the provider does not allocate any memory and sets *pcPropertySets to zero and sets *prgPropertySets to a null pointer on output.

The DBPROPSTATUS enumerated type in the OLE DB Programmer's Reference lists the possible status values returned in the dwStatus element of the DBPROP structures.

The consumer releases *prgPropertySets when it no longer needs the DBPROPSET **** structures. Before releasing this array, the consumer should release the rgProperties element within each element of *prgPropertySets. The consumer should call CoTaskMemFree for all these tasks.

See Also

ITrusteeAdmin, ITrusteeAdmin::SetTrusteeProperties, Properties Overview, TRUSTEE

ITrusteeAdmin::SetTrusteeProperties

Sets properties for the trustee, such as the display name or authentication information.

HRESULT SetTrusteeProperties ( 
   TRUSTEE *   pTrustee,
   ULONG       cPropertySets,
   DBPROPSET   rgPropertySets[]
);

Parameters

  • pTrustee
    [in]
    Address of an initialized TRUSTEE structure that identifies the trustee whose properties are to be retrieved.

  • cPropertySets
    [in]
    Number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method returns S_OK without doing anything.

  • rgPropertySets
    [in, out]
    Array of DBPROPSET structures describing properties to be set on the trustee.

    The property IDs specified in this structure must belong to the Trustee property group.

    If cPropertySets is zero, rgPropertySets is ignored.

Return Code

  • S_OK
    The properties for the trustee were successfully set.
  • DB_S_ERRORSOCCURRED
    One or more of the properties could be set, but some could not be set. Properties not in error remain set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set and why.
  • DB_E_ERRORSOCCURRED
    No properties were set. The consumer checks dwStatus in the DBPROP structures to determine why properties were not set.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pTrustee was not a trustee for the current data source object.
  • E_INVALIDARG
    pTrustee was a null pointer; or cPropertySets was not zero and rgPropertySets was a null pointer; or, in a DBPROPSET structure in the array rgPropertySets, cProperties was not zero and rgProperties was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used.

The DBPROPSTATUS enumerated type in the OLE DB Programmer's Reference lists the possible status values returned in the dwStatus element of the DBPROP structures.

See Also

DBPROPSTATUS, ITrusteeAdmin, ITrusteeAdmin::GetTrusteeProperties, Properties Overview, TRUSTEE, Trustee property group

ITrusteeGroupAdmin

The ITrusteeGroupAdmin interface allows the consumer to manage trustees that have other trustees as members. These "collection" trustees are called membership trustees. The interface allows the consumer to add and remove trustees from a membership trustee and to determine whether a trustee is a member of a membership trustee. It also allows the consumer to get a list of the members of a membership trustee and to get a list of the membership trustee to which a trustee belongs.

The provider may or may not support membership trustees that can have other membership trustees as members. This is provider-specific behavior.

When to Implement

The provider will implement the ITrusteeGroupAdmin interface on the data source object if it supports membership trustees. This interface is optional for all providers.

When to Call

After it initializes the data source object, the consumer uses this interface to examine or change the members of a membership trustee known by the provider.

Method Description
AddMember Adds a member trustee to a membership trustee.
DeleteMember Removes a trustee from a membership trustee.
GetMembers Gets the members of a membership trustee.
GetMemberships Gets the membership trustees to which a trustee belongs.
IsMember Determines whether a trustee is a member of a membership trustee.

ITrusteeGroupAdmin::AddMember

Adds a member trustee to a membership trustee.

HRESULT AddMember ( 
   TRUSTEE *   pMembershipTrustee,
   TRUSTEE *   pMemberTrustee
);

Parameters

  • pMembershipTrustee
    [in]
    Address of the TRUSTEE structure that identifies the membership trustee to which pMemberTrustee will be added.
  • pMemberTrustee
    [in]
    Address of the TRUSTEE structure that identifies the trustee to be added to pMembershipTrustee.

Return Code

  • S_OK
    The trustee was successfully added to the membership trustee.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pMembershipTrustee or pMemberTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pMembershipTrustee or pMemberTrustee was not a trustee for the current data source.
  • SEC_E_NOMEMBERSHIPSUPPORT
    The trustee pointed to by pMembershipTrustee does not support memberships.
  • E_INVALIDARG
    pMembershipTrustee or pMemberTrustee was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

ITrusteeGroupAdmin, ITrusteeGroupAdmin::DeleteMember, TRUSTEE

ITrusteeGroupAdmin::DeleteMember

Removes a trustee from a membership trustee.

HRESULT DeleteMember ( 
   TRUSTEE *   pMembershipTrustee,
   TRUSTEE *   pMemberTrustee
);

Parameters

  • pMembershipTrustee
    [in]
    Address of the TRUSTEE structure that identifies the trustee from which pMemberTrustee is to be removed.
  • pMemberTrustee
    [in]
    Address of the TRUSTEE structure that identifies the trustee to be removed from pMembershipTrustee.

Return Code

  • S_OK
    The trustee was successfully removed from the membership trustee.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pMembershipTrustee or pMemberTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pMembershipTrustee or pMemberTrustee was not a trustee for the current data source object.
  • SEC_E_NOMEMBERSHIPSUPPORT
    The trustee pointed to by pMembershipTrustee does not support memberships.
  • E_INVALIDARG
    pMembershipTrustee or pMemberTrustee was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

ITrusteeGroupAdmin, ITrusteeGroupAdmin::AddMember, TRUSTEE

ITrusteeGroupAdmin::GetMembers

Gets the members of a membership trustee.

This function is not applicable to trustees with the TRUSTEE_TYPE element set to TRUSTEE_IS_USER, because a user cannot have members.

HRESULT GetMembers ( 
   TRUSTEE *      pMembershipTrustee,
   ULONG *        pcMembers,
   TRUSTEE **     prgMembers
);

Parameters

  • pMembershipTrustee
    [in]
    Address of the TRUSTEE structure that identifies the membership trustee whose members will be returned.
  • pcMembers
    [out]
    Address of a ULONG variable that receives the number of TRUSTEE structures in prgMembers.
  • prgMembers
    [out]
    Address of a TRUSTEE pointer variable that receives the address of an array of TRUSTEE structures representing the trustees that are members of pMembershipTrustee.

Return Code

  • S_OK
    The members of the membership trustee were successfully retrieved.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pMembershipTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOMEMBERSHIPSUPPORT
    The trustee pointed to by pMembershipTrustee does not support memberships.
  • SEC_E_NOTRUSTEEID
    pMembershipTrustee was not a trustee for the current data source object.
  • E_INVALIDARG
    pMembershipTrustee, pcMembers, or prgMembers was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The provider calls CoTaskMemAlloc to allocate memory for the array of TRUSTEE structures that represent the members of pMembershipTrustee.

The consumer releases *prgMembers when it no longer needs the TRUSTEE structures. Before freeing this memory, the consumer should free any memory allocated in the pMultipleTrustee or ptstrName elements of each structure. The consumer should call CoTaskMemFree for all these tasks.

If pMembershipTrustee does not contain any members or is not a membership trustee, the provider sets *pcMembers to zero, *prgMembers to NULL, and does not allocate any memory for *prgMembers.

See Also

ITrusteeGroupAdmin, ITrusteeGroupAdmin::GetMemberships, ITrusteeGroupAdmin::IsMember, TRUSTEE

ITrusteeGroupAdmin::GetMemberships

Gets the membership trustees to which a trustee belongs.

HRESULT GetMemberships ( 
   TRUSTEE *      pTrustee,
   ULONG *        pcMemberships,
   TRUSTEE **     prgMemberships
);

Parameters

  • pTrustee
    [in]
    Address of an initialized TRUSTEE structure that identifies the trustee whose memberships will be returned.
  • pcMemberships
    [out]
    Address of a ULONG variable that receives the number of TRUSTEE structures returned using prgMemberships.
  • prgMemberships
    [out]
    Address of a TRUSTEE pointer variable that receives the address of an array of TRUSTEE structures representing the membership trustees that have pTrustee as a member.

Return Code

  • S_OK
    The membership trustees were successfully retrieved.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pTrustee was not a trustee for the current data source object.
  • E_INVALIDARG
    pTrustee, pcMemberships, or prgMemberships was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

Comments

The provider calls CoTaskMemAlloc to allocate memory for the array of TRUSTEE structures that represent the membership trustees that have pTrustee as a member.

The consumer releases *prgMemberships when it no longer needs the TRUSTEE structures. Before freeing this memory, the consumer should free any memory allocated in the pMultipleTrustee or ptstrName elements of each structure. The consumer should call CoTaskMemFree for all these tasks.

If the trustee identified by pTrustee does not belong to any membership trustees or if an error occurs, the provider ensures that no memory is allocated for prgMemberships, sets *pcMemberships to zero, and sets *prgMemberships to NULL.

See Also

ITrusteeGroupAdmin, ITrusteeGroupAdmin::GetMembers, ITrusteeGroupAdmin::IsMember, TRUSTEE

ITrusteeGroupAdmin::IsMember

Determines whether a trustee is a member of a membership trustee.

This function is not applicable to trustees with the TRUSTEE_TYPE element set to TRUSTEE_IS_USER, because a user cannot have members.

HRESULT IsMember ( 
   TRUSTEE *   pMembershipTrustee,
   TRUSTEE *   pMemberTrustee,
   BOOL *      pfStatus
);

Parameters

  • pMembershipTrustee
    [in]
    Address of the TRUSTEE structure that identifies the membership trustee whose membership will be checked.
  • pMemberTrustee
    [in]
    Address of the TRUSTEE structure that identifies the trustee to find in the membership trustee.
  • pfStatus
    [out]
    Address of a BOOL variable that receives the result of the check.

Return Code

  • S_OK
    The method succeeded, whether or not pMemberTrustee is a member of pMembershipTrustee.
  • SEC_E_PERMISSIONDENIED
    Requester does not have permissions for the operation.
  • SEC_E_BADTRUSTEEID
    pMembershipTrustee or pMemberTrustee did not point to a valid TRUSTEE structure.
  • SEC_E_NOTRUSTEEID
    pMembershipTrustee or pMemberTrustee was not a trustee for the current data source object.
  • SEC_E_NOMEMBERSHIPSUPPORT
    The trustee pointed to by pMembershipTrustee does not support memberships.
  • E_INVALIDARG
    pMembershipTrustee, pMemberTrustee, or pfStatus was a null pointer.
  • E_FAIL
    A provider-specific error occurred.

See Also

ITrusteeGroupAdmin, ITrusteeGroupAdmin::GetMembers, ITrusteeGroupAdmin::GetMemberships, TRUSTEE