3.1.4.7.9 LsarOpenTrustedDomainByName (Opnum 55)

The LsarOpenTrustedDomainByName method is invoked to open a trusted domain object handle by supplying the name of the trusted domain.

 NTSTATUS LsarOpenTrustedDomainByName(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PRPC_UNICODE_STRING TrustedDomainName,
   [in] ACCESS_MASK DesiredAccess,
   [out] LSAPR_HANDLE* TrustedDomainHandle
 );

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

TrustedDomainName: The name of the trusted domain object.

DesiredAccess: The type of access requested by the caller.

TrustedDomainHandle: Used to return the opened trusted domain handle.

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.
0xC0000034 STATUS_OBJECT_NAME_NOT_FOUND	A trusted domain object by this name was not found.
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. PolicyHandle.GrantedAccess MUST NOT be considered for this call because the access check MUST happen on the trusted domain object.

TrustedDomainName: Contains the name of the trusted domain to be opened. This can be a DNS or a NetBIOS name. If the server cannot locate a trusted domain object by this name in its policy database, the server MUST return STATUS_OBJECT_NAME_NOT_FOUND. The same status code MUST be returned by the server if Active Directory is not running on this machine.

DesiredAccess: The set of rights that the caller attempts to obtain from the trusted domain object, which is access-checked according to section 3.1.4.2.1. There is no method-specific portion of the check. The valid trusted-domain-rights bits are specified in section 2.2.1.1.5, and the security descriptor is specified in section 3.1.1.5.

TrustedDomainHandle: If the request is successful, this parameter is used to return a handle (section 3.1.1.7) to the opened trusted domain object with its fields initialized as follows:

• LsaContextHandle.HandleType = "Trusted Domain"

• LsaContextHandle.Object = the trusted domain object

• LsaContextHandle.GrantedAccess = as specified in section 3.1.4.2.1