3.1.4.1.102 FAX_StartServerNotificationEx2 (Opnum 92)

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

Protocol version FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), and FAX_API_VERSION_2 (0x00020000) fax servers SHOULD NOT implement this call. The fax client MUST NOT call this method if the protocol version reported by the server is FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), or FAX_API_VERSION_2 (0x00020000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10).

 error_status_t FAX_StartServerNotificationEx2(
   [in] handle_t hBinding,
   [in, string, unique] LPCWSTR lpcwstrAccountName,
   [in, string, ref] LPCWSTR lpcwstrMachineName,
   [in, string, ref] LPCWSTR lpcwstrEndPoint,
   [in] ULONG64 Context,
   [in, ref, string] LPCWSTR lpcwstrProtseqString,
   [in] DWORD dwEventTypes,
   [in] DWORD level,
   [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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

lpcwstrAccountName: A pointer to a constant null-terminated character string that indicates which account to enumerate. If this value is NULL, the current account's jobs are enumerated. Cross-account enumeration currently is not supported.

lpcwstrMachineName: A pointer to a null-terminated string that contains the name of the fax client machine.

lpcwstrEndPoint: A pointer to a null-terminated string that contains the client machine RPC server endpoint string.

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 null-terminated string that contains the fax client RPC server's protocol sequence string. The protocol that is used for sending the notifications is always TCP/IP.<176>

dwEventTypes: A DWORD ([MS-DTYP] section 2.2.9) value that indicates which events the client needs to receive. For more information, see FAX_ENUM_EVENT_TYPE (section 2.2.63). 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. This value cannot be FAX_EVENT_TYPE_LEGACY because the method only supports extended events.

level: A DWORD value that indicates the structure to return. The value MUST be set to 1.

lpHandle: A pointer to an RPC_FAX_EVENT_EX_HANDLE (Fax Data Types (section 2.2.74)) that returns a 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 is returned when any of the following conditions occur:

§ The dwEventTypes parameter is set to a value containing the FAX_EVENT_TYPE_NEW_CALL or FAX_EVENT_TYPE_IN_QUEUE flags, the incoming faxes are not public (accessible to all users), and the client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER permission.

§ dwEventTypes is set to a value containing the FAX_EVENT_TYPE_CONFIG, FAX_EVENT_TYPE_DEVICE_STATUS, or FAX_EVENT_TYPE_ACTIVITY flags and the client's fax user account does not have the FAX_ACCESS_QUERY_CONFIG permission.

ERROR_OUTOFMEMORY

0x0000000E

The fax server failed to allocate the memory required for the internal server's execution of this operation request.

ERROR_GEN_FAILURE

0x0000001F

The server threw internally an exception during the execution of this operation, and the server handled this exception.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect. This error code is returned under any of the following conditions:

§ dwEventTypes is set to a value containing the FAX_EVENT_TYPE_LEGACY or FAX_EVENT_TYPE_LOCAL_ONLY flags, or to another value that is not a combination made exclusively from the flags valid for this operation: 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, or FAX_EVENT_TYPE_NEW_CALL.

§ The level parameter is not set to 1.

§ One or more of the following parameters are set to NULL pointer values: lpcwstrEndpoint, lpcwstrMachineName, or lpHandle.<177>

§ The lpcwstrAccountName parameter is set to a non-null character string pointer value which does not specify a valid fax account name.

§ lpcwstrAccountName is set to a non-null character string pointer value which specifies a valid fax account name for a different user than the user who is currently logged on the client.

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

The account name is the one on which to listen for events and a level that specifies the type of the structure that describes each event. The name lpcwstrAccountName is accessed only for account-based events.

The account name that lpcwstrAccountName indicates MUST be in one of the following formats. Any other format is invalid.

Format

Description

<machine_name>\<user_name>

For a local user that has machine_name as the name of the local machine.

<domain_name>\<user_name>

For a nonlocal user.

A fax client calls FAX_StartServerNotificationEx2 (section 3.1.4.1.102) to inform the server that it needs to receive notifications of extended 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 FAX_ClientEventQueueEx (section 3.2.4.3). When the client no longer needs to receive notifications, it calls FAX_EndServerNotification (section 3.1.4.1.17), and the server SHOULD call FAX_CloseConnection (section 3.2.4.4) to close the connection.