Last modified: July 23, 2011
Applies to: Outlook
Initiates the transfer of an inbound message from the transport provider to the MAPI spooler.
The MAPI spooler calls the IXPLogon::StartMessage method to initiate the transfer of an inbound message from the transport provider to the MAPI spooler. Before the transport provider starts to use the message pointed to by lpMessage, it should store a message reference in the lpulMsgRef parameter for potential use by a call to the IXPLogon::TransportNotify method.
During a StartMessage call, the MAPI spooler processes methods for objects opened during the transfer of the message, and it also processes any attachments. This processing can take a long time. Transport providers can call the IMAPISupport::SpoolerYield callback function for the MAPI spooler frequently during this processing to release CPU time for other system tasks.
All recipients in the recipient table that the transport provider creates for the message must contain all required addressing properties. If necessary, the provider can construct a custom recipient to represent a particular recipient. However, if the provider can produce a recipient entry that includes more information, it should do so. For example, if a transport provider has enough information about an address book provider's recipient format that it can build a valid entry identifier for a recipient for that format, it should build the entry identifier.
If any nontransmittable properties are received, the transport provider should not store them in the new message. However, the transport provider should store all transmittable properties it receives in the new message.
If the incoming message is a delivery report or a nondelivery report and the transport provider is unable to use the IMAPISupport::StatusRecips method to generate the report from the original message, the provider should itself populate the message with the appropriate properties. However, the transport provider cannot set the message's PR_ENTRYID (PidTagEntryId) property.
To save the incoming message in the appropriate MAPI message store after processing, the transport provider calls the IMAPIProp::SaveChanges method. If the transport provider does not have any messages to pass to the MAPI spooler, it can stop the incoming message by returning from the StartMessage call without calling SaveChanges.
All objects that the transport provider opens during a StartMessage call should be released before returning. However, the provider should not release the message object that the MAPI spooler originally passed in the lpMessage parameter.
If StartMessage returns an error, the message in process is released without having changes saved and is lost. In this case, the transport provider should pass the NOTIFY_CRITICAL_ERROR flag with a call to the IMAPISupport::SpoolerNotify method and call the IXPLogon::Poll method to notify the MAPI spooler that it is in a severe error condition.
For more information, see Interacting with the MAPI Spooler.