3.1.4.1.96 FAX_StartCopyMessageFromServer (Opnum 69)

The FAX_StartCopyMessageFromServer (Opnum 69) method is called by the fax client to start a copy operation of a fax message from the Fax Archive Folder (section 3.1.1) or of a fax job from the server queue directory (section 3.1.1).

In response, the server MUST validate the message ID and the folder. The server MUST also validate that the client's fax user account has access to query jobs in the queue or query messages in the archive. The dwlMessageId parameter specifies a particular message and SHOULD be obtained from FAX_EnumMessages (section 3.1.4.1.24) or FAX_EnumMessagesEx (section 3.1.4.1.25).

To indicate success, the server MUST create and return a copy handle to the client.

The copy handle returned by the fax server with the lpHandle output argument is valid until the fax client calls FAX_EndCopy (section 3.1.4.1.15), until the fax server is shut down or restarted, or until an implementation-specific condition occurs that invalidates the copy handle on the fax server.

 error_status_t FAX_StartCopyMessageFromServer(
   [in] handle_t hFaxHandle,
   [in] DWORDLONG dwlMessageId,
   [in] FAX_ENUM_MESSAGE_FOLDER Folder,
   [out, ref] PRPC_FAX_COPY_HANDLE lpHandle
 );

hFaxHandle: 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 indicates the message identifier to copy to the client.

Folder: This MUST be an enumeration value that indicates the folder from which to copy the message. For more information, see FAX_ENUM_MESSAGE_FOLDER (section 2.2.2).

lpHandle: The copy handle identifying this copy operation.

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/error code values	Description
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. The dwlMessageId specified is 0 and/or the specified Folder enumeration value is not FAX_MESSAGE_FOLDER_QUEUE, FAX_MESSAGE_FOLDER_INBOX, or FAX_MESSAGE_FOLDER_SENTITEMS.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	This error code is returned if any of the following conditions are met: § The fax server cannot find the fax queue entry referenced by the specified dwMessageId (invalid job identifier) or the user does not have sufficient rights to access the fax queue. § FAX_MESSAGE_FOLDER_QUEUE was specified for the Folder parameter, the specified message is not owned by the client's fax user account, and the client's fax user account does not have either the FAX_ACCESS_QUERY_OUT_JOBS permission or the FAX_ACCESS_MANAGE_OUT_JOBS permission. § FAX_MESSAGE_FOLDER_INBOX was specified for Folder, the client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER permission, and the bIncomingMessagesArePublic option is not specified in the server configuration. § FAX_MESSAGE_FOLDER_SENTITEMS was specified for Folder, the client's fax user account does not have the FAX_ACCESS_QUERY_ARCHIVES permission, and the specified message is not owned by the client's fax user account.

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