3.1.4.1.45 FAX_GetMessage (Opnum 66)

The FAX_GetMessage (Opnum 66) method is called by the client. The archive can be one of the enumerations that are defined by FAX_ENUM_MESSAGE_FOLDER (section 2.2.2) except FAX_MESSAGE_FOLDER_QUEUE. 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 that the message ID is for a valid message. The server MUST validate that the client's fax user account has access to read the message.

On success, the server MUST return the contents of the message and also its size.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetMessage(
   [in] handle_t hFaxHandle,
   [in] DWORDLONG dwlMessageId,
   [in] FAX_ENUM_MESSAGE_FOLDER Folder,
   [out, size_is(, *lpdwBufferSize)] 
     LPBYTE* lppBuffer,
   [out, ref] LPDWORD lpdwBufferSize
 );

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 identifies the fax message to retrieve from the archive.

Folder: The type of archive where the message resides. FAX_MESSAGE_FOLDER_QUEUE is an invalid value for this parameter.

lppBuffer: A pointer to a buffer that receives a FAX_MESSAGEW (section 2.2.38) structure. This buffer contains the retrieved message.

lpdwBufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) in which to return the size, in bytes, of the buffer that is pointed to by the lppBuffer parameter.

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 any of the permissions covered by ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83).
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command. The fax server failed to allocate sufficient memory to hold the FAX_MESSAGEW to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned when any of the following conditions are met: § The lppBuffer or lpdwBufferSize parameters are set to NULL pointer values.<116> § The dwlMessageId parameter is set to a value of 0, and the value of the specified Folder parameter is not FAX_MESSAGE_FOLDER_INBOX or FAX_MESSAGE_FOLDER_SENTITEMS.
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the FAX_MESSAGEW to be returned to the client.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	The fax server cannot find the job or message by its identifier.  This error code is returned when any of the following conditions are met: § The message identified by dwlMessageId is not found. § The message identified by dwlMessageId is an unassigned incoming fax. The incoming faxes are not public (accessible to all users), and the user does not have FAX_ACCESS_MANAGE_RECEIVE_FOLDER permission. § The message identified by dwlMessageId is for a different user, and this user does not have FAX_ACCESS_QUERY_ARCHIVES permission.

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