MAPISAVEMAIL callback function (mapi.h)
[The use of this function is discouraged. It may be altered or unavailable in subsequent versions of Windows.]
The MAPISaveMail function saves a message into the message store.
Syntax
MAPISAVEMAIL Mapisavemail;
ULONG Mapisavemail(
[in] LHANDLE lhSession,
[in] ULONG_PTR ulUIParam,
[in] lpMapiMessage lpMessage,
[in] FLAGS flFlags,
ULONG ulReserved,
[in] LPSTR lpszMessageID
)
{...}
Parameters
[in] lhSession
Handle for a Simple MAPI session or zero. The value of the lhSession parameter must not be zero if the lpszMessageID parameter contains a valid message identifier. However, if lpszMessageID does not contain a valid message identifier, and the value of lhSession 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, the logon dialog box is displayed.
[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] lpMessage
Input parameter pointing to a MapiMessage structure containing the contents of the message to be saved. The lpOriginator member is ignored. Applications can either ignore the flFlags member, or if the message has never been saved, can set the MAPI_SENT and MAPI_UNREAD flags.
[in] flFlags
Bitmask of option flags. The following flags can be set.
ulReserved
Reserved; must be zero.
[in] lpszMessageID
Pointer to either the message identifier to be replaced by the save operation or an empty string, indicating that a new message is to be created. The string must be allocated by the caller and must be able to hold at least 512 characters if the flFlags parameter is set to MAPI_LONG_MSGID. If the flFlags parameter is not set to MAPI_LONG_MSGID, the message identifier string can hold 64 characters.
Return value
This function returns one of the following values.
Return code | Description |
---|---|
|
An attachment could not be located at the specified path. Either the drive letter was invalid, the path was not found on that drive, or the file was not found in that path. |
|
The recipient type in the lpMessage was invalid. |
|
One or more unspecified errors occurred while saving the message. No message was saved. |
|
There was insufficient memory to save the message. No message was saved. |
|
An invalid message identifier was passed in the lpszMessageID parameter; no message was saved. |
|
One or more recipients of the message were invalid or could not be identified. |
|
An invalid session handle was passed in the lhSession parameter. No message was saved. |
|
There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was saved. |
|
The operation was not supported by the underlying messaging system. |
|
The user canceled one of the dialog boxes. No message was saved. |
|
The call succeeded and the message was saved. |
Remarks
The MAPISaveMail function saves a message, optionally replacing an existing message. Before calling MAPISaveMail, use the MAPIFindNext function to verify that the message to be saved is the one you want saved. The elements of the message identified by the lpszMessageID parameter are replaced by the elements in the lpMessage parameter. If lpszMessageID is empty, a new message is created. All replaced messages are saved in their appropriate folders. New messages are saved in the folder appropriate for incoming messages of that class.
Not all messaging systems support storing messages. If the underlying messaging system does not support message storage, MAPISaveMail returns the MAPI_E_NOT_SUPPORTED value.
Because message identifiers are system-specific and opaque and can be invalidated at any time, MAPISaveMail considers a message identifier to be valid only for the current Simple MAPI session. MAPISaveMail handles invalid message identifiers by returning the MAPI_E_INVALID_MESSAGE value.
Requirements
Requirement | Value |
---|---|
Target Platform | Windows |
Header | mapi.h |
See also
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for