1/* 2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28/* IOCollectionIterator.h created by gvdl on Fri 1998-10-30 */ 29 30#ifndef _OS_OSCOLLECTIONITERATOR_H 31#define _OS_OSCOLLECTIONITERATOR_H 32 33#include <libkern/c++/OSIterator.h> 34 35class OSCollection; 36 37/*! 38 * @header 39 * 40 * @abstract 41 * This header declares the OSCollectionIterator collection class. 42 */ 43 44 45/*! 46 * @class OSCollectionIterator 47 * 48 * @discussion 49 * OSCollectionIterator defines a consistent mechanism to iterate 50 * through the objects of an OSCollection. 51 * It expands on the basic interface of 52 * @link //apple_ref/cpp/class/OSIterator OSIterator@/link 53 * to allow association of an iterator with a specific collection. 54 * 55 * To use an OSCollectionIterator, you create it with the collection 56 * to be iterated, then call 57 * @link //apple_ref/cpp/class/OSIterator OSIterator@/link 58 * as long as it returns an object: 59 * 60 * @textblock 61 * <pre> 62 * OSCollectionIterator * iterator = 63 * OSCollectionIterator::withCollection(myCollection); 64 * OSObject * object; 65 * while (object = iterator->getNextObject()) { 66 * // do something with object 67 * } 68 * // optional 69 * if (!iterator->isValid()) { 70 * // report that collection changed during iteration 71 * } 72 * iterator->release(); 73 * </pre> 74 * @/textblock 75 * 76 * Note that when iterating associative collections, 77 * the objects returned by <code>getNextObject</code> are keys; 78 * if you want to work with the associated values, 79 * simply look them up in the collection with the keys. 80 * 81 * <b>Use Restrictions</b> 82 * 83 * With very few exceptions in the I/O Kit, all Libkern-based C++ 84 * classes, functions, and macros are <b>unsafe</b> 85 * to use in a primary interrupt context. 86 * Consult the I/O Kit documentation related to primary interrupts 87 * for more information. 88 * 89 * OSCollectionIterator provides no concurrency protection. 90 */ 91class OSCollectionIterator : public OSIterator 92{ 93 OSDeclareDefaultStructors(OSCollectionIterator) 94 95protected: 96// xx-review: Do we want to document these? 97 const OSCollection * collection; 98 void * collIterator; 99 unsigned int initialUpdateStamp; 100 bool valid; 101 102public: 103 /*! 104 * @function withCollection 105 * 106 * @abstract 107 * Creates and initializes an OSCollectionIterator 108 * for the provided collection object. 109 * 110 * @param inColl The OSCollection-derived collection object to be iteratated. 111 * 112 * @result 113 * A new instance of OSCollectionIterator, or <code>NULL</code> on failure. 114 */ 115 static OSCollectionIterator * withCollection(const OSCollection * inColl); 116 117 118 /*! 119 * @function initWithCollection 120 * 121 * @abstract 122 * Initializes an OSCollectionIterator 123 * for the provided collection object. 124 * 125 * @param inColl The OSCollection-derived collection object to be iteratated. 126 * @result 127 * <code>true</code> if the initialization was successful, 128 * or <code>false</code> on failure. 129 * 130 * @discussion 131 * Not for general use. Use the static instance creation method 132 * <code>@link withCollection withCollection@/link</code> instead. 133 */ 134 virtual bool initWithCollection(const OSCollection * inColl); 135 136 137 /*! 138 * @function free 139 * 140 * @abstract 141 * Releases or deallocates any resources used 142 * by the OSCollectionIterator object. 143 * 144 * @discussion 145 * This function should not be called directly; 146 * use 147 * <code>@link 148 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() 149 * release@/link</code> 150 * instead. 151 */ 152 virtual void free(); 153 154 155 /*! 156 * @function reset 157 * 158 * @abstract 159 * Resets the iterator to the beginning of the collection, 160 * as if it had just been created. 161 */ 162 virtual void reset(); 163 164 165 /*! 166 * @function isValid 167 * 168 * @abstract 169 * Checks that the collection hasn't been modified during iteration. 170 * 171 * @return 172 * <code>true</code> if the iterator is valid for continued use, 173 * <code>false</code> otherwise 174 * (typically because the iteration context has been modified). 175 */ 176 virtual bool isValid(); 177 178 179 /*! 180 * @function getNextObject 181 * 182 * @abstract 183 * Advances to and returns the next object in the iteration. 184 * 185 * @return 186 * The next object in the iteration context, 187 * <code>NULL</code> if there is no next object 188 * or if the iterator is no longer valid. 189 * 190 * @discussion 191 * This function first calls 192 * <code>@link //apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/() 193 * isValid@/link</code> 194 * and returns <code>NULL</code> if that function 195 * returns <code>false</code>. 196 * 197 * Subclasses must implement this pure virtual function 198 * to check for validity with 199 * <code>@link 200 * //apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/() 201 * isValid@/link</code>, 202 * and then to advance the iteration context to the next object (if any) 203 * and return that next object, or <code>NULL</code> if there is none. 204 */ 205 virtual OSObject * getNextObject(); 206}; 207 208#endif /* !_OS_OSCOLLECTIONITERATOR_H */ 209