1 /* 2 * Copyright (c) 2019 Apple 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 /* 29 * Copyright (c) 1998-1999 Apple Computer, Inc. All rights reserved. 30 * 31 * HISTORY 32 * 33 */ 34 35 #ifndef _OS_OSITERATOR_H 36 #define _OS_OSITERATOR_H 37 38 #include <libkern/c++/OSObject.h> 39 40 /*! 41 * @header 42 * 43 * @abstract 44 * This header declares the OSIterator collection class. 45 */ 46 47 48 /*! 49 * @class OSIterator 50 * @abstract 51 * The abstract superclass for Libkern iterators. 52 * 53 * @discussion 54 * OSIterator is the abstract superclass for all Libkern C++ object iterators. 55 * It defines the basic interface for iterating and resetting. 56 * See @link //apple_ref/cpp/macro/OSCollection OSCollection@/link and 57 * @link //apple_ref/cpp/macro/OSCollectionIterator OSCollectionIterator@/link 58 * for more information. 59 * 60 * With very few exceptions in the I/O Kit, all Libkern-based C++ 61 * classes, functions, and macros are <b>unsafe</b> 62 * to use in a primary interrupt context. 63 * Consult the I/O Kit documentation related to primary interrupts 64 * for more information. 65 * 66 * OSIterator provides no concurrency protection. 67 */ 68 class OSIterator : public OSObject 69 { 70 OSDeclareAbstractStructors(OSIterator); 71 72 public: 73 /*! 74 * @function reset 75 * 76 * @abstract 77 * Resets the iterator to the beginning of the collection, 78 * as if it had just been created. 79 * 80 * @discussion 81 * Subclasses must implement this pure virtual member function. 82 */ 83 virtual void reset() = 0; 84 85 86 /*! 87 * @function isValid 88 * 89 * @abstract 90 * Check that the collection hasn't been modified during iteration. 91 * 92 * @result 93 * <code>true</code> if the iterator is valid for continued use, 94 * <code>false</code> otherwise 95 * (typically because the collection being iterated has been modified). 96 * 97 * @discussion 98 * Subclasses must implement this pure virtual member function. 99 */ 100 virtual bool isValid() = 0; 101 102 103 /*! 104 * @function getNextObject 105 * 106 * @abstract 107 * Advances to and returns the next object in the iteration. 108 * 109 * @return 110 * The next object in the iteration context, 111 * <code>NULL</code> if there is no next object 112 * or if the iterator is no longer valid. 113 * 114 * @discussion 115 * The returned object will be released if removed from the collection; 116 * if you plan to store the reference, you should call 117 * <code>@link 118 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() 119 * retain@/link</code> 120 * on that object. 121 * 122 * Subclasses must implement this pure virtual function 123 * to check for validity with 124 * <code>@link isValid isValid@/link</code>, 125 * and then to advance the iteration context to the next object (if any) 126 * and return that next object, or <code>NULL</code> if there is none. 127 */ 128 virtual OSObject *getNextObject() = 0; 129 130 OSMetaClassDeclareReservedUnused(OSIterator, 0); 131 OSMetaClassDeclareReservedUnused(OSIterator, 1); 132 OSMetaClassDeclareReservedUnused(OSIterator, 2); 133 OSMetaClassDeclareReservedUnused(OSIterator, 3); 134 }; 135 136 #endif /* ! _OS_OSITERATOR_H */ 137