IXPLogon::SubmitMessage

The IXPLogon::SubmitMessage method indicates to a transport provider the MAPI spooler has a message for the provider to deliver.

Quick Info

See IXPLogon : IUnknownHVE6L8.

HRESULT SubmitMessage(

Parameters

ulFlags

[in] Bitmask of flags that controls how the message is submitted. The following flag can be set:

BEGIN_DEFERRED

The MAPI spooler is calling a transport provider with a message whose entry identifier was passed from the transport provider using the IMAPISupport::SpoolerNotifyRYSE6K method s NOTIFY_SENTDEFERRED flag.

lpMessage

[in] Pointer to a message object with read/write access, representing the message to deliver, which is used by the transport provider to access and manipulate that message. This object remains valid until after the transport provider returns from a subsequent call to the IXPLogon::EndMessageIHXUX2 method.

lpulMsgRef

[out] Pointer to a variable in which the transport provider returns the 32-bit reference value it assigned to this message. The MAPI spooler passes this reference value in subsequent calls for this message. The value is initialized to zero by the MAPI spooler before returning it to the transport provider.

lpulReturnParm

[out] Pointer to a variable that corresponds to the MAPI_E_WAIT or MAPI_E_NETWORK_ERROR error value returned by the IXPLogon::SubmitMessage method.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BUSY

The transport provider can t handle the message because it is performing another operation. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage. The MAPI spooler tries the SubmitMessage call again later.

MAPI_E_CANCEL

Although on a previous SpoolerNotify call the transport provider requested the MAPI spooler resubmit the message, conditions have since changed and the message should not be resent. The MAPI spooler goes on to handle something else.

MAPI_E_NETWORK_ERROR

A network error prevented successful completion of the operation. The lpulReturnParm parameter should be set to the number of seconds before the MAPI spooler resubmits the message.

MAPI_E_NOT_ME

The transport provider cannot handle this message. The MAPI spooler should try to find another transport provider for it. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage.

MAPI_E_WAIT

A temporary problem prevents the transport provider from handling the message. The lpulReturnParm parameter should be set to the number of seconds before the MAPI spooler resubmits the message.

Remarks

The MAPI spooler calls the IXPLogon::SubmitMessage method when it has a message for the transport provider to carry. The message is passed to the transport provider 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:

    Put the message into an internal queue to wait for transmission, possibly copying it to local storage, and return.

    Attempt to perform the actual transmission and return when the transmission has completed, either successfully or unsuccessfully.

    Determine whether or not 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 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 32-bit 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::TransportNotify2OI457V method with the NOTIFY_CANCEL_MESSAGE flag set to signal the provider 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 one. The provider should make every effort not to display MAPI_P1 recipient information as part of the transmitted message content, using such recipient information only for addressing purposes. MAPI_P1 recipients are internally-generated recipients for use in resends, 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 opened during the transfer of the message and also processes any attachments. This processing can take a long time. Transport providers running on 16-bit Windows platforms should call the IMAPISupport::SpoolerYieldYSQ8WN callback function 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 originally passed by the MAPI spooler. 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_RESPONSIBILITY5IHLOK property set to TRUE. If PR_RESPONSIBILITY is already set to TRUE, another transport provider handles that recipient. When the provider has completed 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 has completed 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::EndMessageIHXUX2 method.

If an error is returned from SubmitMessage, the MAPI spooler releases the message in process without saving changes. If the transport provider requires message changes be saved, it must call the IMAPIProp::SaveChanges21IFXQ method on the message before returning.

In case of errors occurring because of transport problems, the MAPI spooler retains the message but delays resubmitting it to the transport provider based on the value returned in lpulRetunParm. The transport provider must fill in that value if its return from SubmitMessage is MAPI_E_WAIT or MAPI_E_NETWORK_ERROR. If a severe error condition is occurring, the transport provider must call the IMAPISupport::SpoolerNotifyRYSE6K method with the NOTIFY_CRITICAL_ERROR flag.

See Also