MAPIReadMail (VB)

The Visual Basic MAPIReadMail function retrieves a message for reading.

Quick Info

MAPIReadMail(

    Session as Long,
    UIParam as Long,
    MessageID as String,
    Flags as Long,
    Reserved as Long,
    Message as MapiMessage,
    Originator as MapiRecip,
    Recips() as MapiRecip,
    Files() as MapiFile) as Long

Parameters

Session

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

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

MessageID

[in] The message identifier of the message to be read. The MessageID parameter is a variable-length string that is obtained from the MAPIFindNext4WTQKI and MAPISaveMail1K1.O15 functions.

Flags

[in] Bitmask of flags. The following flags can be set:

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 are written. Setting this flag makes MAPIReadMail processing faster.

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 MapiMessageHKAC_5 type. MAPIReadMail ignores this flag if the calling application has set the MAPI_ENVELOPE_ONLY flag. Setting this flag makes MAPIReadMail processing faster.

Reserved

Reserved; must be zero.

Message

[out] A type set by MAPIReadMail to a message containing the message contents.

Originator

[out] The originator of the message.

Recips

[out] Array of recipients. This array is redimensioned as necessary to accommodate the number of recipients chosen by the user.

Files

[out] Array of attachment files written when the message is read. When MAPIReadMail is called, all message attachments are written to temporary files. It is the caller s responsibility to delete these files when they are no longer needed. When MAPI_ENVELOPE_ONLY or MAPI_SUPPRESS_ATTACH is set, no temporary files are written and no temporary names are filled into the file attachment descriptors. This array is redimensioned as necessary to accommodate the number of files attached by the user.

Return Values

MAPI_E_ATTACHMENT_WRITE_FAILURE

An attachment could not be written to a temporary file. Check directory permissions.

MAPI_E_DISK_FULL

The disk was full.

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 MessageID parameter.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the Session 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 types used in the MAPISendMail function. MAPIReadMail fills a block of memory with the MapiMessageHKAC_5 type containing message elements. File attachments are saved to temporary files, and the names are returned to the caller in the message type. 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 informationis to be returned from the call. Another flag in the MapiMessageHKAC_5 type specifies whether the message is marked as sent or unsent.

All strings are null-terminated and must be specified in the current character set or code page of the client application s operating system process. In Microsoft Windows, the character set is ANSI.

The sender, recipients, and file attachments are written into the appropriate parameters of the Visual Basic call. The Recips and Files parameters should be dynamically allocated arrays of their respective types.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIReadMail(

Session As Long,
UIParam As Long,
MessageID As String,
Flags As Long,
Reserved As Long,
message As MAPIMessage,
Orig As MapiRecip,
RecipsOut() As MapiRecip,
FilesOut() As MapiFile) As Long