3.1.5.1.1 SamrConnect5 (Opnum 64)

The SamrConnect5 method obtains a handle to a server object.

 long SamrConnect5(
   [in, unique, string] PSAMPR_SERVER_NAME ServerName,
   [in] unsigned long DesiredAccess,
   [in] unsigned long InVersion,
   [in] [switch_is(InVersion)] SAMPR_REVISION_INFO* InRevisionInfo,
   [out] unsigned long* OutVersion,
   [out, switch_is(*OutVersion)] SAMPR_REVISION_INFO* OutRevisionInfo,
   [out] SAMPR_HANDLE* ServerHandle
 );

ServerName: The null-terminated NETBIOS name of the server; this parameter MAY<44> be ignored on receipt.

DesiredAccess: An ACCESS_MASK that indicates the access requested for ServerHandle on output. For a listing of possible values, see section 2.2.1.3.

InVersion: Indicates which field of the InRevisionInfo union is used.

InRevisionInfo: Revision information. For details, see the definition of the SAMPR_REVISION_INFO_V1 structure, which is contained in the SAMPR_REVISION_INFO union.

OutVersion: Indicates which field of the OutRevisionInfo union is used.

OutRevisionInfo: Revision information. For details, see the definition of the SAMPR_REVISION_INFO_V1 structure, which is contained in the SAMPR_REVISION_INFO union.

ServerHandle: An RPC context handle, as specified in section 2.2.7.2.

Upon receiving this message, the server MUST process the data from the message subject to the following constraints:

1. The server MUST translate the following bits in DesiredAccess according to the following table. Translate means to remove the "Incoming Bit" and replace with the "Translated Bits".

   Incoming bit	Translated bits
   GENERIC_READ	SAM_SERVER_READ
   GENERIC_WRITE	SAM_SERVER_WRITE
   GENERIC_EXECUTE	SAM_SERVER_EXECUTE
   GENERIC_ALL	SAM_SERVER_ALL_ACCESS

2. Let S be the server object in the account domain.

3. Let GrantedAccess be the union of all bits in the DesiredAccess column in the following table, where the client has the specified access (shown in the Access Mask column) on the ntSecurityDescriptor on S. [MS-ADTS] section 5.1.3.3.3 specifies how to determine the client's access.

   DesiredAccess	Access mask
   SAM_SERVER_CONNECT	ACTRL_DS_READ_PROP
   SAM_SERVER_SHUTDOWN	ACTRL_DS_WRITE_PROP
   SAM_SERVER_INITIALIZE	ACTRL_DS_WRITE_PROP
   SAM_SERVER_CREATE_DOMAIN	ACTRL_DS_WRITE_PROP
   SAM_SERVER_ENUMERATE_DOMAINS	ACTRL_DS_READ_PROP
   SAM_SERVER_LOOKUP_DOMAIN	ACTRL_DS_READ_PROP
   ACCESS_SYSTEM_SECURITY	ACCESS_SYSTEM_SECURITY
   WRITE_OWNER	WRITE_OWNER
   WRITE_DAC	WRITE_DAC
   DELETE	DELETE

4. If GrantedAccess is 0, the server MUST return STATUS_ACCESS_DENIED.

5. If DesiredAccess contains the MAXIMUM_ALLOWED bit, the server MUST create and return a SamContextHandle (section 3.1.1.10) via ServerHandle, with its fields initialized as follows:

   • SamContextHandle.HandleType = "Server"

   • SamContextHandle.Object = S

   • SamContextHandle.GrantedAccess = GrantedAccess

6. If DesiredAccess does not contain the MAXIMUM_ALLOWED bit, the following constraint MUST be satisfied:

   • If DesiredAccess contains bits not in GrantedAccess, the server MUST return STATUS_ACCESS_DENIED. Otherwise, the server MUST create and return a SamContextHandle (section 3.1.1.10) via ServerHandle, with its fields initialized as follows:

     • SamContextHandle.HandleType = "Server"

     • SamContextHandle.Object = S

     • SamContextHandle.GrantedAccess = DesiredAccess

7. If InVersion is not equal to 1, the server MUST return STATUS_NOT_SUPPORTED.

8. The server MUST set OutVersion to 1 and OutRevisionInfo.Revision to 3. The remaining fields of OutRevisionInfo MUST be set to zero.

9. If any processing error occurred, the server MUST return that error. Otherwise, the server MUST return STATUS_SUCCESS.