• Article

Working with Synchronous Events

Topic Last Modified: 2006-06-12

The following information is important when working with synchronous events:

  • Moving a folder does not cause events to occur on any items in the folder.
  • Copying a folder causes events to occur on all items in the folder.
  • Deleting a folder does not cause events to occur on items (messages and documents) in the folder. However, it causes events to occur on the subfolders.
  • Synchronous events are processed in a specific order. For more information, see Event Notification Priority.
  • The item causing the event is passed into the sink in the context of an OLE DB local transaction.
  • An item passed to a synchronous event sink transaction does not exist in the Exchange store until the transaction has been committed.
  • While the event sink is processing a synchronous event, it can abort the OLE DB local transaction. If the transaction is aborted, no further synchronous event notifications occur for this event. The synchronous events in this transaction that have already been notified (processed) are again notified that the transaction was aborted. This is the abort phase. This notification allows you to clean up data or undo activities. For example, the method that handles the synchronous OnSyncSave event might create an associated file outside of the Exchange store. Upon notification of failure, your method might delete that external file.
  • Aborting the transaction associated with a delete event prevents the item from being deleted. If you abort an event that is the result of a move, both the save and delete steps of the move are aborted. This means that the original item is not deleted and the new item is not saved.

Note

E-mail messages that are processed in event sinks must be compliant with RFC 822. They also must end with a carriage return/line feed (CR/LF).

The following illustration shows how event sinks affect an Exchange store item.

Aa579423.9dfab400-e4c2-4225-807a-c30fd857ea92(en-us,EXCHG.80).gif

The sequence of an event sink for an Exchange store item is as follows:

  1. The event occurs in the store.

  2. A transaction image of the item is created.

  3. Synchronous event methods receive event notification of the begin phase. In this phase, the methods modify the image.

  4. The image is committed to the store as the item from the OLE DB transaction.

  5. Synchronous event methods receive event notification of the commit phase.

  6. Asynchronous interface methods in sink classes receive notifications. The store item is directly modified.

    Note

    Asynchronous events are not processed in any specified or guaranteed order. The event source does not wait for asynchronous events to finish.

As the previous illustration shows, synchronous events are always called twice: once for the begin phase, and once for the commit or abort phase. To determine which type of call is being made, add code to your methods for handling synchronous events. The filter in an OnSyncSave Method might look like the following example:

Example

C++

if( lFlags & EVT_SYNC_BEGIN ) {
    Log(pLog,"-----------EVT_SYNC_BEGIN-----------\r\n");
    // Handle the sink here.
}
else if( lFlags & EVT_SYNC_COMMITTED ) {
    Log(pLog,"---------EVT_SYNC_COMMITTED---------\r\n");
    // Handle the commit here.
}
else if( lFlags & EVT_SYNC_ABORTED ) {
    Log(pLog,"----------EVT_SYNC_ABORTED----------\r\n");
    // Handle the abort here.
}

For a support interface that allows you to save data between the begin phase and the commit or abort phase of an event, see the IUserData Interface.

See Also

Other Resources

Support Interfaces