IIterator Class Reference
[Data Model]

#include <support/IIterator.h>

Inheritance diagram for IIterator:

List of all members.

---

Detailed Description

Basic iteration iterface.

An IIterator allows you to step through some series of data. It is a stateful object (the iterator holds a position in the data), so you must be careful if you share iterators between threads. You usually retrieve an IIterator object from IIterable::NewIterator().

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

This is the minimal system data iteration interface. Note that there is no Reset() or Rewind() method on this interface; for non-streaming access, see IRandomIterator.

Public Types
enum	{ BINDER_IPC_LIMIT = 0x05 }
enum	{ REQUEST_DATA = 0x1000, COLLAPSE_NODE = 0x2000, COLLAPSE_CATALOG = 0x2000, IGNORE_PROJECTION = 0x4000 }
	Flags used in Next() and other iterator functions as well. More...
typedef SVector< SValue >	ValueList
Public Member Functions
status_t	LinkIterator (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual status_t	Next (ValueList *keys, ValueList *values, uint32_t flags, size_t count=0)=0
	Return a batch of keys and values from the iteration.
virtual SValue	Options () const =0
	The iterable options that are in force for this iterator.
status_t	UnlinkIterator (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
Protected Member Functions
	IIterator ()
virtual	~IIterator ()

---

Member Typedef Documentation

typedef SVector<SValue> ValueList

---

Member Enumeration Documentation

anonymous enum

Enumerator: BINDER_IPC_LIMIT  This is the limit of the number of binders that can be returned from Next().

anonymous enum

Flags used in Next() and other iterator functions as well. The implementation of all these flags is optional. However, if your iterator does implement projections, then it must also implement IGNORE_PROJECTION. Otherwise implementations of IIterator can completely ignore these flags. There is a copy of these flags in INode, if you change these don't forget to change those as well. Enumerator: REQUEST_DATA  Return the contents of an IDatum instead of the object itself? Can be supplied to IIterator::Next() and various INode functions. Implementations of IIterator are not required to respect this flag -- clients must deal with them ignoring it. COLLAPSE_NODE  Collapse catalog entries to SValue mappings? Can be supplied to IIterator::Next() and various INode functions. Implementations of IIterator are not required to respect this flag -- clients must deal with then ignoring it. Often used in conjunction with REQUEST_DATA so that you get back a collapsed node containing the data instead of IDatum objects. COLLAPSE_CATALOG  Deprecated: Synonyn for COLLAPSE_NODE IGNORE_PROJECTION  Deprecated: Ignore any projections when creating the output value/node? Deprecated: This flag will probably be removed. Can be supplied to IIterator::Next() and various INode functions. This is only useful when an iterator actually implements projections; if it does, it must also implement this flag (though implementing the flag may mean just returning the INode object and ignore the COLLAPSE_NODE flag).

---

Constructor & Destructor Documentation

IIterator (   )  [inline, protected]

virtual ~IIterator (   )  [protected, virtual]

---

Member Function Documentation

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

virtual status_t Next (  ValueList *  keys, ValueList *  values, uint32_t  flags, size_t  count = 0 )  [pure virtual]

Return a batch of keys and values from the iteration. Parameters: [out]  keys  The mapping keys. If your iterator is returning simple values (not mappings), the keys can be B_WILD_VALUE, or you can just make this sequence empty. [out]  values  The value of each item. Must be returned. [in]  flags  Any of REQUEST_DATA, COLLAPSE_NODE, IGNORE_PROJECTION. [in]  count  A "hint" about how many results you want. (You may get more, or fewer.) Use 0 for "don't care". Returns: B_OK if results were returned, B_END_OF_DATA if there is no more data in the iterator, or some other error code if an error occurred. This API is designed, for performance reasons, to return iteration results as batches. You will usually use SIterator::Next() to hide that batching mechanism and retrieve the entries one at a time. In either case, the function will return B_END_OF_DATA once you have reached the end of the iterator's data. The iterator may return key/value pairs, or single values. If returning single values, by the SValue mapping rules the key should always be B_WILD_VALUE. The Next() method can be given a flags parameter. Like INode::Walk(), you can supply REQUEST_DATA and COLLAPSE_NODE in the function's flags, with the corresponding semantics for the values the iterator returns. Also like INode::Walk(), the iterator is free to ignore these flags. Implemented in BCatalogDelegate::IteratorDelegate, BGenericIterable::GenericIterator, BValueIterator, and BRandomIterator.

virtual SValue Options (   )  const [pure virtual]

The iterable options that are in force for this iterator. You can use this determine which of the arguments given to IIterable::NewIterator() are in force for this iterator, and in what way. These are the same form as the arguments supplied to IIterable::NewIterator(). Implemented in BSchemaRowIDJoin::JoinIterator, BSchemaTableNode::QueryIterator, BCatalogDelegate::IteratorDelegate, BGenericIterable::GenericIterator, BIndexedIterable::IndexedIterator, BValueIterator, and BRandomIterator.

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

---

The documentation for this class was generated from the following file:

• IIterator.h

---

Generated on Wed Dec 28 22:33:31 2005 by Doxygen 1.4.4 for OpenBinder Documentation Version 1.0

PalmSource, Inc. © 2005