Share via

3.1.4.1.1 NspiBind (Opnum 0)

  • Article

The NspiBind method initiates a session between a client and the server.

 long NspiBind(
   [in] handle_t hRpc,
   [in] DWORD dwFlags,
   [in] STAT* pStat,
   [in, out, unique] FlatUID_r* pServerGuid,
   [out, ref] NSPI_HANDLE* contextHandle
 );

hRpc: An RPC binding handle parameter, as specified in [C706] section 2.

dwFlags: A DWORD [MS-DTYP] value that contains a set of bit flags. The server MUST ignore values other than the bit flag fAnonymousLogin (0x00000020).

pStat: A pointer to a STAT block that describes a logical position in a specific address book container. This parameter is used to specify input parameters from the client.

pServerGuid: The value NULL or a pointer to a GUID value that is associated with the specific server.

contextHandle: An RPC context handle, as specified in section 2.2.10.

Return Values: The server returns a LONG [MS-DTYP] value that specifies the return status of the method.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

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

  1. If the CodePage field of the input parameter pStat contains the value CP_WINUNICODE, the server MUST return one of the return values specified in section 2.2.1.2. No further constraints are applied to server processing of this method; in this case server behavior is undefined. Note especially that there is no constraint on the data the server returns in any output parameter other than the return value, nor is there any constraint on how or if the server changes its state.

  2. The server MAY make additional validations including but not limited to limiting the number of concurrent connections to any specific client or checking the data access rights of the client. If these checks fail, the server MUST return "LogonFailed".

  3. A value of "fAnonymousLogin" in the input parameter dwFlags indicates that the server did not validate that the client is an authenticated user. The server MAY ignore this request.

  4. Subject to constraint 3, the server MAY authenticate the client. How a server authenticates a client is an implementation-specific detail.

  5. The CodePage field of the input parameter pStat specifies the code page to use in this session. If the server will not service connections using that code page, the server MUST return the error code "InvalidCodepage".

  6. Subject to the prior constraints, if the input parameter pServerGuid is not NULL, the server MUST set the output parameter pServerGuid to a GUID associated with the server. The server MAY use a different GUID for each RPC connection. Each server MUST use a different GUID.

  7. If no other return code has been set, the server MUST return the value "Success".