IMessage::SubmitMessage

The IMessage::SubmitMessage method saves all of the message's properties and marks the message as ready to be sent.

Quick Info

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 Values

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 property. If the MSGFLAG_RESEND flag is set, call IMAPISupport::PrepareSubmit. PrepareSubmit updates the recipient type and PR_RESPONSIBILITY 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 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.