MDAC 2.5 SDK - Technical Articles


 

Trustee Administration

The data provider implements the following two interfaces to support administration tasks for trustees:

These interfaces use a TRUSTEE structure to identify a trustee. The TRUSTEE structure is documented in the Access Control section of the Microsoft® Platform SDK. The TRUSTEE structure contains the unique identification of the trustee in the ptstrName element. As indicated by the value of the TrusteeForm element, the ptstrName element contains either a unique name or a system-generated SID for the trustee. As indicated by the value of the TrusteeType element, a TRUSTEE structure can represent a single trustee or a group of trustees.

Some Windows® functions aid in working with TRUSTEE structures. BuildTrusteeWithName and BuildTrusteeWithSid both initialize a TRUSTEE structure. GetTrusteeForm, GetTrusteeName, and GetTrusteeType each return the value of the appropriate element from a TRUSTEE structure.

The ITrusteeAdmin and ITrusteeGroupAdmin interfaces also use a new property group to modify information about trustees. The Trustee property group DBPROPSET_TRUSTEE contains three properties that allow the consumer to change the trustee's password and descriptive name. Three ITrusteeAdmin methods, CreateTrustee, GetTrusteeProperties, and SetTrusteeProperties, use the Trustee property group to get and change authentication information.

ITrusteeAdmin Methods

ITrusteeAdmin methods allow the consumer to create, delete, and compare trustees. These methods also allow the consumer to set or modify trustee properties used for authentication, such as passwords and a descriptive user name.

To add a trustee to the data source object, the consumer allocates a TRUSTEE structure and initializes it. The consumer also allocates and initializes an array of DBPROPSET structures, one for each trustee property that it sets. Generally, the consumer uses two structures: one for the trustee's descriptive name and another for the password. Then the consumer calls ITrusteeAdmin::CreateTrustee, and the provider adds the trustee to the data source object. Any errors are returned to the consumer by using the HRESULT.

To remove a trustee from the data source object, the consumer simply allocates a TRUSTEE structure and initializes it. Then the consumer calls ITrusteeAdmin::DeleteTrustee, and the provider removes the trustee from the data store. Any errors are returned to the consumer by using the HRESULT.

To compare two trustees, the consumer allocates two TRUSTEE structures and initializes them. Alternatively, the consumer may use a TRUSTEE structure returned from another method, such as ISecurityInfo::GetCurrentTrustee. Then the consumer calls ITrusteeAdmin::CompareTrustees, and the provider compares the trustees and returns the result of the comparison in the HRESULT, as well as any errors encountered.

To set or modify properties for a trustee, the consumer allocates and initializes both a TRUSTEE structure and an array of DBPROP structures. For example, to change the trustee's password, the consumer allocates two DBPROP structures. The first DBPROP contains a DBPROP_TRUSTEE_AUTHENTICATION property for the trustee's original password, and the second DBPROP contains a DBPROP_TRUSTEE_NEWAUTHENTICATION property for the new password. Then the consumer allocates and initializes a DBPROPSET structure, sets the rgProperties element to point to the array of DBPROP structures, and calls ITrusteeAdmin::SetTrusteeProperties. The provider changes the properties, and any errors are returned to the consumer by using the HRESULT and the dwStatus element of any DBPROP structure that had an error. (For more information about setting property values, see "Setting Property Values" in the OLE DB Programmer's Reference.)

To get the properties for a trustee, the consumer allocates a TRUSTEE structure and initializes it. If the consumer wants all the trustee properties, it can simply call ITrusteeAdmin::GetTrusteeProperties right away. Otherwise, the consumer allocates an array of DBPROPID values, one for each property that it wants to get. Then the consumer allocates and initializes a DBPROPIDSET structure, sets the rgPropertyIDs element in the DBPROPIDSET structure to point to the array of DBPROPID values, sets the cPropertyIDs element to the number of properties in the array, and sets the guidPropertySet element to DBPROPSET_TRUSTEE. The consumer then calls ITrusteeAdmin::GetTrusteeProperties.

The provider gets the properties and allocates an array of DBPROP structures, which it fills in, and a DBPROPSET structure. The provider sets the rgProperties element in the DBPROPSET structure to point to the array of DBPROP structures and returns a pointer to the DBPROPSET structure to the consumer. Any errors are returned to the consumer by using the HRESULT return code and the dwStatus element of any DBPROP structures that had an error. The consumer releases the DBPROPSET structure when it is finished with it.

For more information on getting property values, see "Getting Property Values" in the OLE DB Programmer's Reference.

ITrusteeGroupAdmin Methods

ITrusteeGroupAdmin methods allow the consumer to add a trustee to a group trustee, remove a trustee from the group, and determine whether a specific trustee is a member of a group. These methods also allow the consumer to get the complete list of trustees in a group and to find out which groups a trustee belongs to.

To add one trustee to another trustee that represents a group of trustees, the consumer allocates two TRUSTEE structures and initializes them. One trustee is the member trustee, and the other is the group trustee, also called the membership trustee. (A member trustee may be either a user trustee or a group trustee. Membership trustees are only group trustees; they never have the TrusteeType element in the TRUSTEE structure set to TRUSTEE_IS_USER because a user trustee cannot have members.) Then the consumer calls ITrusteeGroupAdmin::AddMember, and the provider adds the member trustee to the membership trustee. Any errors are returned to the consumer by using the HRESULT.

To remove a trustee from a membership trustee, the consumer allocates two TRUSTEE structures—one member trustee and one membership trustee—and initializes them. Then the consumer calls ITrusteeGroupAdmin::DeleteMember, and the provider removes the member trustee from the membership trustee. Any errors are returned to the consumer by using the HRESULT.

To determine whether a trustee is a member of a membership trustee, the consumer allocates two TRUSTEE structures—one member trustee and one membership trustee—and initializes them. Then the consumer calls ITrusteeGroupAdmin::IsMember, passing a pointer to a BOOL variable. The provider checks to determine whether or not the member trustee is in the membership trustee's collection of trustees and sets the BOOL variable depending on the outcome. Any errors are returned to the consumer by using the HRESULT.

To get a list of the trustees in a membership trustee, the consumer allocates a TRUSTEE structure for a membership trustee and initializes it and then calls ITrusteeGroupAdmin::GetMembers. The provider allocates an array of TRUSTEE structures and initializes them from the membership list of the membership trustee and then returns a pointer to the array of TRUSTEE structures. Any errors are returned to the consumer by using the HRESULT. The consumer releases the array of TRUSTEE structures when it is finished with it.

To get a list of the membership trustees to which a trustee belongs, the consumer allocates a TRUSTEE structure and initializes it and then calls ITrusteeGroupAdmin::GetMemberships. The provider allocates an array of TRUSTEE structures large enough to hold all the membership trustees to which the member trustee belongs and initializes the structures from the collection of trustees. The provider returns a pointer to the array of TRUSTEE structures. Any errors are returned to the consumer by using the HRESULT. The consumer releases the array of TRUSTEE structures when it is finished with it.