Last modified: July 23, 2011
Applies to: Outlook
Indicates that the MAPI spooler has a message for the transport provider to deliver.
The MAPI spooler calls the IXPLogon::SubmitMessage method when it has a message for the transport provider to deliver. The message is passed to the transport provider by using the lpMessage parameter.
If the provider is ready to accept the message, it should return a reference value by using the lpulMsgRef parameter, process the passed object, and return the appropriate value (usually S_OK). If the provider is not prepared to handle the transfer, it should return an error value and, optionally, another MAPI return value in lpulReturnParm to indicate how long the MAPI spooler should wait before resubmitting the message.
A transport provider's implementation of this method can do the following:
Put the message into an internal queue to wait for transmission, possibly copying the message to local storage, and return.
Attempt to perform the actual transmission and return when the transmission completes, either successfully or unsuccessfully.
Determine whether to send the message after checking the resource involved. In this case, if the resource is free, the provider can lock the resource, prepare the message, and submit it. If the resource is busy, the provider can prepare the message and defer sending to a later time.
The preferred technique for message transmission depends on the transport provider and the expected number of processes competing for system resources.
During a SubmitMessage call, the transport provider controls the transfer of message data from the message object. However, the transport provider should assign a reference value to the message, to which it returns a pointer in lpulMsgRef, before transferring data. It does so because at any point during the process, the MAPI spooler can call the IXPLogon::TransportNotify method with the NOTIFY_CANCEL_MESSAGE flag set to signal the provider that it should release any open objects and stop message transfer.
The transport provider should not send any nontransmittable properties of the message. When it finds such a property, it should go on to process the next property. The provider should make every effort not to display MAPI_P1 recipient information as part of the transmitted message content; the provider should use this recipient information only for addressing purposes. MAPI_P1 recipients are internally generated recipients that are used for resending messages; they should not be transmitted. Instead, use the other recipients for transmitting recipient information. The purpose of this arrangement is to permit resend recipients to see the exact same recipient table as the original recipients.
During a SubmitMessage call, the MAPI spooler processes methods for objects that are opened during the transfer of the message, and it processes any attachments. This processing can take a long time. Transport providers can call the IMAPISupport::SpoolerYield method for the MAPI spooler frequently during this processing to release CPU time for other system tasks.
All message recipients are visible in the recipient table of the message that the MAPI spooler originally passed. The transport provider should process only those recipients that it can handle — based on entry identifier, address type, or both — and that do not already have their PR_RESPONSIBILITY (PidTagResponsibility) property set to TRUE. If PR_RESPONSIBILITY is already set to TRUE, another transport provider has handled that recipient. When the provider completes sufficient processing of a recipient to determine whether it can handle messages for that recipient, it should set that recipient's PR_RESPONSIBILITY property to TRUE in the passed message. Usually, the provider makes this determination after message delivery is complete.
Typically, the transport provider does not return from a SubmitMessage call until it completes the transfer of message data. If no error is returned, the next call from the MAPI spooler to the provider is a call to the IXPLogon::EndMessage method.
If SubmitMessage returns an error, the MAPI spooler releases the message in process without saving changes. If the transport provider requires message changes to be saved, it must call the IMAPIProp::SaveChanges method on the message before returning.
In case of errors that occur because of transport problems, the MAPI spooler retains the message, but it delays resubmitting the message to the transport provider based on the value returned in lpulReturnParm. The transport provider must fill in that value if its return value from SubmitMessage is MAPI_E_WAIT or MAPI_E_NETWORK_ERROR. If a severe error condition occurs, the transport provider must call the IMAPISupport::SpoolerNotify method with the NOTIFY_CRITICAL_ERROR flag.