3.1.4.1.25 FAX_EnumMessagesEx (Opnum 91)

The FAX_EnumMessagesEx (Opnum 91) method is called by the client. This message differs from the FAX_EnumMessages (section 3.1.4.1.24) in that this function takes a level parameter, which differentiates the type of message information structure that the function returns.

In response, the server MUST validate that the hEnum argument that is passed by the client was created as part of a prior FAX_StartMessagesEnum (section 3.1.4.1.98) or FAX_StartMessagesEnumEx (section 3.1.4.1.99) call. The server MUST validate that the dwNumMessages argument is not zero.

On success, the server MUST return information regarding messages. The server MUST return the size of the returned information and the number of messages for which it could successfully retrieve the information. The latter value MUST NOT exceed dwNumMessages. The server MUST return the level of information. This return value is decided by whether the client used FAX_StartMessagesEnum or FAX_StartMessagesEnumEx to start the enumeration of messages.

The client SHOULD free the returned buffer.

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_EnumMessagesEx(
   [in, ref] RPC_FAX_MSG_ENUM_HANDLE hEnum,
   [in] DWORD dwNumMessages,
   [out, size_is(,*lpdwBufferSize)] 
     LPBYTE* lppBuffer,
   [out, ref] LPDWORD lpdwBufferSize,
   [out, ref] LPDWORD lpdwNumMessagesRetrieved,
   [out, ref] LPDWORD lpdwLevel
 );

hEnum: The enumeration handle returned through the lpHandle output argument by FAX_StartMessagesEnum or FAX_StartMessagesEnumEx.

dwNumMessages: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the maximum number of messages that the caller requires to enumerate. This value MUST NOT be zero.

lppBuffer: A pointer to an array of FAX_MESSAGE_1 (section 2.2.37) structures that contain lpdwNumMessagesRetrieved entries.

lpdwBufferSize: A pointer to a DWORD value that specifies the size, in bytes, of the buffer.

lpdwNumMessagesRetrieved: A pointer to a DWORD value that indicates the actual number of retrieved messages. This value SHOULD NOT exceed dwNumMessages.

lpdwLevel: A pointer to a DWORD value that indicates the structure to return.

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_NOT_ENOUGH_MEMORY 0x00000008	The fax server failed to allocate memory for the return buffer.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § One or more of the pointer values specified by the following arguments are NULL: lppBuffer, lpdwBufferSize, lpdwNumMessagesRetrieved,  and lpdwLevel. § hEnum is NULL<90> or is an invalid handle that is not returned by a call to FAX_StartMessagesEnum or FAX_StartMessagesEnumEx <91>. § dwNumMessages is zero.
ERROR_BUFFER_OVERFLOW 0x0000006F	The fax server encountered an integer overflow condition while processing the request for the maximum number of messages specified by the dwNumMessages argument.
ERROR_NO_MORE_ITEMS 0x00000103	No more data is available. The method reached the end of the lppBuffer message buffer and there are no more messages to be enumerated.
FAX_ERR_SRV_OUTOFMEMORY 0x00001B59	The fax server failed to allocate memory needed for internal execution of the command.

The client implementation assumes that this method is incremental and uses an internal context cursor to point to the next set of messages to retrieve for each call. The cursor is set to point to the beginning of the messages in the archive after a successful call to FAX_StartMessagesEnum or FAX_StartMessagesEnumEx. Each successful call to FAX_EnumMessagesEx advances the cursor by the number of messages retrieved. After the cursor reaches the end of the enumeration, the method fails with the 0x00000103 (ERROR_NO_MORE_ITEMS) error code. The FAX_EndMessagesEnum (section 3.1.4.1.16) method can then be called to halt the enumeration of messages.

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