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.