IIterable Class Reference
[Data Model]

#include <support/IIterable.h>

Inheritance diagram for IIterable:

IInterface SAtom BnIterable BCatalogMirror BGenericCatalog BGenericIterable BTokenSource BCatalogDelegate BIndexedIterable BSchemaRowIDJoin BSchemaTableNode BIndexedCatalog BIndexedDataNode BIndexedTableNode BSchemaRowIDJoin::RowNode BMetaDataCatalog BIndexedTableNode::RowNode BSchemaDatabaseNode BSchemaTableNode::RowNode BStructuredNode BCatalog BPackageManager List of all members.

Detailed Description

Interface implemented by objects that support iteration over their data.

The IIterable interface is a factory for generating iterators over a particular point in the Binder Data Model. This allows you to discover what data is available at that point in a namespace.

Clients will usually use the SIterator convenience class instead of making direct calls on an IIterable/IIterator. Implementations should never directly implement IIterable, instead deriving from BGenericIterable or one of its subclasses.

Note that iterators are not recursive. That is, they return to you all of the immediate children of the object you are iterating over. If you want to recursively iterate through the contents of those children, you will need to call Iterate() on each of the objects you retrieve from the original iterator.


Public Member Functions

status_t LinkIterable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual sptr< IIterator > NewIterator (const SValue &args=B_UNDEFINED_VALUE, status_t *error=NULL)=0
 Walk through the namespace based on the given path.
status_t UnlinkIterable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)

Protected Member Functions

 IIterable ()
virtual ~IIterable ()

Constructor & Destructor Documentation

IIterable (   )  [inline, protected]
 

virtual ~IIterable (   )  [protected, virtual]
 

Member Function Documentation

status_t LinkIterable (  const sptr< IBinder > &  to,
const SValue &  mappings,
uint32_t  flags = 0
)  [inline]
 

virtual sptr<IIterator> NewIterator (  const SValue &  args = B_UNDEFINED_VALUE,
status_t *  error = NULL
)  [pure virtual]
 

Walk through the namespace based on the given path.

Parameters:
[in] args Iterator options as described below.
[out] error Status code from the call, B_OK if all is well else an error code.
Returns:
The new IIterator object on success, else NULL.
The returned iterator has its own state, so you do not have to worry about other threads that may call Iterate() (they will get their own iterator). Most implementations will return a full IRandomIterator; use interface_cast<T> to retrieve that interface.

Clients should usually use SIterator instead of calling NewIterator() directly.

The options parameter is used to control what data is returned by the iterator. The available options are fairly implementation-dependent, but some common ones are described here. Because you can not know what any given IIterable object will be able to do, the IIterator interface you get back has a read-only options property with which you can find out how it is configured. Any of the options supplied to IIterate() that it understands will be propagated to the options property in the form it understood them.

  • "select" (a.k.a. BV_ITERABLE_SELECT) specifies a SQL projection, describing the columns to be included in the iterator results. It is a set of column names to include.
  • "filter" (a.k.a. BV_ITERABLE_FILTER) specifies an abstract filter (as a string) to be applied to the results, interpret in whatever way the IIterable thinks makes the most sense.
  • "where" (a.k.a. BV_ITERABLE_WHERE) specifies a direct SQL WHERE clause, allowing you to filter the results contained in the iterator. This can be used with "filter" at the same time, in which case the result set will be the rows matching both of them.
  • "order_by" (a.k.a. BV_ITERABLE_ORDER_BY) specifies how to order entries returned by the iterator.

See Binder Data Model for more detail on these options.

Implementation Details
Note that semantically each iterator you generate is passive for the set of entries, but the data inside each of those entries may change. That is, if the contents of the container changes, this will not impact the number of entries in any current active iterators. However, if the data inside one of those entries changes, then the next time any iterator requests the data for that entry it will get back the new data. If an entry is removed from the iterable, again the number of items in currently active iterators does not change; however, if that item is requested, both the key and value are returned with B_NULL_VALUE.
This requirement in place so that an iterator's results can be reasonably thread-safe. For example, if a list view gets an IRandomIterator to display an IIterable's contents, it can rely on the indices of that iterator being consistently mapped to the same entry in the iterable.

Implemented in BGenericIterable, BCatalogMirror, and BTokenSource.

status_t UnlinkIterable (  const sptr< IBinder > &  to,
const SValue &  mappings,
uint32_t  flags = 0
)  [inline]
 

The documentation for this class was generated from the following file:
Generated on Wed Dec 28 22:33:31 2005 by Doxygen 1.4.4 for OpenBinder Documentation Version 1.0

PalmSource, Inc. © 2005