3.1.4.1.100 FAX_StartServerNotification (Opnum 73)

The FAX_StartServerNotification (Opnum 73) method is called by the client to get notification about legacy events. On success, the server MUST start to notify the fax client about the occurring fax events.

Protocol version FAX_API_VERSION_2 (0x00020000) and FAX_API_VERSION_3 (0x00030000) fax servers SHOULD fail this call by returning ERROR_NOT_SUPPORTED (0x00000032). The fax client SHOULD NOT call this method if the protocol version reported by the server is FAX_API_VERSION_2 (0x00020000) or FAX_API_VERSION_3 (0x00030000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10).

 error_status_t FAX_StartServerNotification(
   [in] handle_t hBinding,
   [in, string, ref] LPCWSTR lpcwstrMachineName,
   [in, string, ref] LPCWSTR lpcwstrEndPoint,
   [in] ULONG64 Context,
   [in, ref, string] LPCWSTR lpcwstrProtseqString,
   [in] BOOL bEventEx,
   [in] DWORD dwEventTypes,
   [out, ref] PRPC_FAX_EVENT_HANDLE lpHandle
 );

hBinding: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FAX_ConnectFaxServer or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

lpcwstrMachineName: A pointer to a string that contains 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.

lpcwstrEndPoint: A pointer to a string that contains the client machine RPC server endpoint string. The endpoint MUST be a TCP port between 1024 and 65534 (in increments of 10).

Context: A ULONG64 ([MS-DTYP] section 2.2.54) value that can be passed to FAX_OpenConnection (section 3.2.4.5) as a notification context.

lpcwstrProtseqString: A pointer to a string that contains the fax client RPC server's protocol sequence string. The protocol sequence string MUST be ncalrpc for local and ncan_ip_tcp for remote.

bEventEx: A Boolean value that indicates which notification method to use for notifications. This parameter is always set to FALSE.

dwEventTypes: A DWORD ([MS-DTYP] section 2.2.9) value that indicates which events the client needs to receive. This parameter is always set to FAX_EVENT_TYPE_LEGACY. For more information, see FAX_ENUM_EVENT_TYPE (section 2.2.63).

lpHandle: Returned subscription context handle. This handle can be used in the FAX_EndServerNotification (section 3.1.4.1.17) method.

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	The client's fax user account does not have sufficient rights for this call, which is ALL_FAX_USER_ACCESS_RIGHTS, or the user account does not exist.
ERROR_BAD_FORMAT 0x0000000B	The length, including the terminating null character, of the string specified by the lpcwstrMachineName argument is greater than 256 characters. The length, including the terminating null character, of the string specified by the lpcwstrEndPoint argument is greater than 11 characters.
ERROR_NOT_SUPPORTED 0x00000032	The request is not supported.

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

A fax client calls FAX_StartServerNotification to inform the server that it needs to receive the notifications of legacy fax events. The fax server SHOULD call FAX_OpenConnection on the client by using the supplied endpoint, protocol sequence information, and context handle information. The server then sends the notification of legacy events to the client by using FAX_ClientEventQueue (section 3.2.4.2). When the client no longer needs to receive notifications, it calls FAX_EndServerNotification, and the server SHOULD call FAX_CloseConnection (section 3.2.4.4) to close the connection.

Note This method only supports TCP/IP as the transport protocol.