IXPLogon::TransportNotify

The IXPLogon::TransportNotify method signals the occurrence of an event about which the transport provider has requested notification.

Quick Info

See IXPLogon : IUnknown.

HRESULT TransportNotify(
  ULONG FAR * lpulFlags,   
  LPVOID FAR * lppvData  
);

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 deferred. 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 deferred by calling the IMsgStore::AbortSubmit method.

NOTIFY_BEGIN_INBOUND

The MAPI spooler can now accept inbound messages for this transport provider session. The MAPI spooler regularly calls the IXPLogon::Poll method if the transport provider set the flag LOGON_SP_POLL with the IXPProvider::TransportLogon 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::SpoolerNotify method. The status table row for the transport provider session should be updated before returning by calling the IMAPISupport::ModifyStatusRow 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_CODE 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::TransportNotify method call with the flag NOTIFY_END_INBOUND_FLUSH set, the provider should not call the IMAPISupport::SpoolerYield method or otherwise give up cycles to the operating system in order to speed delivery of incoming messages. This is acceptable because the MAPI spooler typically only uses this notification in response to a user's request, via a client application, to deliver all messages now. 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::SubmitMessage 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 inbound message that is currently being processed, the transport provider should save the incoming message wherever it is presently stored and deliver it again 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 be completed. 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 inbound 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 outbound message currently being sent, it should not be stopped; to stop delivery of 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 inbound or outbound 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.

Notes to Implementers

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. This is most likely when the MAPI spooler signals the cancellation of a message that the transport provider has started sending.