3.2.4.3 FAX_ClientEventQueueEx (Opnum 3)

The FAX_ClientEventQueueEx (Opnum 3) method is called by the fax server (acting as an RPC client for this call) when it needs to deliver an extended fax event to the fax client (acting as an RPC server for this call). The fax client registers for notifications with the fax server by calling either FAX_StartServerNotificationEx (section 3.1.4.1.101) or FAX_StartServerNotificationEx2 (section 3.1.4.1.102). In this call, the fax client MUST pass a fax client notification context, which the fax server MUST pass back to the fax client when it sends an event. This is done to provide a security layer, by verifying that the notifications are coming from an expected source.

Data in FAX_ClientEventQueueEx is serialized. Pointers to variable-size data (such as strings) are replaced with offsets from the beginning of the buffer.

In response, the fax client MUST validate the notification context in the hClientContext argument, which is sent by the fax server, to ensure that this is a valid notification context created with a successful FAX_OpenConnection (section 3.2.4.5) method call for which FAX_CloseConnection (section 3.2.4.4) was not already successfully called. If the validation fails, the fax client MUST abort the operation and MUST return ERROR_SUCCESS. If the notification context is valid, the fax client MUST accept notifications for fax client events.

 error_status_t FAX_ClientEventQueueEx(
   [in, ref] RPC_FAX_HANDLE hClientContext,
   [in, ref, size_is(dwDataSize)] const LPBYTE lpbData,
   [in] DWORD dwDataSize
 );

hClientContext: A fax data type indicating a context handle for this call.

lpbData: A pointer to a FAX_EVENT_EX (section 2.2.67) or FAX_EVENT_EX_1 (section 2.2.68) structure. The data is serialized. Pointers to variable size data (such as strings) are replaced with offsets from the beginning of the buffer. Since the client is to be notified of each event separately, in this case ORing of events is not allowed.

If the client requested extended events by calling FAX_StartServerNotificationEx, the client MUST use a FAX_EVENT_EX. If the client called FAX_StartServerNotificationEx2 to receive these events, the client MUST use a FAX_EVENT_EX_1.

dwDataSize: A DWORD ([MS-DTYP] section 2.2.9) containing the size of the buffer pointed to by the lpbData parameter.

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_INVALID_DATA

0x0000000D

The hClientContext handle is not a valid subscription context handle returned by FAX_StartServerNotificationEx or FAX_StartServerNotificationEx2.<218>

ERROR_OUTOFMEMORY

0x0000000E

The fax client needs to make a copy of the data provided by the fax server in the lpbData buffer, and the fax client failed to allocate dwDataSize bytes to hold this copy.

ERROR_INTERNAL_ERROR

0x0000054F

The fax client failed to recognize the custom marshaled FAX_EVENT_EX or FAX_EVENT_EX_1 provided by the fax server in the lpbData buffer.

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

Data in FAX_ClientEventQueueEx is serialized. Pointers to variable size data (such as strings) are replaced with offsets from the beginning of the buffer.