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