MAPIReadMail (VB)

The Visual Basic MAPIReadMail function retrieves a message for reading.

Quick Info

Header file:

MAPIVB32.BAS

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 MAPIFindNext and MAPISaveMail 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 MapiMessage 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 MapiMessage 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 MapiMessage 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