3.1.4.1 EcDoConnectEx Method (Opnum 10)

The EcDoConnectEx method establishes a new Session Context with the server. The Session Context is persisted on the server until the client disconnects by using the EcDoDisconnect method, as specified in section 3.1.4.3. The EcDoConnectEx method returns a session context handle to be used by a client in subsequent calls.

 long __stdcall EcDoConnectEx(
     [in] handle_t hBinding,
      [out, ref] CXH * pcxh,
      [in, string] unsigned char * szUserDN,
      [in] unsigned long ulFlags,
      [in] unsigned long ulConMod,
      [in] unsigned long cbLimit,
      [in] unsigned long ulCpid,
      [in] unsigned long ulLcidString,
      [in] unsigned long ulLcidSort,
      [in] unsigned long ulIcxrLink,
      [in] unsigned short usFCanConvertCodePages,
      [out] unsigned long * pcmsPollsMax,
      [out] unsigned long * pcRetry,
      [out] unsigned long * pcmsRetryDelay,
      [out] unsigned short * picxr,
      [out, string] unsigned char **szDNPrefix,
      [out, string] unsigned char **szDisplayName,
      [in] unsigned short rgwClientVersion[3],
      [out] unsigned short rgwServerVersion[3],
      [out] unsigned short rgwBestVersion[3],
      [in, out] unsigned long * pulTimeStamp,
      [in, size_is(cbAuxIn)] unsigned char rgbAuxIn[],
      [in] unsigned long cbAuxIn,
      [out, length_is(*pcbAuxOut), size_is(*pcbAuxOut)] unsigned char rgbAuxOut[],
      [in, out] SMALL_RANGE_ULONG *pcbAuxOut
 );

hBinding: A valid RPC binding handle.

pcxh: A session context handle for the client. On success, the server MUST return a unique value to be used as a session context handle.

On failure, the server MUST return a zero value as the session context handle.

szUserDN: The DN of the user who is calling the EcDoConnectEx method in a directory service. The value of the szUserDN parameter is similar to the following: "/o=First Organization/ou=First Administrative Group/cn=recipients/cn=janedow".

ulFlags: A flag value that designates the type of connection being established. On input, this parameter contains connection bits that MUST be set; all flag values not in the following table are reserved connection flags. 

ulConMod: A client-derived 32-bit hash value of the DN passed in the szUserDN parameter. The server determines which public folder replica to use when accessing public folder information when more than one replica of a folder exists. The hash can be used to distribute client access across replicas in a deterministic way for load balancing.

cbLimit: MUST be set to zero when sent and MUST be ignored when received.

ulCpid: The code page in which text data is sent. If the Unicode format is not requested by the client on subsequent calls that use this Session Context, the ulCpid parameter sets the code page to be used in subsequent calls.

ulLcidString: The local ID for everything other than sorting.

ulLcidSort: The local ID for sorting.

ulIcxrLink: A value used to link the Session Context created by this call with a currently existing Session Context on the server. To request Session Context linking, the client MUST pass the value of 0xFFFFFFFF. To link to an existing Session Context, this value is the session index value returned in the piCxr parameter from a previous call to the EcDoConnectEx method. In addition to passing the session index in the ulIcxrLink parameter, the client sets the pulTimeStamp parameter to the value that was returned in the pulTimeStamp parameter from the previous call to the EcDoConnectEx method. These two values MUST be used by the server to identify an active session with the same session index and session creation time stamp. If a session is found, the server MUST link the Session Context created by this call with the one found.<8>

A server allows Session Context linking for the following reasons:

1. To consume a single Client Access License (CAL) for all the connections made from a single client computer. This gives a client the ability to open multiple independent connections using more than one Session Context on the server but be seen to the server as only consuming a single CAL.<9>

2. To get pending notification information for other sessions on the same client computer. For details, see [MS-OXCNOTIF].

Note that the ulIcxrLink parameter is defined as a 32-bit value. Other than passing 0xFFFFFFFF for no Session Context linking, the server only uses the low-order 16 bits as the session index. This value is the value returned in the piCxr parameter from a previous call to the EcDoConnectEx method, which is the session index and defined as a 16-bit value.

usFCanConvertCodePages: This parameter is reserved. The client MUST pass a value of 0x0001.

pcmsPollsMax: An implementation-dependent value that specifies the number of milliseconds that a client waits between polling the server for event information. If the client or server does not support making asynchronous RPCs for notifications as specified in section 3.3.4.1, or the client is unable to receive notifications via UDP datagrams, as specified in [MS-OXCNOTIF] section 3.2.5.4 and [MS-OXCNOTIF] section 3.2.5.5.2, the client can poll the server to determine whether any events are pending for the client.

pcRetry: An implementation-dependent value that specifies the number of times a client retries future RPCs using the session context handle returned in this call. This is for client RPCs that fail with RPC status code RPC_S_SERVER_TOO_BUSY (0x000006BB). This is a suggested retry count for the client and is not to be enforced by the server. For more details about circumstances under which the RPC_S_SERVER_TOO_BUSY status code is returned, see [MS-OXCROPS] section 3.2.4.2. For more details about how the client handles the RPC_S_SERVER_TOO_BUSY status code, see section 3.2.4.4.

pcmsRetryDelay: An implementation-dependent value that specifies the number of milliseconds a client waits before retrying a failed RPC. If any future RPC to the server using the session context handle returned in this call fails with RPC status code RPC_S_SERVER_TOO_BUSY (0x000006BB), the client waits the number of milliseconds specified in this output parameter before retrying the call. The number of times a client retries is returned in the pcRetry parameter. This is a suggested delay for the client and is not to be enforced by the server.

piCxr: A session index value that is associated with the session context handle returned from this call. This value in conjunction with the session creation time stamp value returned in the pulTimeStamp parameter will be passed to a subsequent call to the EcDoConnectEx method if the client requests to link two Session Contexts.<10> The server MUST NOT assign the same session index value to two active Session Contexts. The server is free to return any 16-bit value for the session index.

The server MUST also use the session index when returning 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, to tell the client which Session Context has pending notifications. If Session Contexts are linked, a RopPending ROP response can be returned for any linked Session Context.

szDNPrefix: An implementation-dependent value that specifies a DN prefix that is used to build message recipients. An empty value indicates that there is nothing to prepend to recipient entries on messages.

szDisplayName: The display name of the user associated with the szUserDN parameter.

rgwClientVersion: The client protocol version that the server uses to determine what protocol functionality the client supports. For more details about how version numbers are interpreted from the wire data, see section 3.2.4.1.3.

rgwServerVersion: The server protocol version that the client uses to determine what protocol functionality the server supports. For details about how version numbers are interpreted from the wire data, see section 3.1.4.1.3.

rgwBestVersion: The minimum client protocol version that the server supports. This information is useful if the call to the EcDoConnectEx method fails with return code ecVersionMismatch. On success, the server returns the value passed in the rgwClientVersion parameter by the client. The server cannot perform any client protocol version negotiation. The server can either return the minimum client protocol version required to access the server and fail the call with ecVersionMismatch (0x80040110) or allow the client and return the value passed by the client in the rgwClientVersion parameter. The server implementation sets the minimum client protocol version that is supported by the server. For details about how version numbers are interpreted from the wire data, see section 3.1.4.1.3.1.

pulTimeStamp: The creation time of the newly created Session Context. On input, a value used with the ulIcxrLink parameter to link the Session Context created by this call with an existing Session Context. If the ulIcxrLink parameter is not set to 0xFFFFFFFF, the client MUST pass in the value of the pulTimeStamp parameter returned from the server on a previous call to the EcDoConnectEx method. For more details, see the ulIcxrLink and piCxr parameter descriptions earlier in this section. If the server supports Session Context linking, the server verifies that there is a Session Context state with the unique identifier in the ulIcxrLink parameter, and the Session Context state has a creation time stamp equal to the value passed in this parameter. If so, the server MUST link the Session Context created by this call with the one found. If no such Session Context state is found, the server does not fail the EcDoConnectEx method call but simply does not link the Session Contexts.<11>

On output, the server has to return a time stamp in which the new Session Context was created. The server saves the Session Context creation time stamp within the Session Context state for later use if a client attempts to link Session Contexts.

rgbAuxIn: An auxiliary payload buffer prefixed by an RPC_HEADER_EXT structure, as specified in section 2.2.2.1. Information stored in this structure determines how to interpret the data that follows the structure. The length of the auxiliary payload buffer that includes the RPC_HEADER_EXT structure is contained in the cbAuxIn parameter.

For details about how to access the embedded auxiliary payload buffer, see section 3.1.4.1.1. For details about how to interpret the auxiliary payload data, see section 3.1.4.1.2.

cbAuxIn: The length of the rgbAuxIn parameter. If this value on input is larger than 0x00001008 bytes in size, the server SHOULD<12> fail with the RPC status code RPC_X_BAD_STUB_DATA (0x000006F7). If this value is greater than 0x00000000 and less than 0x00000008, the server SHOULD<13> fail with ecRpcFailed (0x80040115). For more information on returning RPC status codes, see [C706].

rgbAuxOut: An auxiliary payload buffer prefixed by an RPC_HEADER_EXT structure (section 2.2.2.1). On output, the server can return auxiliary payload data to the client in this parameter. The server MUST include an RPC_HEADER_EXT structure before the auxiliary payload data.

For details about how to access the embedded auxiliary payload buffer, see section 3.1.4.1.1. For details about how to interpret the auxiliary payload data, see section 3.1.4.1.2.

pcbAuxOut: The length of the rgbAuxOut parameter. If this value on input is larger than 0x00001008, the server MUST fail with the RPC status code RPC_X_BAD_STUB_DATA (0x000006F7).

On output, this parameter contains the size of the data to be returned in the rgbAuxOut parameter.

Return Values: If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code or one of the protocol-defined error codes listed in the following table.

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