Synchronous Event Details

[This is preliminary documentation and subject to change.]

The following information is important to know when developing the interfaces for synchronous event sinks.

• Moving, copying or deleting a parent folder will not cause a synchronous event notification.
• Synchronous events are processed in a specific order.
• Synchronous events can abort synchronous events yet to be processed.
• The item causing the event that is passed into your sink is in the context of an OLE DB local transaction.
• When you are processing a synchronous event you can cancel the OLE DB local transaction that caused the event. If you cancel the transaction, no further synchronous events will be processed. Also, the synchronous events in this transaction that have already been processed are notified that the transaction was aborted. This notification allows you to clean up data or undo activities if the event does not occur. For example, your method that handles the synchronous OnSave event may create an associated file outside of the Exchange Store. Upon notification of failure, your method could delete that external file.
• Aborting the transaction associated with a delete will prevent the item from being deleted. If you abort an event that is the result of a move, then both the save and delete steps of the move will be aborted. This means that the original item will not be deleted and the new item will not be saved.
• Saving or deleting an item to the Web Store does not occur until all OnSyncSave, or OnSyncDelete event sinks have completed (without aborting the transaction).

The item being passed through the synchronous event transaction is not the item in the Web Store. The item being passed is the item in transition--a copy. Additionally, for the OnSyncSave event, the sink is given a URL to an original image of the item before any synchronous events were called.

The following illustration shows a Web Store item and how event sinks affect it.

1. The event occurs in the store.
2. An image is created of the Item.
3. 8Synchronous interface methods in sink classes receive notification of the synchronous event and modify then image.
4. The image is committed to the store as the item (from the OLE DB Transaction).
5. Synchronous interface methods in sink classes receive notification of the commit phase.
6. Asynchronous interface methods in sink classes receive notifications. The store Item is directly modified.

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

As the above illustration shows, Synchronous events are always called twice, once for the transaction and once for commit or abort. It is important to add code in your methods for handling synchronous events to determine which type of call is being made. The filter in an IExStoreSyncEvents::OnSyncSave method could look like this:

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.
}

An item created during the context of a transaction does not exist in the Web Store until the transaction has been committed. Actions performed within a transaction will not cause another event to occur until the transaction has been committed. This means that if an OnSyncSave sink saves some other item, the Web Store processes the new OnSave event only after the current transaction is committed. Additionally, it is not possible to create an item and then open it using IBindResource::Bind without first committing the transaction.