This topic contains an overview of the state machine for Outlook data replication.
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:
The client calls IOSTX::SyncBeg to begin replication, specifying a state identifier and a pointer to an address of a corresponding data structure.
Outlook allocates the data structure and initializes the data structure with the necessary information for the client.
The client performs the replication, updating the data structure to convey to the local store any necessary information about the replication.
After performing the replication, the client calls IOSTX::SetSyncResult and IOSTX::SyncEnd to notify the local store of the completion of the specific replication.
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.
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).
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).
Example: Uploading a Folder Hierarchy
When uploading a hierarchy of folders, the following sequence of steps takes place:
Step
Action
State
Related Data Structure
1.
The client initiates the hierarchy upload with IOSTX::SyncBeg.
LR_SYNC_UPLOAD_HIERARCHY
UPHIER
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_HIERARCHY
UPHIER
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_FOLDER
UPFLD
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_FOLDER
UPFLD
5.
The client uploads the specified folder.
LR_SYNC_UPLOAD_FOLDER
UPFLD
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_FOLDER
UPFLD
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_FOLDER
UPFLD
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_HIERARCHY
UPHIER
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.