3.2.4.5 FAX_OpenConnection (Opnum 0)

  • Article

The FAX_OpenConnection (Opnum 0) method returns the context handle that is supplied by the FAX_StartServerNotification family of calls. This is done to provide a security layer, by verifying that the notifications are coming from an expected source.

In response, the fax client (acting as an RPC server for this call) SHOULD validate the notification context referred by the Context argument to ensure this is a valid notification context previously submitted by the fax client to a FAX_StartServerNotification (section 3.1.4.1.100), FAX_StartServerNotificationEx (section 3.1.4.1.101), or FAX_StartServerNotificationEx2 (section 3.1.4.1.102) method call through the argument with the same name (Context). The fax client MUST validate whether the fax server (acting as an RPC client for this call) uses an authentication scheme better than RPC_C_AUTHN_LEVEL_PKT_PRIVACY. An RPC client always uses a packet authentication level, as specified in [MS-RPCE] section 3.3.1.5.2.

On success, the fax client MUST open a notification session to the fax server and MUST return the same Context in the FaxHandle argument that was passed by the fax server in the FaxHandle argument.

 error_status_t FAX_OpenConnection(
   [in] handle_t hBinding,
   [in] unsigned __int64 Context,
   [out] PRPC_FAX_HANDLE FaxHandle
 );

hBinding: Handle provided by the client RPC layer when the RPC call is made.

Context: A ULONG64 ([MS-DTYP] section 2.2.51) containing a context information handle. This handle SHOULD match the one supplied to the server when using the FAX_StartServerNotification family of calls. For more information, see the following topics:

§ FAX_StartServerNotification

  • FAX_StartServerNotificationEx

  • FAX_StartServerNotificationEx2

FaxHandle: A pointer to an RPC_FAX_HANDLE indicating a context handle to open. This value is used in other fax client calls.

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

The method requires at least packet-level privacy. The server checks the authentication level of the client. If it is less than RPC_C_AUTHN_LEVEL_PKT_PRIVACY, refuse access. Or there are other access-related problems.

ERROR_INVALID_PARAMETER

0x00000057

An invalid AssyncInfo structure is pointed to by the Context parameter or there are parameter-related problems.

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

The returned PRPC_FAX_HANDLE is the Context parameter cast to a HANDLE.

The FAX_OpenConnection method returns the context handle supplied by the FAX_StartServerNotification family of calls. This is done to provide a security layer, by verifying that the notifications are coming from an expected source.