1.3 Overview

The Table Object Protocol is used to read tabular data from a server. It specifies a set of operations that a client can use to request tabular data from a server based on a handle to the table as described in section 4.4. The client can specify the columns, the restriction, and the sort order for the table, and can request that the rows of the table be categorized according to specific properties as described in section 4.5. The client can then request one or more rows of data. Additionally, the client can find rows, navigate through the rows, and create bookmarks for easier navigation. The protocol can provide a way to free server resources associated with bookmarks.

When the client requests that the rows of the table be categorized, the server will include header rows in the table that don't have the same properties as normal rows. The client can request that the server hide or show all of the normal rows for which the header row represents their category. A category can be nested inside another category. The client can retrieve a binary large object (BLOB) that specifies which categories are collapsed and which are expanded in the current table. This BLOB can then be given to the table at a future time to restore the collapsed state of the table as well as the cursor location.

Multivalue instances can be retrieved from the table when a multivalue property is specified in the column set. When multivalue instances are requested, for each value in a multivalue property there will be an instance of the row that has that single value for the property. All other properties are repeated in each multivalue instance.

Categories that are based on multivalue properties will display the multivalue instances under each header row representing a value that is set on that row. The row that is displayed under a given header row will include the single property value specified by the header row, not all values for the property.

Some tables might not support certain table operations. For example, rules tables do not support sorting and return an error if sorting is attempted. Tables that do not support asynchronous operations can perform them synchronously or return an error.