3.1.4.1.10 FAX_ConnectFaxServer (Opnum 80)

The FAX_ConnectFaxServer (Opnum 80) method is called by the client to create a connection to the fax server.

Protocol version FAX_API_VERSION_0 (0x00000000) fax servers SHOULD NOT implement this method.

If the underlying RPC layer fails this call by returning RPC_S_PROCNUM_OUT_OF_RANGE (0x000006D1), the fax client SHOULD consider the server protocol (and API version) to be FAX_API_VERSION_0 and MAY retry this request by switching to the FaxObs Server Interface (section 3.1.4.2) and calling the FaxObs_ConnectionRefCount (section 3.1.4.2.2) method.

In response, if the bAutoCreateAccountOnConnect field of the FAX_GENERAL_CONFIG (section 2.2.31) structure is set to FALSE, the server MUST validate whether the calling user's authenticated user identity has a fax user account associated on the fax server and MUST validate whether this client's fax user account has any fax user access rights. On success, the server MUST create a connection handle.

The client MUST call the FAX_ConnectionRefCount (section 3.1.4.1.11) method at the end of the session to disconnect the session and close the connection handle. This call MUST include a value of 0x00000000 for the Connect argument as well as the connection handle returned by the server via the FAX_ConnectFaxServer (section 3.1.4.1.10) method as the Handle argument.

If the bAutoCreateAccountOnConnect field of the FAX_GENERAL_CONFIG is set to FALSE and the calling user's authenticated user identity does not have a fax user account associated on the fax server, FAX_ConnectFaxServer MUST fail with ERROR_ACCESS_DENIED.

If the bAutoCreateAccountOnConnect field of the FAX_GENERAL_CONFIG is set to TRUE and the calling user’s authenticated user identity does not have a fax user account associated on the fax server, FAX_ConnectFaxServer MUST create a new fax user account with the default fax user access rights described in section 3.1.4.1.12.

If this call is successful, the client SHOULD retain the RPC binding handle used for the hBinding argument and reuse it as the RPC binding handle input argument for all subsequent fax server calls made, until the connection with the server is disconnected.

 error_status_t FAX_ConnectFaxServer(
   [in] handle_t hBinding,
   [in] DWORD dwClientAPIVersion,
   [out, ref] LPDWORD lpdwServerAPIVersion,
   [out, ref] PRPC_FAX_SVC_HANDLE pHandle
 );

hBinding: The RPC binding handle that is provided by the client RPC layer when the RPC call is made.

dwClientAPIVersion: A DWORD ([MS-DTYP] section 2.2.9) that MUST contain the protocol version (fax API version) of the client module. This value MUST be one of the constants defined in section 2.2.85 (Protocol and Fax API Version Constants). The value determines the specific FAX_ERR error codes that can be returned by the fax server, as described in the following table. If the fax server receives from the fax client a version number greater than the server’s version number, the server MUST accept the request and MUST consider the client version to be the same as the version supported by the fax server.

Value	Meaning
FAX_API_VERSION_0 0x00000000	No FAX_ERR_* values can be returned.
FAX_API_VERSION_1 0x00010000	FAX_ERR_* values in the FAX_ERR 7001-7012 range can be returned.
FAX_API_VERSION_2 0x00020000	FAX_ERR_* values in the FAX_ERR 7001-7013 range can be returned.
FAX_API_VERSION_3 0x00030000	FAX_ERR_* values in the FAX_ERR 7001-7013 range can be returned.

lpdwServerAPIVersion: A pointer to a DWORD that contains the protocol and fax API version of the fax server that is reported back by the fax server to the fax client. This value MUST be one of the constants defined in section 2.2.85.

The fax client SHOULD use this value to determine which fax specific error codes are to be expected from the fax server, and also to determine which fax server methods are implemented by the fax server. The methods which are to be implemented differently depending on the protocol and fax API version have version differences documented in their respective subsections.

pHandle: The connection handle returned by the fax server. The client MUST use this connection handle as the Handle argument for the FAX_ConnectionRefCount call made to disconnect from the fax server at the end of the session.

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return the following error code, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The bAutoCreateAccountOnConnect field of the FAX_GENERAL_CONFIG structure is set to FALSE and the calling user's authenticated user identity does not have a fax user account associated on the fax server, or the does not have any of the access rights defined in ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83).

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol [MS-RPCE].