3.1.4.1.46 FAX_GetMessageEx (Opnum 89)

The FAX_GetMessageEx (Opnum 89) method is called by the client to retrieve a particular message from one of the specified fax message archives. 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. The folder value MUST be one of the enumerations that are defined by FAX_ENUM_MESSAGE_FOLDER (section 2.2.2), except FAX_MESSAGE_FOLDER_QUEUE. This is an extended version of FAX_GetMessage (section 3.1.4.1.45), because it takes an additional level parameter supporting the extended structure FAX_MESSAGE_1 (section 2.2.37).

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

In response, the server MUST validate that 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 in lppBuffer and also its size.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetMessageEx(
   [in] handle_t hFaxHandle,
   [in] DWORDLONG dwlMessageId,
   [in] FAX_ENUM_MESSAGE_FOLDER Folder,
   [in] DWORD level,
   [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 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: A FAX_ENUM_MESSAGE_FOLDER that indicates the type of the archive where the message resides. The FAX_MESSAGE_FOLDER_QUEUE value is invalid for this parameter.

level: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the type of structure to return in lppBuffer. The only value currently supported is 1.

lppBuffer: A pointer to an array of FAX_MESSAGE_1 structures that contain the retrieved messages.

lpdwBufferSize: A pointer to a DWORD value that specifies 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_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code results under any of the following conditions: § The value of the specified level parameter is not 1. § The pointer specified by the lppBuffer parameter is NULL.<117> § The pointer specified by the lpdwBufferSize parameter is NULL.<118> § The value of the dwlMessageId parameter is specified as 0. § The value of the specified Folder parameter is not FAX_MESSAGE_FOLDER_INBOX or FAX_MESSAGE_FOLDER_SENTITEMS.
FAX_ERR_SRV_OUTOFMEMORY 0x00001B59	The fax server failed to allocate memory needed for internal execution of this operation.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	This error code is returned under any of the following conditions: § The message identified by the dwlMessageId parameter 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].