MAPISaveMail (VB)

The Visual Basic MAPISaveMail function saves a message.

Quick Info

MAPISaveMail(

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

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value for the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

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.

Message

[in] Contents of the message to be saved. Client applications can either ignore the Flags member of the MapiMessage type, or if the message has never been saved, can set the MAPI_SENT and MAPI_UNREAD flags.

Recips

[in] The first element in an array of recipients. When the value of the RecipCount member in the MapiMessage type is zero, this parameter is ignored. The recipient string can include either the recipient's name or the recipient's name-address pair. If only a name is specified, the name is resolved to an address using implementation-defined address-book search rules. If an address is also specified, a search for the name is not performed. The address is in an implementation-defined format and is assumed to have been obtained from the implementation some other way. When the address is specified, the name is used for display to the user and the address is used for delivery. When the EntryID member for a particular recipient is used, no search is performed and the display-name and address are ignored. (A name and address are associated with the EntryID within the messaging system.)

Files

[in] The first element in an array of attachment files written when the message is read. The number of attachments per message can be limited in some systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. When the value of the FileCount member in the MapiMessage type is zero, this parameter is ignored. Attachment files are read and attached to the message before the call returns. Do not attempt to display attachments outside the range of the message text.

Flags

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

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISaveMail ignores this flag if the MessageID parameter is empty.

MAPI_LONG_MSGID

The returned message identifier is expected to be 512 characters. If this flag is set, the MessageID parameter must be large enough to accomodate 512 characters.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, MAPISaveMail uses an existing shared session.

Reserved

Reserved; must be zero.

MessageID

[in] A variable-length, caller-allocated string identifier for the message, returned either by the MAPIFindNext function or a previous call to MAPISaveMail, or a null string. If the MessageID parameter contains a valid message identifier, the message is overwritten. If MessageID contains a null string, a new message is created.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while saving the message. No message was saved.

MAPI_E_BAD_RECIPTYPE

The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to save the message. No message was saved.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the MessageID parameter. No message was saved.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the Session parameter. No message was saved.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was saved.

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

MAPI_E_USER_ABORT

The user canceled the process. No message was saved.

SUCCESS_SUCCESS

The call succeeded and the message was saved.

Remarks

To replace an existing message, the caller first calls the MAPIFindNext function to locate the message to be replaced and then calls the MAPISaveMail function with the MessageID parameter set with a valid message identifier. The elements of the message identified by MessageID are replaced by the elements in the MapiMessage type pointed to by the Message parameter.

To create a new message, the caller passes an empty string for MessageID. New messages are saved in the folder appropriate for incoming messages of that class. The new message identifier is returned in MessageID on completion.

The MessageID parameter must be a variable-length string. The elements of the message identified by MessageID are replaced by the elements in the Message parameter. If MessageID is empty, a new message is created.

MAPISaveMail takes the recipients and file attachments from the Recips and Files parameters, which should each be the first element of dynamically allocated arrays of their respective types. These arrays are not redimensioned.

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

MAPISaveMail(

ByVal Session&,
ByVal UIParam&,
message As MAPIMessage,
Recipient() As MapiRecip,
File() As MapiFile,
ByVal Flags&,
ByVal Reserved&,
MsgID$) As Long