IXPLogon::TransportNotify

The IXPLogon::TransportNotify method signals in a transport provider session the occurrence of an event for the MAPI spooler about which the provider requested notification.

Quick Info

See IXPLogon : IUnknownHVE6L8.

HRESULT TransportNotify(

Parameters

lpulFlags

[in, out] Bitmask of flags that signals notification events. The following flags can be set by the MAPI spooler on input and must be returned unchanged on output:

NOTIFY_ABORT_DEFERRED

Notifies the transport provider that a message for which it accepted responsibility is being canceled. Only transport providers that support deferral must support this flag. The lppvData parameter points to the entry identifier of the canceled message. Messages that have not been processed by the MAPI spooler can still be canceled by calling the IMsgStore::AbortSubmitETMTIF method.

NOTIFY_BEGIN_INBOUND

Inbound messages can now be accepted for this transport provider session. The MAPI spooler regularly calls the IXPLogon::PollCC7S3H method if the transport provider set the flag LOGON_SP_POLL with the IXPProvider::TransportLogonAGE6K0 call at logon. Once the NOTIFY_BEGIN_INBOUND flag is set, the MAPI spooler honors the NOTIFY_NEWMAIL flag passed in the call to the IMAPISupport::SpoolerNotifyRYSE6K method. The status table row for the transport provider session should be updated before returning by calling the IMAPISupport::ModifyStatusRowF5S5Z4 method. NOTIFY_BEGIN_INBOUND is mutually exclusive with the NOTIFY_END_INBOUND flag.

NOTIFY_BEGIN_INBOUND_FLUSH

Signals the transport provider to cycle through inbound messages as quickly as possible. To comply with this notification, the transport provider should set the flag STATUS_INBOUND_FLUSH in the PR_STATUS_CODE7DOHP8 property of its status table row as soon as it can, using ModifyStatusRow. Until the end of this inbound messaging cycle, which is when the provider determines it has downloaded all it can or when it has received an IXPLogon::TransportNotify2OI457V method call with the flag NOTIFY_END_INBOUND_FLUSH set, the provider should not call the IMAPISupport::SpoolerYieldYSQ8WN method or otherwise give up cycles to the operating system that can be used to speed delivery of incoming messages. At the end of the inbound flush operation, the provider should use SpoolerNotify to clear the STATUS_INBOUND_FLUSH flag in the PR_STATUS_CODE property of its status row.

NOTIFY_BEGIN_OUTBOUND

Outbound operations can now occur for this transport provider session. If there are any messages to be sent for this provider, a call to the IXPLogon::SubmitMessage1ZHZV4 method follows. The status table row for this session should be updated before returning. The NOTIFY_BEGIN_OUTBOUND flag is mutually exclusive with the NOTIFY_END_OUTBOUND flag.

NOTIFY_BEGIN_OUTBOUND_FLUSH

Works similarly to the NOTIFY_BEGIN_INBOUND_FLUSH flag but refers to outbound messages, and the appropriate status flag is STATUS_OUTBOUND_FLUSH.

NOTIFY_CANCEL_MESSAGE

The MAPI spooler must cancel transfer of the message for which the lppvData parameter points to the 32-bit value obtained with the IXPLogon::SubmitMessage method call. The NOTIFY_CANCEL_MESSAGE flag can be set without the transport provider having returned from the SubmitMessage, IXPLogon::StartMessage, or IXPLogon::EndMessage method call associated with the message. The transport provider must return from the entry point that is handling the canceled message as soon as possible.

For an in-process incoming message, the transport provider should retain the incoming message wherever it is presently stored and pass it at the next convenient time. The message object data already stored for the incoming message is discarded.

If the transport provider did not update this 32-bit value at StartMessage or SubmitMessage time, it is 0 for outbound messages and 1 for inbound messages.

NOTIFY_END_INBOUND

Inbound operations must cease for this transport provider session. The MAPI spooler ceases to use Poll and ignores NOTIFY_NEWMAIL for this session. In-process messages should not be aborted. The status table row for the transport session should be updated by calling ModifyStatusRow before returning. NOTIFY_END_INBOUND is mutually exclusive with NOTIFY_BEGIN_INBOUND.

NOTIFY_END_INBOUND_FLUSH

Notifies the transport provider to come out of flush mode. The transport provider should not stop downloading, but downloading should be done in the background. The status table row for the transport session should be updated by calling ModifyStatusRow when the transport provider can comply with this notification.

NOTIFY_END_OUTBOUND

Outbound operations must cease for this transport provider session. The MAPI spooler ceases to call SubmitMessage and ignores the SpoolerNotify flag NOTIFY_READYTOSEND. If there is an in-process message, it should not be stopped; to stop a message, use the NOTIFY_CANCEL_MESSAGE flag. The status table row for this session should be updated by calling ModifyStatusRow before returning. NOTIFY_END_INBOUND is mutually exclusive with NOTIFY_BEGIN_OUTBOUND.

NOTIFY_END_OUTBOUND_FLUSH

Works similarly to NOTIFY_END_INBOUND_FLUSH but refers to outbound messages, and the appropriate status flag is STATUS_OUTBOUND_FLUSH.

lppvData

[out] Pointer to a pointer to event-specific data. For more information on what lppvData holds, see the description for the lpulFlags parameter.

Return Values

S_OK

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

Remarks

The MAPI spooler calls the IXPLogon::TransportNotify method to signal to the transport provider the occurrence of events about which notification has been requested. These events include the MAPI spooler s requiring the cancellation of transfer for a message, the beginning or ending of inbound or outbound transport operations, and the beginning or ending of an operation to clear an incoming or outgoing message queue.

When the user tries to cancel a message that the transport provider has previously deferred, the MAPI spooler calls TransportNotify passing in both the NOTIFY_ABORT_DEFERRED and NOTIFY_CANCEL_MESSAGE flags in ulFlags. If the MAPI spooler is logging off and still has messages in the queue, it passes only NOTIFY_ABORT_DEFERRED in ulFlags when it calls TransportNotify.

The provider must synchronize access to its data on this call, because the MAPI spooler can invoke this method from another thread of execution or from a procedure for a different window.

See Also