NspiBind (Opnum 0)

The NspiBind method initiates a session between a client and the NSPI 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 value containing a set of bit flags. The server MUST ignore values other than the bit flag fAnonymousLogin.

pStat: A pointer to a STAT block describing a logical position in a specific address book container. This parameter is used to specify both input parameters from the client and return values from the NSPI server.

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

contextHandle: An RPC context handle as specified in section 2.3.9.

Return Values: The server returns a long value specifying 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.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. If the server returns any return value other than Success, the server MUST return a NULL for the output parameter pServerGuid.

  3. The server MAY<11> 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.

  4. 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<12> ignore this request.

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

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

  7. 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 NSPI server. The NSPI server MAY<14> use a different GUID for each RPC connection. Each NSPI server MUST use a different GUID.

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