IMessage::SubmitMessage
Applies to: Outlook 2013 | Outlook 2016
Saves all of the message's properties and marks the message as ready to be sent.
HRESULT SubmitMessage(
ULONG ulFlags
);
Parameters
ulFlags
[in] Bitmask of flags used to control how a message is submitted. The following flag can be set:
FORCE_SUBMIT
MAPI should submit the message immediately. This flag is not currently in use.
Return value
S_OK
The call succeeded and has returned the expected value or values.
MAPI_E_NO_RECIPIENTS
The message's recipient table is empty.
Remarks
The IMessage::SubmitMessage method marks a message as ready to be transmitted. MAPI passes messages to the underlying messaging system in the order in which they are marked for sending. Because of this functionality, a message might stay in a message store for some time before the underlying messaging system can take responsibility for it. The order of receipt at the destination is in the underlying messaging system's control and does not necessarily match the order in which messages were sent.
Notes to implementers
Call the message's IMAPIProp::SaveChanges method to save it and then check the message's PR_MESSAGE_FLAGS (PidTagMessageFlags) property. If the MSGFLAG_RESEND flag is set, call IMAPISupport::PrepareSubmit. PrepareSubmit updates the recipient type and PR_RESPONSIBILITY (PidTagResponsibility) property for all of the recipients in the resend message.
Notes to callers
When SubmitMessage returns, all pointers to the message and its associated subobjects messages, folders, attachments, streams, tables, and so on are no longer valid. MAPI does not permit any further operations on these pointers, except for calling their IUnknown::Release methods. MAPI is designed such that after SubmitMessage is called, you should release the message and all associated subobjects. However, if SubmitMessage returns an error value indicating missing or invalid information, the message remains open and the pointers remain valid.
To cancel a send operation, get and store a pointer to the message's PR_ENTRYID (PidTagEntryId) property before the message is submitted. Because a message's entry identifier is invalidated after the message has been submitted, it is necessary to save it before calling SubmitMessage. To cancel the send, point the lpEntryId parameter to this entry identifier and call IMsgStore::AbortSubmit.
MFCMAPI reference
For MFCMAPI sample code, see the following table.
| File | Function | Comment |
|---|---|---|
| FolderDlg.cpp |
CFolderDlg::OnSubmitMessage |
MFCMAPI uses the IMessage::SubmitMessage method to submit the selected message. |