This documentation is archived and is not being maintained.

About the Replication State Machine

Office 2007

This topic contains an overview of the state machine for Outlook data replication.

Bb905250.vs_note(en-us,office.12).gif  Note
The Replication API must be fully implemented according to the instructions in this topic in order to be useful or supported. The Replication API is available exclusively to replicate Outlook changes to and from a server.

IOSTX and the State Machine

A client calls IOSTX::SyncBeg, IOSTX::SyncEnd, IOSTX::SyncHdrBeg, and IOSTX::SyncHdrEnd in a sequence to synchronize Outlook folders and items between a local store and a server. The actual sequence of calls depends on the data that needs to be replicated (for example, a hierarchy of Outlook folders, an Outlook folder, mail items, calendar items, and so on) and the direction of synchronization (whether uploading from the local store to the server, or downloading from the server to the local store). Here is a typical sequence of calls:

  1. The client calls IOSTX::SyncBeg to begin replication, specifying a state identifier and a pointer to an address of a corresponding data structure.
  2. Outlook allocates the data structure and initializes the data structure with the necessary information for the client.
  3. The client performs the replication, updating the data structure to convey to the local store any necessary information about the replication.
  4. After performing the replication, the client calls IOSTX::SetSyncResult and IOSTX::SyncEnd to notify the local store of the completion of the specific replication.
Bb905250.vs_note(en-us,office.12).gif  Note
The client always calls IOSTX::SyncEnd to end a replication that the client has begun for a certain state. Depending on the overall data that the client needs to synchronize, the client may call the pair of calls IOSTX::SyncBeg and IOSTX::SyncEnd more than once.

State Table

The following table lists all the valid states in the replication state machine, along with the corresponding state identifiers and data structures.

Bb905250.vs_note(en-us,office.12).gif  Note
In the Data Replicated column, the term "items" includes mail, calendar, contact, note, journal, and task items. When replicating changes from the local store to the server, use state identifiers specifying "UPLOAD" and data structures with the "UP" prefix (for example, LR_SYNC_UPLOAD_HIERARCHY and UPHIER). When replicating changes from the server to the local store, use state identifiers specifying "DOWNLOAD" and data structures with the "DN" prefix (for example, LR_SYNC_DOWNLOAD_HIERARCHY and DNHIER).
StateData ReplicatedState IdentifierData Structure
Idle stateNoneLR_SYNC_IDLENone
Synchronize stateFolders or itemsLR_SYNCSYNC
Upload hierarchy stateFolders LR_SYNC_UPLOAD_HIERARCHYUPHIER
Upload folder stateFolder LR_SYNC_UPLOAD_FOLDER UPFLD
Synchronize contents stateItems LR_SYNC_CONTENTS SYNCCONT
Upload table stateItems LR_SYNC_UPLOAD_TABLEUPTBL
Upload message stateItem LR_SYNC_UPLOAD_MESSAGEUPMSG
Upload read status state ItemsLR_SYNC_UPLOAD_MESSAGE_READUPREAD
Upload delete status stateItemsLR_SYNC_UPLOAD_MESSAGE_DELUPDEL
Download hierarchy stateFoldersLR_SYNC_DOWNLOAD_HIERARCHYDNHIER
Download table stateItemsLR_SYNC_DOWNLOAD_TABLEDNTBL
Download message header stateMessage headerLR_SYNC_DOWNLOAD_HEADER HDRSYNC

State Transition Diagram

The following diagram shows the state transitions that occur when uploading or performing a full synchronization (downloading followed by uploading) of folders or contents of folders (mail, calendar, contact, note, task, or journal items).

State diagram for the replication state machine.

Example: Uploading a Folder Hierarchy

When uploading a hierarchy of folders, the following sequence of steps takes place:

StepActionStateRelated Data Structure
1.The client initiates the hierarchy upload with IOSTX::SyncBeg. LR_SYNC_UPLOAD_HIERARCHYUPHIER
2.Outlook populates UPHIER with information for the client. This includes initializing the [out] parameters: iEnt is set to 0, and cEnt to the number of folders in the hierarchy that needs uploading.LR_SYNC_UPLOAD_HIERARCHYUPHIER
3.The client does the actual hierarchy upload. As an example, if cEnt is 10, for each of the 10 folders, the client calls IOSTX::SyncBeg, specifying the appropriate state identifier and data structure for uploading a folder. LR_SYNC_UPLOAD_FOLDERUPFLD
4.Outlook populates UPFLD by initializing its [out] parameters, including the reason for the folder upload, the pointer to the folder object, and the entry ID for the folder.LR_SYNC_UPLOAD_FOLDERUPFLD
5.The client uploads the specified folder.LR_SYNC_UPLOAD_FOLDERUPFLD
6. The client notifies the local store of the completion of the folder upload: Upon success, the client sets the [in] parameter ulFlags in UPFLD with UPF_OK, and then calls IOSTX::SetSyncResult (S_OK) and IOSTX::SyncEnd. Upon failure, the client would not set ulFlags with the UPF_OK flag. It calls IOSTX::SetSyncResult, passing in the HRESULT value, and IOSTX::SyncEnd. LR_SYNC_UPLOAD_FOLDERUPFLD
7.If UPF_OK is set, Outlook will clear the internal request for uploading the folder. Then regardless of the state of ulFlags, it will clean up any internal bookkeeping information. While there are still folders in the hierarchy to upload (iEnt is still less than cEnt), the client and Outlook repeat steps 3 through 7.LR_SYNC_UPLOAD_FOLDERUPFLD
8.The client notifies the local store of the completion of the hierarchy upload: Upon success, the client sets the [in] flag in UPHIER with UPH_OK, and then calls IOSTX::SetSyncResult (S_OK) and IOSTX::SyncEnd. Upon failure, the client would not set the UPH_OK flag. It calls IOSTX::SetSyncResult, passing in the HRESULT value, and IOSTX::SyncEnd. LR_SYNC_UPLOAD_HIERARCHYUPHIER
9.If UPH_OK is set, Outlook will clear the internal request for uploading the hierarchy. Then regardless of the state of ulFlags, it will clean up any internal bookkeeping information. LR_SYNC_UPLOAD_HIERARCHYUPHIER

See Also

About the Replication API
Constants for the Replication API
SYNCSTATE


Show: