Service: zimbraAdmin
Namespace: "urn:zimbraAdmin"
AdminWaitSet SOAP Command

AdminWaitSetRequest optionally modifies the wait set and checks for any notifications. If block=1 and there are no notifications, then this API will BLOCK until there is data.

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 true

AdminWaitSetRequest

    <AdminWaitSetRequest waitSet="{waitset-id}" seq="{waitset-last-known-seq-no}" [block="{waitset-block} (0|1)"]
                            [defTypes="{default-interests}"] [timeout="{waitset-timeout-length} (Long)"]> ## AdminWaitSetRequest
        <add>
            (<a [name="{waitset-name}"] [id="{waitset-id}"] [token="{last-known-sync-token}"] [types="{waitset-types}"] /> ## WaitSetAddSpec)*
        </add>
        <update>
            (<a ... /> ## See /add/a [ ## WaitSetAddSpec])*
        </update>
        <remove>
            (<a [id="..."] /> ## Id)*
        </remove>
    </AdminWaitSetRequest>

The following table describes elements and attributes you can define within a <AdminWaitSetRequest> 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:
f folders
m messages
c contacts
a appointments
t tasks
d documents
all all types (equiv to "f,m,c,a,t,d")
@timeout Optional (0 or 1) Type:Long
Timeout length
/add Required (only 1)
/add/a Optional (0 or more)
/add/a@name Optional (0 or 1) Type:String
Name
/add/a@id Optional (0 or 1) Type:String
/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:
f folders
m messages
c contacts
a appointments
t tasks
d documents
all all types (equiv to "f,m,c,a,t,d")
/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

AdminWaitSetResponse

    <AdminWaitSetResponse waitSet="{waitset-id}" [canceled="(0|1)"] [seq="{sequence-num}"]> ## AdminWaitSetResponse
        (<a [id="..."] /> ## Id)*
        (<error id="..." type="..." /> ## IdAndType)*
    </AdminWaitSetResponse>

The following table describes elements and attributes you can define within a <AdminWaitSetResponse> 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) Signalled accounts
/a@id Optional (0 or 1) Type:String
ID
/error Optional (0 or more) Error information
/error@id Required (only 1) Type:String
ID
/error@type Required (only 1) Type:String
Type