3.1.5.8 Monitoring Folders for New Items

  • Article

The client uses the Ping command (as specified in section 2.2.1.13) to monitor a folder or set of folders for changes. The client MUST include a HeartbeatInterval element (as specified in section 2.2.3.88.1) in the initial Ping command request to specify an amount of time that the server SHOULD wait before sending a response if there are no new items added to the included folders. The server MUST cache the value of the HeartbeatInterval element and use it in subsequent Ping requests that do not include a HeartbeatInterval element.

The client MUST include a Folders element (as specified in section 2.2.3.75.2) in the initial Ping command request to specify one or more folders that the server will monitor for additions. The server MUST cache the list of included folders and use it in subsequent Ping requests that do not include a Folders element.

Because the server caches the values of the HeartbeatInterval element and the Folders element, the client can omit either element, or both from subsequent Ping requests if those parameters have not changed from the previous Ping request. If neither the heartbeat interval nor the folder list has changed, the client can issue an empty Ping request – one with no XML body. The server will use the previously cached XML sent by the client if it receives an empty Ping request

The server uses the last airsync:SyncKey element (as specified in section 2.2.3.181.4) value returned to the client when determining what to report in the Ping response. Therefore, the client MUST have received the response to its last Sync request (as specified in section 2.2.1.21) and successfully applied the changes sent by the server, prior to issuing a Ping request.

The server SHOULD delay sending a response until either of the following conditions are met:

  • The interval specified by the HeartbeatInterval element has elapsed.

  • An item is added to one or more of enumerated collections. This condition includes new mail being delivered and items being copied or moved into the collection.

The server SHOULD NOT send the response before the interval specified by the HeartbeatInterval element for any other changes to a collection, including items being modified, items being deleted, or items being moved out of the collection.

In the case of no changes on the server, the client can then reissue a new Ping request. In the case of changes, the response indicates in which folders those changes occurred so that the client can resynchronize those folders.

Note that if no changes occur in any of the folders that are specified by the client for a significant length of time (longer than the value of the HeartbeatInterval element (section 2.2.3.88.1)), the client can run in a loop in which it issues a Ping request, receives a response indicating that there are no changes, and then reissues the Ping request. The length of time that the server waits before issuing a response is called the heartbeat interval.