3.1.4.1.67 FAX_ReAssignMessage (Opnum 102)

  • Article

The fax client application calls the FAX_ReAssignMessage (Opnum 102) method to reassign the specified fax message to a set of users.<144>

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).

The dwlMessageId parameter specifies a particular message and can be obtained using the FAX_EnumMessages (section 3.1.4.1.24) method or the FAX_EnumMessagesEx (section 3.1.4.1.25) methods.

The client MUST specify the recipients for a reassigned message in a semicolon (;) separated format. In response, the server MUST validate whether the bIncomingFaxesArePublic option in the FAX_GENERAL_CONFIG (section 2.2.31) data structure is not set in the server configuration. The server MUST also validate whether the message that is specified by the dwlMessageId argument refers to a valid message on the server. The server MUST validate that there are recipient numbers for each of the recipients that are listed in pReAssignInfo structure. On success, the server MUST reassign the specified fax message.

 error_status_t FAX_ReAssignMessage(
   [in] handle_t hBinding,
   [in] DWORDLONG dwlMessageId,
   [in, ref] PFAX_REASSIGN_INFO pReAssignInfo
 );

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.

dwlMessageId: A DWORDLONG ([MS-DTYP] section 2.2.13) value that specifies the identifier of the fax message to reassign.

pReAssignInfo: A pointer to a FAX_REASSIGN_INFO (section 2.2.18) structure that contains reassignment information.

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_FILE_NOT_FOUND

0x00000002

This error code is returned under any of the following conditions:

§ The dwlMessageId argument does not specify a valid message.

§ One or more recipients specified in the lpcwstrRecipients field of the pReAssignInfo argument do not have a corresponding fax user account.

ERROR_ACCESS_DENIED

0x00000005

The caller does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER access rights.

ERROR_INVALID_PARAMETER

0x00000057

This error code is returned under any of the following conditions:

§ The value specified for the dwlMessageId parameter is zero.

§ The lpcwstrRecipients member of the data structure specified by the pReAssignInfo parameter is set to NULL or to an empty string.

ERROR_BUFFER_OVERFLOW

0x0000006F

The number of recipients specified in the lpcwstrRecipients member of the data structure pointed at by pReAssignInfo is greater than FAX_MAX_RECIPIENTS (10000).

ERROR_INVALID_OPERATION

0x000010DD

This error code is returned under any of the following conditions:

§ Incoming faxes are public (section 2.2.31). Reassignment is not supported when incoming faxes are public.

§ The server does not support reassignment, or the server is configured with a policy that is currently set to disable fax message reassignment.

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