IMessage::SubmitMessage

Applies to: Office 2010 | Outlook 2010 | Visual Studio

In this article
Notes to Implementers
Notes to Callers
MFCMAPI Reference

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.

See Also

Reference

IMsgStore::AbortSubmit

IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample