Share via

3.1.5.3.1 SamrQueryDisplayInformation3 (Opnum 51)

  • Article

The SamrQueryDisplayInformation3 method obtains a listing of accounts in ascending name-sorted order, starting at a specified index.

 long SamrQueryDisplayInformation3(
   [in] SAMPR_HANDLE DomainHandle,
   [in] DOMAIN_DISPLAY_INFORMATION DisplayInformationClass,
   [in] unsigned long Index,
   [in] unsigned long EntryCount,
   [in] unsigned long PreferredMaximumLength,
   [out] unsigned long* TotalAvailable,
   [out] unsigned long* TotalReturned,
   [out, switch_is(DisplayInformationClass)] 
     PSAMPR_DISPLAY_INFO_BUFFER Buffer
 );

DomainHandle: An RPC context handle, as specified in section 2.2.7.2, representing a domain object.

DisplayInformationClass: An enumeration (see section 2.2.8.12) that indicates the type of accounts, as well as the type of attributes on the accounts, to return via the Buffer parameter.

Index: A cursor into an account-name–sorted list of accounts.

EntryCount: The number of accounts that the client is requesting on output.

PreferredMaximumLength: The requested maximum number of bytes to return in Buffer; this value overrides EntryCount if this value is reached before EntryCount is reached.

TotalAvailable: The number of bytes required to see a complete listing of accounts specified by the DisplayInformationClass parameter.

TotalReturned: The number of bytes returned.<53>

Buffer: The accounts that are returned.

This protocol asks the RPC runtime, via the strict_context_handle attribute, to reject the use of context handles created by a method of a different RPC interface than this one, as specified in [MS-RPCE] section 3.

Upon receiving this message, the server MUST process the data from the message subject to the following constraints:

  1. The server MUST return an error if DomainHandle.HandleType is not equal to "Domain".

  2. DomainHandle.GrantedAccess MUST have the required access specified in section 3.1.2.2. Otherwise, the server MUST return STATUS_ACCESS_DENIED.

  3. This method MUST return a set of database objects, sorted by their sAMAccountName attribute value, that match the following criteria for the given DisplayInformationClass.

    DisplayInformationClass

    Database object criteria

    DomainDisplayUser

    All user objects (or those derived from user) in the domain referenced by DomainHandle.Object with userAccountControl containing the UF_NORMAL_ACCOUNT bit.

    DomainDisplayMachine

    All user objects (or those derived from user) in the domain referenced by DomainHandle.Object with userAccountControl containing the UF_WORKSTATION_TRUST_ACCOUNT or UF_SERVER_TRUST_ACCOUNT bit.

    DomainDisplayGroup

    All group objects (or those derived from group) in the domain referenced by DomainHandle.Object with groupType equal to GROUP_TYPE_SECURITY_UNIVERSAL or GROUP_TYPE_SECURITY_ACCOUNT.

    DomainDisplayOemUser

     All user objects (or those derived from user) in both the account domain and the built-in domain with userAccountControl containing the UF_NORMAL_ACCOUNT bit.

    DomainDisplayOemGroup

    All group objects (or those derived from group) in both the account domain and the built-in domain with groupType equal to GROUP_TYPE_SECURITY_UNIVERSAL or GROUP_TYPE_SECURITY_ACCOUNT.

  4. Let L be a list of accounts, sorted by sAMAccountName, that match the above criteria. If the Index parameter is nonzero, the server MUST return objects starting from the position in L implied by the implementation-specific cookie (carried in the Index parameter). If the Index parameter is zero, the server MUST start at the beginning of L. If the implementation-specific cookie refers to an object that has been deleted since the time at which the cookie was created, the server MUST return objects, if any, starting from the next position in L.

  5. For each candidate object to return, the server MUST fill an element in the Buffer output parameter according to the following table.

    Element field

    Value

    Index

    Any unsigned integer such that there are no duplicates in the set of values returned in Buffer; that is, each element has a unique Index. There is no requirement on the ordering of Index values.<54>

    Rid

    RID of the objectSid attribute.

    AccountControl

    userAccountControl attribute value.

    AccountName

    sAMAccountName attribute value.

    AdminComment

    description attribute value.

    FullName

    displayName attribute value.

    Attributes

    See section 3.1.5.14.7 for a message processing specification.

    A call with DisplayInformationClass set to DomainDisplayOemUser or DomainDisplayOemGroup MUST behave identically to a call with DisplayInformationClass set to DomainDisplayUser or DomainDisplayGroup, respectively, with the following exceptions:

    • The RPC_UNICODE_STRING structures in the Oem cases of DisplayInformationClass MUST be translated to RPC_STRING structures using the OEM code page.

    • The value returned in TotalAvailable MUST be set to zero.

  6. If a processing error occurs, the server MUST return that error. Otherwise, the server MUST return STATUS_SUCCESS.