Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

About the Replication State Machine

Last modified: June 25, 2012

Applies to: Outlook

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 2013 and Microsoft Outlook 2010 data replication.

Note 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 2013 or Outlook 2010 changes to and from a server.

A client calls IOSTX::SyncBeg, IOSTX::SyncEnd, IOSTX::SyncHdrBeg, and IOSTX::SyncHdrEnd in a sequence to synchronize Outlook 2013 or 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 2013 or Outlook 2010 folders, an Outlook 2013 or 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:

  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 2013 or Outlook 2010 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.

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

Note 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

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

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@@@@@@

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 2013 or 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 2013 or 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 2013 or 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 2013 or 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 2013 or 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

Show:
© 2015 Microsoft