Share via

3.1.5.2.1 SamrEnumerateDomainsInSamServer (Opnum 6)

  • Article

The SamrEnumerateDomainsInSamServer method obtains a listing of all domains hosted by the server side of this protocol.

 long SamrEnumerateDomainsInSamServer(
   [in] SAMPR_HANDLE ServerHandle,
   [in, out] unsigned long* EnumerationContext,
   [out] PSAMPR_ENUMERATION_BUFFER* Buffer,
   [in] unsigned long PreferedMaximumLength,
   [out] unsigned long* CountReturned
 );

ServerHandle: An RPC context handle, as specified in section 2.2.7.2, representing a server object.

EnumerationContext: This value is a cookie that the server can use to continue an enumeration on a subsequent call. It is an opaque value to the client. To initiate a new enumeration, the client sets EnumerationContext to zero. Otherwise the client sets EnumerationContext to a value returned by a previous call to the method.

Buffer: A listing of domain information, as described in section 2.2.7.10.

PreferedMaximumLength: The requested maximum number of bytes to return in Buffer.

CountReturned: The count of domain elements returned in Buffer.

This method 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.

On 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 ServerHandle.HandleType is not equal to "Server".

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

  3. The server MUST enable a client to obtain a listing, without duplicates, of the following two values: the name attribute of the account domain object and the name attribute of the built-in domain object.

  4. EnumerationContext MUST be used to allow the client implementation to pass back to the server, on a subsequent call, information on the last database object that was returned using EnumerationContext.

  5. Servers SHOULD<48> validate that EnumerationContext is an expected value for the server's implementation.

  6. The server SHOULD<49> fill Buffer.Buffer with as many entries as possible, such that not more than PreferedMaximumLength bytes are returned in Buffer.Buffer. If the server returns more than PreferedMaximumLength bytes, the difference between PreferedMaximumLength and the actual number of bytes returned MUST be less than the maximum size, in bytes, of one entry in the array Buffer.Buffer.

  7. Each element of Buffer.Buffer MUST represent one database object that matches the criteria from item 2 above, and MUST be filled as follows:

    1. Buffer.Buffer.Name is the name attribute value of the database object.

    2. Buffer.Buffer.RelativeId is 0.

  8. On output, CountReturned MUST equal Buffer.EntriesRead.

  9. STATUS_MORE_ENTRIES MUST be returned if the server returns less than all of the database objects in Buffer.Buffer because of the PreferedMaximumLength restriction described above. Note that this return value is not an error status.

  10. If there are no entries or Buffer.Buffer contains all matching database objects that remain, the server MUST return STATUS_SUCCESS.