IXPLogon::StartMessage
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Initiates the transfer of an inbound message from the transport provider to the MAPI spooler.
HRESULT StartMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef
);
Parameters
ulFlags
[in] Reserved; must be zero.lpMessage
[in] A pointer to a message object (representing the inbound message) that has read/write permission, which is used by the transport provider to access and manipulate that message. This object remains valid until after the transport provider returns from the call to IXPLogon::StartMessage.lpulMsgRef
[out] A pointer to a reference value assigned to the message. The MAPI spooler initializes this value to 1 before it returns the pointer to the transport provider.
Return Value
- S_OK
The call succeeded and has returned the expected value or values.
Remarks
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.