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