#include <libkern/c++/OSCollectionIterator.h>
libkern/c++/OSCollectionIterator.h
IOCollectionIterator.h created by gvdl on Fri 1998-10-30
typedefOSCollectionIteratorPtr
typedef OSCollectionIterator* OSCollectionIteratorPtr
classOSCollectionIterator
@class OSCollectionIterator
@discussion OSCollectionIterator defines a consistent mechanism to iterate
through the objects of an OSCollection.
It expands on the basic interface of
@link //apple_ref/cpp/class/OSIterator OSIterator@/link
to allow association of an iterator with a specific collection.
To use an OSCollectionIterator, you create it with the collection
to be iterated, then call
@link //apple_ref/cpp/class/OSIterator OSIterator@/link
as long as it returns an object:
@textblock
<pre>
OSPtr <OSCollectionIterator> iterator =
OSCollectionIterator::withCollection(myCollection);
OSObject * object;
while (object = iterator->getNextObject()) {
// do something with object
}
// optional
if (!iterator->isValid()) {
// report that collection changed during iteration
}
iterator = nullptr;
</pre>
@/textblock
Note that when iterating associative collections,
the objects returned by <code>getNextObject</code> are keys;
if you want to work with the associated values,
simply look them up in the collection with the keys.
<b>Use Restrictions</b>
With very few exceptions in the I/O Kit, all Libkern-based C++
classes, functions, and macros are <b>unsafe</b>
to use in a primary interrupt context.
Consult the I/O Kit documentation related to primary interrupts
for more information.
OSCollectionIterator provides no concurrency protection.
: public OSIterator
| OSPtr<const OSCollection> | collection | |
| void * | collIterator | |
| unsigned int | initialUpdateStamp | |
| bool | valid |
static OSPtr<OSCollectionIterator> withCollection(const OSCollection * inColl)static
@function withCollection
@abstract Creates and initializes an OSCollectionIterator
for the provided collection object.
@param inColl The OSCollection-derived collection object to be iteratated.
@result A new instance of OSCollectionIterator, or <code>NULL</code> on failure.
virtual bool initWithCollection(const OSCollection * inColl)virtual
@function initWithCollection
@abstract Initializes an OSCollectionIterator
for the provided collection object.
@param inColl The OSCollection-derived collection object to be iteratated.
@result <code>true</code> if the initialization was successful,
or <code>false</code> on failure.
@discussion Not for general use. Use the static instance creation method
<code>@link withCollection withCollection@/link</code> instead.
APPLE_KEXT_OVERRIDE
virtual void free()virtual@function free
@abstract Releases or deallocates any resources used
by the OSCollectionIterator object.
@discussion This function should not be called directly;
use
<code>@link
//apple_ref/cpp/instm/OSObject/release/virtualvoid/()
release@/link</code>
instead.
APPLE_KEXT_OVERRIDE
virtual void reset()virtual@function reset
@abstract Resets the iterator to the beginning of the collection,
as if it had just been created.
APPLE_KEXT_OVERRIDE
virtual bool isValid()virtual@function isValid
@abstract Checks that the collection hasn't been modified during iteration.
@return <code>true</code> if the iterator is valid for continued use,
<code>false</code> otherwise
(typically because the iteration context has been modified).
APPLE_KEXT_OVERRIDE virtual OSObject * getNextObject()virtual
@function getNextObject
@abstract Advances to and returns the next object in the iteration.
@return The next object in the iteration context,
<code>NULL</code> if there is no next object
or if the iterator is no longer valid.
@discussion This function first calls
<code>@link //apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/()
isValid@/link</code>
and returns <code>NULL</code> if that function
returns <code>false</code>.
Subclasses must implement this pure virtual function
to check for validity with
<code>@link
//apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/()
isValid@/link</code>,
and then to advance the iteration context to the next object (if any)
and return that next object, or <code>NULL</code> if there is none.