OnArrival Method

The OnArrival method is called by the Simple Mail Transfer Protocol (SMTP) event dispatcher on registered OnArrival event sinks when a new message arrives to the SMTP service.

[Visual Basic]
Sub OnArrival(ByVal Msg as CDO.Message, EventStatus as CdoEventStatus)
[C++]
HRESULT OnArrival(IMessage* Msg, CdoEventStatus* EventStatus);
[IDL]
HRESULT OnArrival([in] IMessage* Msg, [in,out] CdoEventStatus* EventStatus);

Parameters

Msg

The IMessage interface on a Message object holding the message that arrived.

EventStatus

On return, the status of the event. The event sink signals to the dispatcher whether to continue notifying subsequent event sinks, or to stop and return. The CdoEventStatus enumeration contains the possible values for this parameter.

Remarks

The Message object that is passed to the OnArrival method is in unexpanded format; the recipient addresses have not been resolved or expanded, and thus, are still in the format in which the sending message transfer agent placed them in the message envelope.

For SMTP OnArrival events, the message content is read-write and can be modified by the sink. Additionally, some of the envelope fields can be modified. For more information, see SMTP/NNTP Transport Event Sinks with CDO.

The passed CDO Message object is bound to an ADO Stream object containing the message contents within the SMTP transport. The IDataSource.SourceClass property returns "_Stream". To commit any changes you make to the transport content, call IDataSource.Save. This does not affect the EnvelopeFields collection. Changes to the EnvelopeFields collection for the message are committed to the transport using the Fields.Update method.

If you want to rebind the Message object to another object, make sure to cache the reference to the ADO Stream object in the transport using the IDataSource.Source property. If you rebind the Message object (using IDataSource.OpenObject or IDataSource.SaveToObject) without caching this reference, you will not be able to rebind the Message object to the transport stream.

The OnArrival event for the SMTP service is synchronous, which means that the event dispatcher thread is blocked for the duration of time required for all bound event sinks to be created (if necessary) and executed, or until a sink preemptively stops event notifications by returning the EventStatus parameter with the value cdoSkipRemainingSinks.

See Also

SMTP/NNTP Transport Event Sinks with CDO

CdoEventStatus Enum

IMessage Interface

IDataSource Interface

IDataSource.Source Property