3.1.5.4 Synchronizing Inbox, Calendar, Contacts, and Tasks Folders
The client synchronizes the contents of individual folders by using the Sync command (section 2.2.1.21). The client can synchronize the Inbox folder, Calendar folder, or Contacts folder, or any folder within the mailbox after the folder hierarchy has been populated by the FolderSync command (section 2.2.1.5), as specified in section 3.1.5.3. Clients MUST NOT synchronize the Drafts folder when using version 2.5, 12.0, 12.1, 14.0, or 14.1 of this protocol.
In order to synchronize the content of each of the folders, an initial synchronization key for each folder MUST be obtained from the server. The client obtains the key by sending the server an initial Sync request with a airsync:SyncKey element (section 2.2.3.181.4) value of zero (0) and the airsync:CollectionId element (section 2.2.3.30.6) value that identifies the folder to be synchronized. The Sync command response includes a new airsync:SyncKey value, which is generated by the server for each transaction.
Figure 4 Retrieval of SyncKey value
The airsync:SyncKey issued in the initial Sync response MUST be stored by the client, and is sent in the second Sync request. The second Sync request includes the new airsync:SyncKey element as well as the airsync:GetChanges (section 2.2.3.84) element.
Figure 5 Retrieval of folder content
The server responds by adding all the items in the collection to the client and returning a new airsync:SyncKey element value, which can be used in successive synchronizations. The order of items in the response is implementation-specific. Clients SHOULD NOT rely on any specific ordering of items in the response. The client deletes its copy of all objects in the collection that are being synchronized before the client performs a full synchronization. The client can use the GetItemEstimate command (section 2.2.1.9) to obtain an estimate of the number of items that have to be synchronized before completely synchronizing a collection, which is useful when the client user interface displays a progress bar while getting items from the server. In some cases, the client could have to submit a airsync:WindowSize element (section 2.2.3.199) that specifies the number of items to be synchronized at a time.
If more items remain to be synchronized, 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 until no more items are available. For more details about the airsync:WindowSize element of the Sync command, see section 2.2.3.199.
After a full synchronization has been performed on a collection, successive synchronizations are used to obtain additions, deletions, or changes to the initial collection state. The client can use the Sync command request to add, delete, or change items on the server, and the server can use the Sync command response to add, delete, or change items on the client.
The following table lists the command sequence for folder synchronization.
The asterisk (*) in the Order column means that the step can be repeated multiple times. [n] means that a step is optional.
|
Order |
Client action |
Server action |
|---|---|---|
|
1 |
The client sends the Sync command for the Email, Calendar, Contacts, and/or Tasks collection with a synchronization key of zero (0). This establishes a partnership with the server, initializing server data for the device. |
The server responds with the synchronization key for the collection, to be used in successive synchronizations. |
|
2* |
The client sends the Sync command with a synchronization key of zero (0) for other collections to be synchronized. |
The server responds with new synchronization keys for each collection. |
|
[3] |
The client sends the GetItemEstimate command for all collections to be synchronized. This step can be skipped if it is not required by the client UI. |
The server responds to indicate how many items will be added, changed, or deleted, for each collection. |
|
4* |
The client sends the Sync command with the airsync:GetChanges element for a collection. The command SHOULD include the airsync:WindowSize element, the recommended value for which is 100. This step is repeated for each collection to be synchronized or all collections can be combined into one request. |
The server responds with airsync:Add (section 2.2.3.7.2), airsync:Change (section 2.2.3.24), or airsync:Delete (section 2.2.3.42.2) elements for items in the collection. If the response contains the airsync:MoreAvailable element, this step is repeated. |
The client can use the airsync:WindowSize element to break the server airsync:Add elements into multiple sets of items. The recommended window size is 100. For more details about the airsync:WindowSize element used by the Sync command, see section 2.2.3.199.
When the Sync command request contains a HeartbeatInterval element (section 2.2.3.88.2) or a Wait element (section 2.2.3.198), the server SHOULD delay sending a response until either of the following conditions are met:
The interval specified by the HeartbeatInterval element or Wait element has elapsed.
An item is added to one or more of the enumerated collections. This condition includes new mail being delivered and items being copied or moved into the collection.
In most cases, the server SHOULD NOT send the response before the interval specified by the HeartbeatInterval element or Wait element for any other changes to the collection, including items being modified, items being deleted, items being moved out of the collection, or items being soft deleted due to falling out of scope of a synchronization filter, as specified in section 2.2.3.68.2. However, if the Sync command request includes an Add or Change element, and the addition or change does not involve only flags, the server SHOULD return immediately, regardless of the current HeartbeatInterval or Wait value.