CMC_return_code cmc_read (
CMC_session_id session, CMC_message_reference * message_reference, CMC_flags read_flags, CMC_message FAR * FAR * message, CMC_ui_id ui_id, CMC_extension FAR * read_extensions )
Parameters
session
[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the value provided for the session parameter is invalid, the cmc_read function returns CMC_E_INVALID_SESSION_ID.
message_reference
[in] Pointer to a CMC_message_reference structure containing the message reference of the message to be retrieved. A NULL value for this parameter indicates that cmc_read should retrieve the first message in the mailbox. If the message reference is invalid, cmc_read returns CMC_E_INVALID_MESSAGE_REFERENCE.
read_flags
[in] Bitmask of flags. The following flags can be set:
CMC_DO_NOT_MARK_AS_READ
Does not mark messages as read when they are returned. This flag also suppresses sending of receipt reports. The calling client application or service provider can query the implementation to see if it supports this flag by calling the cmc_query_configuration function.
CMC_ERROR_UI_ALLOWED
Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_read does not display a dialog box and returns an error value instead.
CMC_MSG_AND_ATT_HDRS_ONLY
The attach_filename fields in the CMC_message structure returned in the message parameter will be undefined when cmc_read returns and should be ignored. This flag can be used to reduce the amount of data transferred, because the filenames will not be included in the transfer. If this flag is not set, the attach_filename fields are returned as usual.
Note that if the CMC_MSG_TEXT_NOTE_AS_FILE value is set in the flags of the returned message, the first attachment contains the message text. In this case, cmc_read returns the attach_filename field for that attachment regardless of the setting of the CMC_MSG_AND_ATT_HDRS_ONLY flag.
CMC_READ_FIRST_UNREAD_MESSAGE
Returns the first message that is not marked as read. If this flag is not set, cmc_read should return the first message in the mailbox, whether it is marked as read or not. This flag can only be set when passing a null message reference to receive the first message in the mailbox.
message
[out] Pointer to the location to which cmc_read writes the CMC_message structure containing the message it has read. The function writes attachment data in files, and the CMC_message structure indicates the names of those files in its attachments member. If the client application has set the CMC_MSG_AND_ATT_HDRS_ONLY flag, the function does not indicate any attachment files.
ui_id
[in] Handle of a dialog box for cmc_read to present to help resolve processing questions.
read_extensions
[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_read function. A value of NULL for the read_extensions parameter indicates that the client application has no extensions for cmc_read and is expecting no extensions.
On output, cmc_read writes to the array new information about the read operation. It writes NULL if it generates no output extensions.
Return Values
CMC_E_ATTACHMENT_OPEN_FAILURE
The specified attachment was found but could not be opened, or the attachment file could not be created.
CMC_E_ATTACHMENT_READ_FAILURE
The specified attachment was found and opened, but there was an error reading it.
CMC_E_ATTACHMENT_WRITE_FAILURE
The attachment file was created successfully, but there was an error writing it.
CMC_E_DISK_FULL
Insufficient disk space was available to complete the requested operation — this can refer to local or shared disk space.
CMC_E_FAILURE
There was a general failure that does not fit the description of any other return value.
CMC_E_INSUFFICIENT_MEMORY
Insufficient memory was available to complete the requested operation.
CMC_E_INVALID_FLAG
A flag set using a flags parameter was invalid.
CMC_E_INVALID_MESSAGE_REFERENCE
The specified message reference is invalid or no longer valid — for example, it has been deleted.
CMC_E_INVALID_PARAMETER
A function parameter was invalid.
CMC_E_INVALID_SESSION_ID
The specified session handle is invalid or no longer valid — for example, after logging off.
CMC_E_INVALID_UI_ID
The specified user-interface identifier is invalid or no longer valid.
CMC_E_TOO_MANY_FILES
The current implementation cannot support the number of files specified.
CMC_E_UNABLE_TO_NOT_MARK_READ
The current implementation cannot support the CMC_DO_NOT_MARK_AS_READ flag.
CMC_E_UNSUPPORTED_FLAG
The current implementation does not support the flag requested.
CMC_E_UNSUPPORTED_FUNCTION_EXT
The current implementation does not support the function extension requested.
Remarks
The cmc_read function only reads the first message in the mailbox if the client application passes a null message-reference value.
After processing, cmc_read writes the data from the message into the CMC_message structure. Unless the client application has set the flag CMC_DO_NOT_MARK_AS_READ on input, the message will be marked as read when cmc_read returns. If the client application has set the input flag CMC_MSG_AND_ATT_HDRS_ONLY, cmc_read writes only message and attachment headers on output.
The cmc_read function can write multiple addresses. Before it writes message information, it must allocate memory for the structure to contain that information. When this memory is no longer needed, the client application should free all structures in the array with a call to the cmc_free function.