3.1.4.7.7 LsarEnumerateTrustedDomainsEx (Opnum 50)

The LsarEnumerateTrustedDomainsEx method is invoked to enumerate trusted domain objects in the server's database. The method is designed to be invoked multiple times to retrieve the data in fragments.

 NTSTATUS LsarEnumerateTrustedDomainsEx(
   [in] LSAPR_HANDLE PolicyHandle,
   [in, out] unsigned long* EnumerationContext,
   [out] PLSAPR_TRUSTED_ENUM_BUFFER_EX EnumerationBuffer,
   [in] unsigned long PreferedMaximumLength
 );

PolicyHandle: An RPC context handle obtained from either LsarOpenPolicy or LsarOpenPolicy2.

EnumerationContext: Used to keep track of the state of the enumeration in cases where the caller obtains its information in several fragments.

EnumerationBuffer: Contains a fragment of requested information.

PreferedMaximumLength: A value that indicates the approximate size of the data to be returned.

Return Values: The following is a summary of the return values that an implementation MUST return, as specified by the message processing that follows.

Return value/code	Description
0x00000000 STATUS_SUCCESS	The request was successfully completed.
0xC0000022 STATUS_ACCESS_DENIED	The caller does not have the permissions to perform this operation.
0x8000001A STATUS_NO_MORE_ENTRIES	No more information is available.
0x00000105 STATUS_MORE_ENTRIES	More information is available by calling this method again.
0xC0000008 STATUS_INVALID_HANDLE	PolicyHandle is not a valid handle.

Processing:

This message takes four arguments:

PolicyHandle: An open handle to the policy object. If the handle is not a valid context handle to the policy object or PolicyHandle.HandleType does not equal "Policy", the server MUST return STATUS_INVALID_HANDLE. The server MUST verify that PolicyHandle grants access as specified in section 3.1.4.2.2 with RequiredAccess set to POLICY_VIEW_LOCAL_INFORMATION.

EnumerationContext: A number that indicates a starting index at which to begin the enumeration. The server MUST always return all trusted domain objects in the same order, starting at the object whose index is EnumerationContext. 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.

The server MUST return STATUS_INVALID_PARAMETER if the EnumerationContext parameter is NULL.

EnumerationBuffer: Used to return the results of enumeration. The server MUST fill EnumerationBuffer with as many trusted domain objects as possible, as determined by PreferedMaximumLength. If the size of all remaining objects is less than or equal to PreferedMaximumLength, the server MUST fill EnumerationBuffer with all objects. If the size of all remaining objects is greater than PreferedMaximumLength, the server MUST fill EnumerationBuffer with objects such that the size of the trusted domain objects returned is greater than or equal to PreferedMaximumLength, but would be less than PreferedMaximumLength if the last object had not been added to EnumerationBuffer. If there are no more objects than are returned in EnumerationBuffer, the server MUST return STATUS_NO_MORE_ENTRIES. If there are more database objects than are returned in EnumerationBuffer, the server MUST set the EnumerationContext value to the index value that would allow it to resume enumeration correctly when this method is called again, and the server MUST return STATUS_MORE_ENTRIES. Note that this return value is not an error status.

PreferedMaximumLength: An indication about the approximate size, in bytes, of the data to be returned. Any unsigned 32-bit value is valid for the PreferedMaximumLength parameter.

If Active Directory is not running on this machine, the server MUST fill 0 objects in EnumerationBuffer, and return STATUS_NO_MORE_ENTRIES.