Cisco Cisco Meeting Server 2000 开发者指南

4.1.1 Collections level

If the GET method is performed at the Collections level (the pluralized noun: “calls”, “coSpaces”
etc.) then some number of matching child nodes will be retrieved. By design this is not
guaranteed to be the entire list, but the total number of objects of that type present in the
Meeting Server can be learnt via this mechanism.

In order to retrieve just specific items, most GET methods at the Collections level allow the use
of a filter expression. The idea here is that the interface of a management tool would initially
present the API user with the summed count of coSpaces (for example), basic details on the
first “N” coSpaces (e.g. their names) and a filter box which the human user can use to search for
the specific coSpace(s) of interest.

With no other additional parameters, a GET method at the Collections level will return items
from the start of the Meeting Server's notional complete list. By comparing the number of items
returned with the "total" value, it is straightforward to determine whether all elements have
been returned (if the number of elements returned is equal to the "total" value).

4.1.2 Using limit and offset at the Collections level

It is possible to restrict the number of elements returned to a limit chosen by the requestor, by
including a "limit=<limitValue>" in the API request. This guarantees that no more than the
specified "limitValue" number of elements will be returned - the Meeting Server will have its
own limit in these cases too, and therefore the number of elements returned will be the lower of
any supplied "limitValue" and the Meeting Server's own limit.

In order to retrieve elements other than the first "n" on the Meeting Server's notional list, it is
also possible to supply an "offset=<offsetValue>" in the API request. This causes the Meeting
Server to return elements which start at the specified position in its list, skipping the first
"offsetValue" number of elements. If "offsetValue" is greater than the number of objects of
that type, then no elements will be returned.

Note: The offset value should not be viewed as a general mechanism for retrieving a large
complete list - sequential retrievals of one "page" of data followed by a second "page" will not
necessarily be operating on the same complete list if any objects have been deleted or added in
the interval between these methods.

The expectation is that, for each request and response, the requestor will keep track of the
offset and limit values used, and combine this knowledge with the number of elements returned
in the response and the "total" indicated by the Meeting Server. If the "offsetValue" supplied
by the requestor plus the number of elements returned is less than the "total" value indicated in
the response, the requestor then knows that there are more values present. The following table
shows some examples: