About the Replication State Machine [Outlook 2003 API Reference]
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).
| State | Data Replicated | State Identifier | Data Structure |
| Idle state | None | LR_SYNC_IDLE | None |
| Synchronize state | Folders or items | LR_SYNC | SYNC |
| Upload hierarchy state | Folders | LR_SYNC_UPLOAD_HIERARCHY | UPHIER |
| Upload folder state | Folder | LR_SYNC_UPLOAD_FOLDER | UPFLD |
| Synchronize contents state | Items | LR_SYNC_CONTENTS | SYNCCONT |
| Upload table state | Items | LR_SYNC_UPLOAD_TABLE | UPTBL |
| Upload message state | Item | LR_SYNC_UPLOAD_MESSAGE | UPMSG |
| Upload read status state | Items | LR_SYNC_UPLOAD_MESSAGE_READ | UPREAD |
| Upload delete status state | Items | LR_SYNC_UPLOAD_MESSAGE_DEL | UPDEL |
| Download hierarchy state | Folders | LR_SYNC_DOWNLOAD_HIERARCHY | DNHIER |
| Download table state | Items | LR_SYNC_DOWNLOAD_TABLE | DNTBL |
| Download message header state | Message header | LR_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).
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. | LR_SYNC_UPLOAD_HIERARCHY | UPHIER |