Client should always set 'seq' to be the highest known value it has received from the server. The server will use this information to retransmit lost data.
If the client sends a last known sync token then the notification is calculated by comparing the accounts current token with the client's last known.
If the client does not send a last known sync token, then notification is based on change since last Wait (or change since <add> if this is the first time Wait has been called with the account)
The client may specify a custom timeout-length for their request if they know something about the particular underlying network. The server may or may not honor this request (depending on server configured max/min values). See LocalConfig values:
zimbra_waitset_default_request_timeout, zimbra_waitset_min_request_timeout, zimbra_waitset_max_request_timeout, zimbra_admin_waitset_default_request_timeout, zimbra_admin_waitset_min_request_timeout, and zimbra_admin_waitset_max_request_timeout
WaitSet: scalable mechanism for listening for changes to one or more accounts
| Authorization token required | true |
| Admin Authorization token required | false |
<WaitSetRequest waitSet="{waitset-id}" seq="{waitset-last-known-seq-no}" [block="{waitset-block} (0|1)"]
[defTypes="{default-interests}"] [timeout="{waitset-timeout-length} (Long)"]
[expand="{expand} (0|1)"]> ## WaitSetRequest
<add>
(<a [name="{account-name}"] [id="{account-id}"] [token="{last-known-sync-token}"] [types="{waitset-types}"]
[folderInterests="{waitset-folder-interests}"] /> ## WaitSetAddSpec)*
</add>
<update>
(<a ... /> ## See /add/a [ ## WaitSetAddSpec])*
</update>
<remove>
(<a [id="..."] /> ## Id)*
</remove>
</WaitSetRequest>
elements and attributes you can define within a
<WaitSetRequest> element:
| XPath | Required / Optional | Description | ||||||||||||||
| @waitSet | Required (only 1) | Type: String Waitset ID |
||||||||||||||
| @seq | Required (only 1) | Type: String Last known sequence number |
||||||||||||||
| @block | Optional (0 or 1) | Type: 0|1 Flag whether or not to block until some account has new data |
||||||||||||||
| @defTypes | Optional (0 or 1) | Type: String Default interest types: comma-separated list. Currently:
This is used if types isn't specified for an account |
||||||||||||||
| @timeout | Optional (0 or 1) | Type: Long Timeout length |
||||||||||||||
| @expand | Optional (0 or 1) | Type: 0|1 boolean flag. If true, WaitSetResponse will include details of Pending Modifications. |
||||||||||||||
| /add | Required (only 1) | |||||||||||||||
| /add/a | Optional (0 or more) | |||||||||||||||
| /add/a@name | Optional (0 or 1) | Type: String Name of account |
||||||||||||||
| /add/a@id | Optional (0 or 1) | Type: String ID of account. Ignored if name is supplied |
||||||||||||||
| /add/a@token | Optional (0 or 1) | Type: String Last known sync token |
||||||||||||||
| /add/a@types | Optional (0 or 1) | Type: String interest types: comma-separated list. Currently:
If not specified, the value of defTypes in the request is used |
||||||||||||||
| /add/a@folderInterests | Optional (0 or 1) | Type: String Comma separated list of IDs for folders. |
||||||||||||||
| /update | Required (only 1) | |||||||||||||||
| /update/a | Optional (0 or more) | See /add/a for more details. | ||||||||||||||
| /remove | Required (only 1) | |||||||||||||||
| /remove/a | Optional (0 or more) | |||||||||||||||
| /remove/a@id | Optional (0 or 1) | Type: String ID |
<WaitSetResponse waitSet="{waitset-id}" [canceled="(0|1)"] [seq="{sequence-num}"]> ## WaitSetResponse
(<a [id="{account-id}"] [changeid="{change-id} (int)"]> ## AccountWithModifications
(<mods id="{id} (Integer)"> ## PendingFolderModifications
(<created> ## CreateItemNotification
<m t="{item-type}" f="{flags} (Integer)" tn="{tag-names}" id="{msg-id} (int)" i4uid="{imap-uid} (int)" /> ## ImapMessageInfo
</created>)*
(<deleted id="(int)" t="..." /> ## DeleteItemNotification)*
(<modMsgs change="(int)"> ## ModifyNotification$ModifyItemNotification
<m ... /> ## See /a/mods/created/m [ ## ImapMessageInfo]
</modMsgs>)*
(<modTags change="(int)"> ## ModifyNotification$ModifyTagNotification
<id>{id} (int)</id>
<name>{name} (String)</name>
</modTags>)*
(<modFolders id="(int)" path="..." change="(int)" /> ## ModifyNotification$RenameFolderNotification)*
</mods>)*
</a>)*
(<error id="..." type="..." /> ## IdAndType)*
</WaitSetResponse>
elements and attributes you can define within a
<WaitSetResponse> element:
| XPath | Required / Optional | Description |
| @waitSet | Required (only 1) | Type: String WaitSet ID |
| @canceled | Optional (0 or 1) | Type: 0|1 1(true) if canceled |
| @seq | Optional (0 or 1) | Type: String Sequence number |
| /a | Optional (0 or more) | Information on signaled accounts.
If folder IDs are included then changes only affect those folders. |
| /a@id | Optional (0 or 1) | Type: String Account ID |
| /a@changeid | Optional (0 or 1) | Type: int ID of the last change |
| /a/mods | Optional (0 or more) | serialized pending modifications per folder TODO: instead of a string this should be a structure that contains enough data to instantiate PendingRemoteModifications |
| /a/mods@id | Required (only 1) | Type: Integer ID of signaled folder |
| /a/mods/created | Optional (0 or more) | list of created items |
| /a/mods/created/m | Required (only 1) | message info of created item |
| /a/mods/created/m@t | Required (only 1) | Type: String Item type |
| /a/mods/created/m@f | Required (only 1) | Type: Integer Flags |
| /a/mods/created/m@tn | Required (only 1) | Type: String Comma separated list of name of tags associated with this item |
| /a/mods/created/m@id | Required (only 1) | Type: int Message ID |
| /a/mods/created/m@i4uid | Required (only 1) | Type: int IMAP UID |
| /a/mods/deleted | Optional (0 or more) | list of deleted items |
| /a/mods/deleted@id | Required (only 1) | Type: int ID of deleted item |
| /a/mods/deleted@t | Required (only 1) | Type: String type of deleted item |
| /a/mods/modMsgs | Optional (0 or more) | list of modified messages |
| /a/mods/modMsgs@change | Required (only 1) | Type: int bitmask of modification change |
| /a/mods/modMsgs/m | Required (only 1) | See /a/mods/created/m for more details. |
| /a/mods/modTags | Optional (0 or more) | list of modified tags |
| /a/mods/modTags@change | Required (only 1) | Type: int bitmask of modification change |
| /a/mods/modTags/id | Required (only 1) | Type: {id} (int) |
| /a/mods/modTags/name | Required (only 1) | Type: {name} (String) |
| /a/mods/modFolders | Optional (0 or more) | list of renamed folders |
| /a/mods/modFolders@id | Required (only 1) | Type: int |
| /a/mods/modFolders@path | Required (only 1) | Type: String |
| /a/mods/modFolders@change | Required (only 1) | Type: int bitmask of modification change |
| /error | Optional (0 or more) | Error information |
| /error@id | Required (only 1) | Type: String ID |
| /error@type | Required (only 1) | Type: String Type |