3.1.4.1.101 FAX_StartServerNotificationEx (Opnum 74)

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

 error_status_t FAX_StartServerNotificationEx(
   [in] handle_t hBinding,
   [in, string, ref] LPCWSTR lpcwstrMachineName,
   [in, string, ref] LPCWSTR lpcwstrEndPoint,
   [in] ULONG64 Context,
   [in, ref, string] LPCWSTR lpcwstrProtSeq,
   [in] BOOL bEventEx,
   [in] DWORD dwEventTypes,
   [out, ref] PRPC_FAX_EVENT_EX_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 (section 3.1.4.1.10) or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

lpcwstrMachineName: A pointer to a string containing the name of the fax client machine. The machine name MUST be NULL for a local machine and an FQDN for a remote machine.

lpcwstrEndPoint: A pointer to a string containing 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.

lpcwstrProtSeq: A pointer to a string containing the fax client RPC server's protocol sequence string. The protocol used for sending the notifications is always TCP/IP. The protocol sequence string MUST be ncalrpc for local and respectively ncan_ip_tcp for remote. <174>

bEventEx: A Boolean value that indicates which notification method to use for notifications. If set to TRUE, the registration is for extended events (FAX_EVENT_EX (section 2.2.67)). If FALSE, the registration is for legacy events (FAX_EVENT (section 2.2.66)).

dwEventTypes: A DWORD ([MS-DTYP] section 2.2.9) value containing bitwise OR combination of FAX_ENUM_EVENT_TYPE (section 2.2.63) event type flags, events the client needs to receive. During registration the client is allowed to register for multiple events, so that if any of them occur the client will get a notification. Hence bitwise ORing of events is allowed in this case. For more information, see FAX_ENUM_EVENT_TYPE.

lpHandle: The 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	Access is denied. This error code is returned under any of the following conditions: § The value specified for the dwEventTypes argument contains the FAX_EVENT_TYPE_NEW_CALL and/or FAX_EVENT_TYPE_IN_QUEUE flags and the caller cannot access unsigned faxes: incoming faxes are not public and the caller does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER rights. § The value specified for the dwEventTypes argument contains the FAX_EVENT_TYPE_CONFIG, FAX_EVENT_TYPE_DEVICE_STATUS and/or the FAX_EVENT_TYPE_ACTIVITY flags and the caller does not have the FAX_ACCESS_QUERY_CONFIG rights.
ERROR_BAD_FORMAT 0x0000000B	This error code is returned under any of the following conditions: § The length of the fax client machine name specified by the lpcwstrMachineName argument, excluding the length of the terminating null character, is longer than 256 characters. § The length of the endpoint string specified by the lpcwstrEndPoint argument, excluding the length of the terminating null character, is longer than or equal to 11 characters.
ERROR_OUTOFMEMORY 0x0000000E	Not enough storage is available to complete this operation.
ERROR_INVALID_PARAMETER 0x00000057	Invalid parameter. This error code is returned under any of the following conditions: § Any of these arguments specify a NULL pointer value: lcpwstrEndPoint, lpcwstrMachineName, lpHandle.<175> § The value specified for the dwEventTypes argument is not a bitwise OR combination of the following FAX_ENUM_EVENT_TYPE values: § FAX_EVENT_TYPE_IN_QUEUE § FAX_EVENT_TYPE_OUT_QUEUE § FAX_EVENT_TYPE_CONFIG § FAX_EVENT_TYPE_ACTIVITY § FAX_EVENT_TYPE_QUEUE_STATE § FAX_EVENT_TYPE_IN_ARCHIVE § FAX_EVENT_TYPE_OUT_ARCHIVE § FAX_EVENT_TYPE_FXSSVC_ENDED § FAX_EVENT_TYPE_DEVICE_STATUS § FAX_EVENT_TYPE_NEW_CALL

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

A fax client calls FAX_StartServerNotificationEx to inform the server that it needs to receive the notifications of extended or 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 notification of events to the client by using either FAX_ClientEventQueueEx (section 3.2.4.3) or FAX_ClientEventQueue (section 3.2.4.2) as specified by the bEventEx parameter. When the client no longer needs to receive notifications, it calls FAX_EndServerNotification; the server SHOULD call FAX_CloseConnection (section 3.2.4.4) to close the connection.