About the Replication State Machine
Applies to: Office 2010 | Outlook 2010 | Visual Studio
In this article
IOSTX and the State Machine
State Table
State Transition Diagram
Example: Uploading a Folder Hierarchy
This topic contains an overview of the state machine for Microsoft Outlook 2010 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 2010 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 2010 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 2010 folders, an Outlook 2010 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 2010 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
Note
The following table lists all the valid states in the replication state machine, along with the corresponding state identifiers and data structures. 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).
State |
Data Replicated |
State Identifier |
Data Structure |
None |
LR_SYNC_IDLE |
None |
|
Folders or items |
LR_SYNC |
||
Folders |
LR_SYNC_UPLOAD_HIERARCHY |
||
Folder |
LR_SYNC_UPLOAD_FOLDER |
||
Items |
LR_SYNC_CONTENTS |
||
Items |
LR_SYNC_UPLOAD_TABLE |
||
Item |
LR_SYNC_UPLOAD_MESSAGE |
||
Items |
LR_SYNC_UPLOAD_MESSAGE_READ |
||
Items |
LR_SYNC_UPLOAD_MESSAGE_DEL |
||
Folders |
LR_SYNC_DOWNLOAD_HIERARCHY |
||
Items |
LR_SYNC_DOWNLOAD_TABLE |
||
Message header |
LR_SYNC_DOWNLOAD_HEADER |
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).
@@@@@NEED TO INSERT ART HERE THAT IS MISSING@@@@@@
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 2010 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 2010 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 2010 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 2010 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 2010 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_HIERARCHY |
UPHIER |