3.1.4.2.31 FaxObs_StartClientServer (Opnum 29)

  • Article

The FaxObs_StartClientServer (Opnum 29) method is called by the client to register itself to receive notifications of fax events from the server.

On success, the server MUST start notifying the client about the occurring fax events.

If the server receives a FaxObs_StartClientServer request for a client machine name and client name that are already registered to receive fax event notifications with a previously executed FaxObs_StartClientServer call, the fax server MUST consider the new request a success and keep the existing fax client registration.

To notify the client about a fax event, the server MUST first open a connection with the client by calling the FAX_OpenConnection (section 3.2.4.5) method. Then the fax server MUST notify the client by calling the FAX_ClientEventQueue (section 3.2.4.2) method. Finally, the server SHOULD close the connection with the client by calling the FAX_CloseConnection (section 3.2.4.4) method. <213>

 error_status_t FaxObs_StartClientServer(
   [in] handle_t hBinding,
   [in, string, unique] LPCWSTR MachineName,
   [in, string, unique] LPCWSTR ClientName,
   [in] ULONG64 Context
 );

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

MachineName: A pointer to a null-terminated character string containing the name of the fax client machine. The machine name MUST be NULL for a local machine and a fully qualified domain name (FQDN) for a remote machine.

ClientName: A pointer to a null-terminated character string containing the friendly name of the fax client application. This name MUST be unique for each fax client application running on the same fax client machine.

Context: A ULONG64 ([MS-DTYP] section 2.2.54) value that can be passed to FAX_OpenConnection as a notification context. This context is equivalent to the subscription context used in the Fax Server Interface methods FAX_StartServerNotification (section 3.1.4.1.100), FAX_StartServerNotificationEx (section 3.1.4.1.101), and FAX_StartServerNotificationEx2 (section 3.1.4.1.102), with the difference that the FaxObs Server Interface (section 3.1.4.2) does not have a method similar to FAX_EndServerNotification (section 3.1.4.1.17) that the client calls to close this context.

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_NOT_ENOUGH_MEMORY

0x00000008

The fax server cannot allocate memory necessary for the fax client connection.

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