3.1.4.1.11 FAX_ConnectionRefCount (Opnum 1)

  • Article

The FAX_ConnectionRefCount (Opnum 1) method is called by the client.<73>

In response, the server MUST connect, disconnect, or release a connection between the fax client and the fax server.

If this call is successfully made with a Connect argument value of Connect (0x00000001), 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_ConnectionRefCount(
   [in] handle_t hBinding,
   [in, out] PRPC_FAX_SVC_HANDLE Handle,
   [in] DWORD Connect,
   [out] LPDWORD CanShare
 );

hBinding: The RPC binding handle that is provided by the client RPC layer when the RPC call is made. If the Connect parameter is set to Disconnect (0x00000000), the client SHOULD reuse the RPC binding handle used for the FAX_ConnectFaxServer (section 3.1.4.1.10) call or for the previous call to this method used to connect to the fax server.

Handle: The connection handle that references a connection to the fax server. If Connect is set to 0x00000001 (Connect), a new handle is returned in this parameter. Otherwise, this parameter MUST be set to a handle returned from a previous call to this method, or to FAX_ConnectFaxServer.

Connect: A DWORD ([MS-DTYP] section 2.2.9) value that specifies connection information.

Value

Meaning

Disconnect

0x00000000

Close the fax server connection.

The handle specified in Handle MUST have been returned by a previous call to FAX_ConnectFaxServer or FAX_ConnectionRefCount with a Connect value of 1 (Connect). After this call, the handle in Handle will be invalid and MUST NOT be used in any subsequent calls.

Connect

0x00000001

Connect to the fax server.

Calling FAX_ConnectionRefCount with this value is equivalent to calling FAX_ConnectFaxServer with an API version of FAX_API_VERSION_0.

Release

0x00000002

Release a connection to the fax server.

The handle specified in Handle MUST have been returned by a previous call to FAX_ConnectFaxServer or FAX_ConnectionRefCount with a Connect value of 1 (Connect). After this call, the handle in Handle MUST NOT be used in any subsequent calls except a call to FAX_ConnectionRefCount with a Connect value of 0 (Disconnect).

If FAX_ConnectionRefCount is called in a sequence, and varying values are given for this parameter on the same Handle, the following holds true:

  1. The call sequence SHOULD have values for the Connect argument in the following order:

    1. 1 (Connect): To obtain a valid Handle and connect to the fax server. (This call is optional and can be replaced by a FAX_ConnectFaxServer call.

    2. 2 (Release): Step "1 (Connect)" is mandatory for this call to succeed.

    3. 0 (Disconnect): Step "1 (Connect)" is mandatory for this call to succeed.

  2. The following sequence of calls on the same handle MUST result in an ERROR_INVALID_PARAMETER error:

    1. Consecutive calls with a Connect argument value of 2 (Release) or 0 (Disconnect) without obtaining a valid Handle in between two calls (through step "1 (Connect)" above).

    2. A call with a Connect argument value of 0 (Disconnect) following a call with a Connect argument value of 2 (Release).

CanShare: The server MUST return a nonzero value in the DWORD referenced by this parameter if the fax print queues can be shared as described in section 3.1.1, and a zero value otherwise.<74>

Possible value

Description

0x00000000

The fax print queues can be shared.

0x00000001 — 0xFFFFFFFF

The fax print queues cannot be shared.

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, 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 Connect parameter is set to a value of 0x00000001 (Connect), and the client's fax user account does not have the ALL_FAX_USER_ACCESS_RIGHTS access rights required for the connect operation.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect. This error code is returned if any of the following conditions are met:

§ The Connect parameter is set to a value of 0x00000000 (Disconnect) or to a value of 0x00000002 (Release), and the Handle parameter is set to a NULL value.<75>

§ The Connect parameter is set to a value of 0x00000001 (Connect), and the CanShare parameter is set to a NULL pointer value.<76>

§ The Connect parameter is set to a value other than 0x00000000 (Disconnect), 0x00000001 (Connect), or 0x00000002 (Release).

Fax clients call this method to connect or disconnect from the fax server.

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