3.1.4.1.84 FAX_SetMessage (Opnum 103)

The fax client application calls the FAX_SetMessage (Opnum 103) method to set the specific message properties for the message identified by its ID.<162> 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) method.

In response, the server MUST validate whether the client's fax user account has access to set the message properties. The server MUST also confirm if the dwlMessageId specified by the client refers to a valid message and the client's fax user account has access to this message in the specified folder. On success, the server MUST set the specified message properties, enabled using the dwValidityMask member of the FAX_MESSAGE_PROPS (section 2.2.15) structure, for the fax message.

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_SetMessage(
   [in] handle_t hFaxHandle,
   [in] DWORDLONG dwlMessageId,
   [in] FAX_ENUM_MESSAGE_FOLDER Folder,
   [in, ref] PFAX_MESSAGE_PROPS lpMessageProps
 );

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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

dwlMessageId: The unique ID number of the fax message.

Folder: Identifies the location of the fax message. The value in this parameter MUST come from the FAX_ENUM_MESSAGE_FOLDER (section 2.2.2) enumeration. It can be set to the FAX_MESSAGE_FOLDER_INBOX or FAX_MESSAGE_FOLDER_SENTITEMS constant.

lpMessageProps: This MUST be a pointer to a FAX_MESSAGE_PROPS. Contains the property settings for the fax message identified by dwlMessageId.

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. The client's fax user account does not have the ALL_FAX_USER_ACCESS_RIGHTS access rights required for this operation.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § The structure pointed to by the lpMessageProps argument contains invalid data. § The Folder argument has an invalid value (a value other than FAX_MESSAGE_FOLDER_INBOX or FAX_MESSAGE_FOLDER_SENTITEMS). § The dwlMessageId parameter is zero. § In the structure pointed at by the lpMessageProps argument, the dwValidityMask field contains the FAX_MSG_PROP_FIELD_MSG_FLAGS, and the dwMsgFlags field does not contain the FAX_MSG_ALL_FLAGS flag.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	The fax message specified by the dwlMessageId argument cannot be found by the fax server in the folder specified by the Folder argument.

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