3.1.5.3 Synchronizing a Folder Hierarchy
This section specifies how the client uses the FolderSync command (section 2.2.1.5) to replicate the folder hierarchy of the user's mailbox on the client.
The client initiates folder synchronization by sending an initial FolderSync command request to the server with a folderhierarchy:SyncKey element (section 2.2.3.181.2) value of zero (0). The server responds with a new folderhierarchy:SyncKey element value and provides a list of all the folders in the user's mailbox. The folders are identified by a folderhierarchy:ServerId element (section 2.2.3.166.4), which can then be used in a Sync command (section 2.2.1.21) to synchronize the items in those folders.
Additional folder synchronizations can be performed by using the folderhierarchy:SyncKey element value from the initial FolderSync command response to get folder additions, deletions, or updates from the server. At any point, the client can repeat the initial FolderSync command, sending a SyncKey element value of zero (0), and resynchronizing the entire hierarchy. Existing folderhierarchy:ServerId values do not change when the client resynchronizes.
The client can use the GetItemEstimate command (section 2.2.1.9) to obtain an estimate of the number of items that need to be synchronized in a collection, which is useful when the client UI displays a progress bar while it retrieves items from the server. The client can also limit the number of changed items returned in the Sync response by submitting the airsync:WindowSize element (section 2.2.3.199), which specifies the maximum number of items to synchronize at one time. If the number of items returned is larger than the value specified by the airsync:WindowSize element, the airsync:MoreAvailable element (section 2.2.3.116) is returned in the Sync command response. The client then continues to call the Sync command (section 2.2.1.21) until no more items are available.
The following table lists the command sequence for folder hierarchy synchronization.
The asterisk (*) in the Order column means that a step is run once and can be repeated multiple times.
|
Order |
Client action |
Server action |
|---|---|---|
|
1 |
The client sends the FolderSync command with the folderhierarchy:SyncKey element set to zero (0) to get the folder hierarchy and the folderhierarchy:ServerId values of all the folders. |
The server responds with the folder hierarchy and a new folderhierarchy:SyncKey value. The client stores the names and folderhierarchy:ServerId values of all folders that can be synchronized. |
|
2* |
The client sends the FolderSync command with the new folderhierarchy:SyncKey value to update the folder hierarchy. |
If any changes have occurred on the server, the new, deleted, or changed folders are returned to the client. |
The folder hierarchy is now populated on the client and ready for the contents of the folders to be synchronized.
If the FolderSync response contains a Status element value of 9 (see section 2.2.3.177.5), the client's local copy of the folder hierarchy list can no longer be considered valid. The client SHOULD<23> restart the synchronization process with a synchronization key of 0. Any changes that were sent in the FolderSync request were not applied to the server.