3.2.4.12 NetrGetJoinInformation (Opnum 20)

  • Article

The NetrGetJoinInformation method retrieves details about the workgroup or domain to which the specified computer is joined.

 unsigned long NetrGetJoinInformation(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in, out, string] wchar_t** NameBuffer,
   [out] PNETSETUP_JOIN_STATUS BufferType
 );

ServerName: A WKSSVC_IMPERSONATE_HANDLE structure (section 2.2.2.2) that specifies the server (2). The client MUST map this structure to an RPC binding handle ([C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

NameBuffer: A pointer to the address of the buffer that receives the name of the domain or workgroup to which the computer is joined, and that also specifies the computer name as input. The server MUST ignore this parameter on input.

BufferType: A pointer to a value from the NETSETUP_JOIN_STATUS enumeration (section 2.2.3.1) that specifies the status of a workstation.

Return Values: When the message processing result meets the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

The following statements define the sequence of message-processing operations.

  1. The server (2) MUST retrieve the RPC protocol sequence used for the current call ([MS-RPCE] section 3.1.3.4.1), specifying the server binding handle maintained by the RPC runtime ([C706] section 6.2.1). If that RPC protocol sequence is not NCACN_NP, the server SHOULD return RPC_S_PROTSEQ_NOT_SUPPORTED.<56>

  2. The server MUST check that the caller has been granted access rights using the algorithm in the Access Control Abstract Data Model (section 3.2.1.1), with Access Request mask initialized to WKSTA_NETAPI_QUERY; if not, the server MUST return ERROR_ACCESS_DENIED.

  3. The server MUST impersonate the client by invoking the StartImpersonatingClient task (section 3.2.4.29.6). If this operation fails, the server MUST return an error.

  4. The server MUST compute the response in the following way.

    • If DomainNameFQDN (section 3.2.1.5) is set to NULL, BufferType is set to NetSetupUnjoined, and NameBuffer is set to NULL.

    • Else if DomainSid is set to NULL, BufferType is set to NetSetupWorkgroupName (section 2.2.3.1) and NameBuffer is set to DomainNameNetBIOS (section 3.2.1.5).

    • Else BufferType is set to NetSetupDomainName (section 2.2.3.1) and NameBuffer is set to DomainNameFQDN.

  5. The server MUST stop impersonating the client by invoking the StopImpersonatingClient task (section 3.2.4.29.7).

If no errors occur, the server MUST return NERR_Success.