IXPLogon::StartMessage
The IXPLogon::StartMessage
method initiates the transfer of an incoming 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 incoming 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 the IXPLogon::StartMessage method.
lpulMsgRef
[out] Pointer
to a variable in which the transport provider returns the 32-bit reference
value it assigned to this 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 incoming message from the transport provider to the MAPI spooler. Before
the transport provider starts to use the message object, 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 provider should store in the
message all transmittable properties required for the message.
If the
incoming message is to be 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
passed message with the appropriate properties.
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 flag NOTIFY_CRITICAL_ERROR 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.
See Also