3.2.4.1 Sending the EcDoConnectEx Method
When issuing the EcDoConnectEx method on the EMSMDB interface, some parameters require additional client-side consideration beyond what is stated in section 3.1.4.1. The parameters for which the client has specific handling are as follows:
hBinding: A valid RPC binding handle that MUST have a server name, protocol sequence, and authentication method defined. Some protocol sequences have named endpoints that MUST be used. For details about how to create a binding handle, see section 2.1.
pcxh: On success, this parameter will contain the session context handle. On failure, this value is NULL. The session context handle MUST be stored on the client and used in subsequent calls on the EMSMDB interface that require a valid session context handle.
ulConMod: The connection modulus hash is determined by the client for a connection. How the client determines the hash value is an implementation detail. The client ensures that for a particular DN passed in the szUserDN parameter, the hash value is the same. It is acceptable to have the same hash value for different DNs. The client is free to send any 32-bit value.
cbLimit: A client MUST pass a value of 0x00000000.
ulIcxrLink: This value is used to link the Session Context that is created by this call with an existing Session Context on the server that was created by a previous call to the EcDoConnectEx method.<28>
A client can link two Session Contexts for the following reasons:
To consume a single CAL for all the connections made from a single client computer. This gives a client the ability to open multiple independent connections by using more than one Session Context on the server but be seen to the server as only consuming a single CAL.<29>
To get pending notification information for other sessions on the same client computer. For details, see [MS-OXCNOTIF].
If a client is not requesting to link two Session Contexts or if this is the first call to the EcDoConnectEx method, the client MUST pass a value of 0xFFFFFFFF.
Note that the ulIcxrLink parameter is defined as a 32-bit value. Other than passing 0xFFFFFFFF if there is no Session Context link, the client passes a value with the high-order 16-bits set to zero, and the low-order 16-bits MUST be the value returned in the piCxr parameter from a previous EcDoConnectEx method call.
usFCanConvertCodePages: The client MUST pass a value of 0x0001.
pcmsPollsMax: On success, this value is the number of milliseconds the client waits before polling the server for notification information. On failure, the value of this field is undefined and SHOULD be ignored. Other more dynamic options are available to the client for receiving notifications from the server. The client saves this value and associates it with the session context handle.
pcRetry: On success, this value is the number of times the client retries a subsequent EMSMDB interface method call that uses the session context handle that is returned in the pcxh parameter. On failure, the value of this field is undefined and SHOULD be ignored. For details about retrying RPCs, see section 3.2.4.4. The client saves this value and associates it with the session context handle.
pcmsRetryDelay: On success, this value is the number of milliseconds a client waits before retrying a subsequent EMSMDB interface method call that uses the session context handle that is returned in the pcxh parameter. On failure, the value of this field is undefined and SHOULD be ignored. The client saves this value and associates it with the session context handle.
piCxr: On success, this value is a 16-bit session index that can be used in conjunction with the value returned in the pulTimeStamp parameter to link two Session Contexts on the server. On failure, the value of this field is undefined and SHOULD be ignored. For details about how to link Session Contexts and the reason why a client might request to do so, see the ulIcxrLink parameter.<30>
The client saves this value and associates it with the session context handle. It is the session index returned in a RopPending ROP response ([MS-OXCROPS] section 2.2.14.3) on calls to the EcDoRpcExt2 method, as specified in section 3.1.4.2. The RopPending ROP response tells the client that a Session Context on the server has pending notifications. If a client links Session Contexts, a RopPending ROP can be returned for any linked Session Context.
rgwClientVersion: The client MUST pass the version number of the highest client protocol version it supports. This value will provide information to the server about the protocol functionality that the client supports. For details about how version numbers are interpreted from the wire data and the expected client behavior, see section 3.2.4.1.3.
rgwServerVersion: On success, this value is the server protocol version that the client uses to determine what protocol functionality the server supports. On failure, the value of this field is undefined and SHOULD be ignored. For details about how version numbers are interpreted from the wire data and the expected server behavior, see section 3.1.4.1.3. The client saves this value and associates it with the session context handle.
pulTimeStamp: If a client requests to link the Session Context that is created by this call to a previously created Session Context, the client MUST pass on input the session creation time stamp returned in the pulTimeStamp parameter on a previous EcDoConnectEx method call. If the client is not requesting to link Session Contexts, the client passes value 0x00000000.<31>
On success, this value is the Session Context creation time stamp. On failure, the value of this field is undefined and SHOULD be ignored. The server saves the Session Context creation time stamp and associates it with the session context handle.