3.1.4.7.15 LsarQueryForestTrustInformation (Opnum 73)

  • Article

The LsarQueryForestTrustInformation method is invoked to retrieve information about a trust relationship with another forest.

 NTSTATUS LsarQueryForestTrustInformation(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PLSA_UNICODE_STRING TrustedDomainName,
   [in] LSA_FOREST_TRUST_RECORD_TYPE HighestRecordType,
   [out] PLSA_FOREST_TRUST_INFORMATION* ForestTrustInfo
 );

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

TrustedDomainName: The name of the trusted domain to query.

HighestRecordType: The highest ordinal number of forest trust record type that the caller understands.

ForestTrustInfo: Used to return the forest trust information.

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.

0xC000000D

STATUS_INVALID_PARAMETER

One of the supplied arguments was invalid.

0xC00000DD

STATUS_INVALID_DOMAIN_STATE

The domain is in the wrong state of this operation.

0xC00000DF

STATUS_NO_SUCH_DOMAIN

The TrustedDomainName is not a recognized domain name.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

0xC0000225

STATUS_NOT_FOUND

Forest trust information does not exist for this trusted domain object.

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. PolicyHandle.GrantedAccess MUST NOT be considered for this call because the access check MUST happen on the trusted domain object.

TrustedDomainName: The name of the trusted domain object to query.

The server MUST return STATUS_INVALID_DOMAIN_STATE if any of the following conditions is TRUE:

  • The DnsForestName and DnsDomainName fields in DNS Domain Information (see section 3.1.1.1) do not contain the same value.

  • The forestFunctionality specified in [MS-ADTS] section 3.1.1.3.2.27 is not DS_BEHAVIOR_WIN2003 or higher.

  • Active Directory is not running on this machine.

If a trusted domain object by the name TrustedDomainName does not exist, the server MUST return STATUS_NO_SUCH_DOMAIN.

HighestRecordType: The caller sets this argument to the highest LSA_FOREST_TRUST_RECORD_TYPE enum value recognized by the caller. This parameter is ignored by the server.

ForestTrustInfo: Used to return the forest trust information associated with the trusted domain object. This corresponds to the Forest Trust Information abstract data model specified in section 3.1.1.5. Any records of type ForestTrustBinaryInfo and later must be returned to the caller as ForestTrustBinaryInfo type records (sections 2.2.7.21 and 2.2.7.22).

If the trusted domain object is not of the type that supports a forest trust (as determined by the presence or absence of the TRUST_ATTRIBUTE_FOREST_TRANSITIVE attribute), the server MUST return STATUS_INVALID_PARAMETER. If the forest trust information does not exist on a trusted domain object that otherwise can support a forest trust, the server MUST return STATUS_NOT_FOUND.

The server MUST verify that the caller has access to the trusted domain object as specified in section 3.1.4.2.1 with DesiredAccess set to TRUSTED_QUERY_AUTH. There is no method-specific portion of this check.