MAPIREADMAIL callback function (mapi.h)

Article
04/19/2022

[The use of this function is discouraged. It may be altered or unavailable in subsequent versions of Windows.]

The MAPIReadMail function retrieves a message for reading.

Syntax

MAPIREADMAIL Mapireadmail;

ULONG Mapireadmail(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszMessageID,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
        lpMapiMessage *lppMessage
)
{...}

Parameters

[in] lhSession

Handle to a Simple MAPI session. The value of the lhSession parameter must represent a valid session; it cannot be zero.

[in] ulUIParam

Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG_PTR). If no dialog box is displayed during the call, ulUIParam is ignored.

[in] lpszMessageID

Pointer to a message identifier string for the message to be read. The string is allocated by the caller.

[in] flFlags

Bitmask of option flags. The following flags can be set.

Value	Meaning
MAPI_BODY_AS_FILE	MAPIReadMail should write the message text to a temporary file and add it as the first attachment in the attachment list.
MAPI_ENVELOPE_ONLY	MAPIReadMail should read the message header only. File attachments are not copied to temporary files, and neither temporary file names nor message text is written. Setting this flag enhances performance.
MAPI_PEEK	MAPIReadMail does not mark the message as read. Marking a message as read affects its appearance in the user interface and generates a read receipt. If the messaging system does not support this flag, MAPIReadMail always marks the message as read. If MAPIReadMail encounters an error, it leaves the message unread.
MAPI_SUPPRESS_ATTACH	MAPIReadMail should not copy file attachments but should write message text into the MapiMessage structure. MAPIReadMail ignores this flag if the calling application has set the MAPI_ENVELOPE_ONLY flag. Setting the MAPI_SUPPRESS_ATTACH flag enhances performance.

ulReserved

Reserved; must be zero.

lppMessage

Return value

This function returns one of the following values.

Return code	Description
MAPI_E_ATTACHMENT_WRITE_FAILURE	An attachment could not be written to a temporary file. Check directory permissions.
MAPI_E_DISK_FULL	An attachment could not be written to a temporary file because there was not enough space on the disk.
MAPI_E_FAILURE	One or more unspecified errors occurred while reading the message.
MAPI_E_INSUFFICIENT_MEMORY	There was insufficient memory to read the message.
MAPI_E_INVALID_MESSAGE	An invalid message identifier was passed in the lpszMessageID parameter.
MAPI_E_INVALID_SESSION	An invalid session handle was passed in the lhSession parameter. No message was retrieved.
MAPI_E_TOO_MANY_FILES	There were too many file attachments in the message. The message could not be read.
MAPI_E_TOO_MANY_RECIPIENTS	There were too many recipients of the message. The message could not be read.
SUCCESS_SUCCESS	The call succeeded and the message was read.

Remarks

The MAPIReadMail function returns one message, breaking the message content into the same parameters and structures used in the MAPISendMail function. MAPIReadMail fills a block of memory with the MapiMessage structure containing message elements, such as the subject, message class, delivery time, and the sender. File attachments are saved to temporary files, and the names are returned to the caller in the message structure. Recipients, attachments, and contents are copied from the message before MAPIReadMail returns to the caller, so later changes to the files do not affect the contents of the message.

A flag is provided to specify that only envelope information is to be returned from the call. Another flag (in the MapiMessage structure) specifies whether the message is marked as sent or unsent.

The caller is responsible for freeing the MapiMessage structure by calling the MAPIFreeBuffer function and deleting any files associated with attachments included with the message.

Before calling MAPIReadMail, use the MAPIFindNext function to verify that the message to be read is the one you want to be read. Because message identifiers are system-specific and opaque and can be invalidated at any time, MAPIReadMail considers a message identifier to be valid only for the current Simple MAPI session.

Requirements

Requirement	Value
Target Platform	Windows
Header	mapi.h