3.1.4.7.8 LsarEnumerateTrustedDomains (Opnum 13)

  • Article

The LsarEnumerateTrustedDomains method is invoked to request a list of trusted domain objects in the server's database. The method can be called multiple times to return its output in fragments.

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

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

EnumerationContext: A pointer to a context value that is used to resume enumeration, if necessary.

EnumerationBuffer: A pointer to a structure that will contain the results of the enumeration.

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.

0xC0000105

STATUS_MORE_ENTRIES

More information is available to successive calls.

0xC000001A

STATUS_NO_MORE_ENTRIES

No more entries are available from the enumeration.

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.

This method differs from the LsarEnumerateTrustedDomainsEx method in one significant way-in mixed-mode forests, this method returns to the caller an entire set of domains within the forest by enumerating all the cross-referenced objects in Active Directory in addition to domains that are trusted explicitly.

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.

When enumerating trusted domain objects for this message, the server MUST limit the trusted domain objects returned to the following subset only:

  • Outbound Trusts: The trust direction has the TRUST_DIRECTION_OUTBOUND bit set.

  • Uplevel or Downlevel Trusts: The trust type is TRUST_TYPE_DOWNLEVEL or TRUST_TYPE_UPLEVEL.

  • Non-uplevel-only Trusts: The Trust Attributes field does not have the TRUST_ATTRIBUTE_UPLEVEL_ONLY bit set.

Trust types and attributes are specified in [MS-ADTS] section 6.1.6.

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.