IXPLogon::StartMessage

The IXPLogon::StartMessage method initiates the transfer of an inbound message from the transport provider to the MAPI spooler.

Quick Info

See IXPLogon : IUnknown.

HRESULT StartMessage(
  ULONG ulFlags,         
  LPMESSAGE lpMessage,   
  ULONG FAR * lpulMsgRef 
);

Parameters

ulFlags: Reserved; must be zero.
lpMessage: [in] Pointer to a message object with read/write access, representing the inbound message, 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] Pointer to a 32-bit reference value assigned to the message. This value is initialized to 1 by the MAPI spooler before returning it to the transport provider.

Return Values

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 also processes any attachments. This processing can take a long time. Transport providers on 16-bit Windows platforms should 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 created by the transport provider 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, in the case where 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 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 doesn't 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 opened by the transport provider during a StartMessage call should be released before returning. However, the provider should not release the message object originally passed by the MAPI spooler in the lpMessage parameter.

If an error is returned from StartMessage, the message in process is released without having changes saved and is lost. The transport provider in such a case 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.