1.3.2 Method-Based Perspective

The method-based perspective is used to show a common set of operations for each object type. The operations fall into patterns. A list of the patterns and associated methods, along with a description of each pattern, is shown below.

• Open Pattern

  This pattern returns an RPC context handle that references a specific object type. A client uses this pattern by specifying a specific access for the handle in the request, and using the returned handle to call other methods that require the returned handle along with the associated access. For example, calling the method SamrSetInformationDomain requires a domain handle that has been opened with DOMAIN_WRITE_PASSWORD_PARAMS. For more information on the range of accesses for a domain object, see section 2.2.1.4.

  SamrConnect2, SamrConnect4, and SamrConnect5 are distinguished from the other methods in this pattern in that they are the first methods that a client calls prior to a calling any other handle-based methods.

  The methods that follow the open pattern are as follows:

  • SamrConnect5

  • SamrConnect4

  • SamrConnect2

  • SamrOpenDomain

  • SamrOpenGroup

  • SamrOpenAlias

  • SamrOpenUser

• Enumerate Pattern

  This pattern allows a client to obtain a complete list of all objects of a certain type (domain, group, alias, or user).

  The methods that follow the enumerate pattern are as follows:

  • SamrEnumerateDomainsInSamServer

  • SamrEnumerateGroupsInDomain

  • SamrEnumerateAliasesInDomain

  • SamrEnumerateUsersInDomain

• Selective Enumerate Pattern

  This pattern allows a client to obtain a partial list of objects based on the name of the objects. These methods, for example, allow a client to obtain a bounded number of objects from a virtual list of objects sorted alphabetically by name starting with a client-specified prefix, such as "Chr". User interface programs use these methods to allow the end user to quickly find an object, given partial knowledge of the object's name.

  The methods that follow the selective enumerate pattern are as follows:

  • SamrQueryDisplayInformation3

  • SamrQueryDisplayInformation2

  • SamrQueryDisplayInformation

  • SamrGetDisplayEnumerationIndex2

  • SamrGetDisplayEnumerationIndex

• Create Pattern

  This pattern allows specified objects to be created. A handle to the newly created object is returned.

  The methods that follow the create pattern are as follows:

  • SamrCreateGroupInDomain

  • SamrCreateAliasInDomain

  • SamrCreateUser2InDomain

  • SamrCreateUserInDomain

• Query Pattern

  This pattern allows specified attributes of an object to be returned. The client specifies which attributes to return by using an "information level". The information level is an enumeration that the server understands and translates into a specific structure to return; the structure contains the attributes indicated by the information level.

  To retrieve the name of a user, for example, a client specifies the UserAccountNameInformation information level in the SamrQueryInformationUser method.

  The methods that follow the query pattern are as follows:

  • SamrQueryInformationDomain2

  • SamrQueryInformationDomain

  • SamrQueryInformationGroup

  • SamrQueryInformationAlias

  • SamrQueryInformationUser2

  • SamrQueryInformationUser

• Set Pattern

  This pattern allows specified object attributes to be set. The client indicates the attributes that are to be updated by specifying an "information level". Similar to the query pattern of methods, the information level specifies the attributes that are being sent in the request.

  The methods that follow the set pattern are as follows:

  • SamrSetInformationDomain

  • SamrSetInformationGroup

  • SamrSetInformationAlias

  • SamrSetInformationUser2

  • SamrSetInformationUser

• Delete Pattern

  This pattern allows a client to delete a specified object.

  The methods that follow the delete pattern are as follows:

  • SamrDeleteGroup

  • SamrDeleteAlias

  • SamrDeleteUser

• Membership Pattern

  This pattern allows a client to add to, remove from, or query the membership list for either a group or an alias object.

  The methods that follow the membership pattern are as follows:

  • SamrAddMemberToGroup

  • SamrRemoveMemberFromGroup

  • SamrAddMemberToAlias

  • SamrRemoveMemberFromAlias

  • SamrRemoveMemberFromForeignDomain

  • SamrGetMembersInGroup

  • SamrGetMembersInAlias

  • SamrAddMultipleMembersToAlias

  • SamrRemoveMultipleMembersFromAlias

• Membership-Of Pattern

  This pattern allows a client to obtain the groups or aliases that a user or collection of security identifiers (SIDs) is a member of.

  The methods that follow the membership-of pattern are as follows:

  • SamrGetGroupsForUser

  • SamrGetAliasMembership

• Change Password Pattern

  This pattern allows a client to change a password on a user object. The client provides the current password and new password, and the server verifies that the client-presented current password matches the server-persisted current password for the user. If there is a match, the new password is persisted.

  The methods that follow the change password pattern are as follows:

  • SamrChangePasswordUser

  • SamrOemChangePasswordUser2

  • SamrUnicodeChangePasswordUser2

• Lookup Pattern

  This pattern allows a client to translate between a relative identifier (RID) or SID, and a user-friendly display name (the name of the object).

  The methods that follow the lookup pattern are as follows:

  • SamrLookupDomainInSamServer

  • SamrLookupNamesInDomain

  • SamrLookupIdsInDomain

• Security Pattern

  This pattern allows a client to specify or query access control with a granularity of individual objects.

  The methods that follow the security pattern are as follows:

  • SamrSetSecurityObject

  • SamrQuerySecurityObject

• Miscellaneous

  The following methods do not fall into a general pattern; see the message processing sections for details about each one. A brief description of each method follows:

  • SamrGetUserDomainPasswordInformation: This method obtains information about the password policy on the account domain, given a user handle. Applications that allow end users to change their passwords can use this method to display policy information to an end user.

  • SamrGetDomainPasswordInformation: This method is similar to the SamrGetUserDomainPasswordInformation method, except that the server does not enforce any security, and a user handle is not needed.

  • SamrRidToSid: This method returns a SID given a RID returned by any of the methods in this interface.<1>

  • SamrSetDSRMPassword: This method allows a client to set the password on a local account (an account not stored in Active Directory) on a DC. This is useful for recovery scenarios where Active Directory does not start.

  • SamrValidatePassword: This method allows applications that store passwords to validate the strength of the passwords against the account domain policy.

  • SamrSetMemberAttributesOfGroup: This method allows a server to configure extra authorization information associated with a group membership. This method is ignored in DC scenarios.

  • SamrCloseHandle: This method releases server resources associated with the RPC context handle that is passed as a parameter.

  • SamrValidateComputerAccountReuseAttempt: This method validates whether client attempts to re-use a given computer account are permitted.