1 /* 2 * Copyright (c) 1998-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 Apple Computer, Inc. All rights reserved. 30 * 31 * HISTORY 32 * 33 */ 34 35 36 #ifndef _IOKIT_IOREGISTRYENTRY_H 37 #define _IOKIT_IOREGISTRYENTRY_H 38 39 #include <IOKit/IOTypes.h> 40 #include <libkern/c++/OSContainers.h> 41 #include <libkern/c++/OSPtr.h> 42 43 #if defined(IOKIT_ENABLE_SHARED_PTR) 44 /*! @parseOnly */ 45 #define APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR __attribute__((deprecated)) 46 #else 47 /*! @parseOnly */ 48 #define APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR 49 #endif /* IOKIT_ENABLE_SHARED_PTR */ 50 51 52 extern const OSSymbol * gIONameKey; 53 extern const OSSymbol * gIOLocationKey; 54 extern const OSSymbol * gIORegistryEntryIDKey; 55 extern const OSSymbol * gIORegistryEntryPropertyKeysKey; 56 57 class IORegistryEntry; 58 class IORegistryPlane; 59 class IORegistryIterator; 60 61 typedef void (*IORegistryEntryApplierFunction)(IORegistryEntry * entry, 62 void * context); 63 64 enum { 65 kIORegistryIterateRecursively = 0x00000001, 66 kIORegistryIterateParents = 0x00000002, 67 }; 68 69 #ifdef KERNEL_PRIVATE 70 enum{ 71 kIORegistryEntryIndexedPropertyCLPC = 0, 72 kIORegistryEntryIndexedPropertyCount, 73 }; 74 #endif /* KERNEL_PRIVATE */ 75 76 /*! @class IORegistryEntry : public OSObject 77 * @abstract The base class for all objects in the registry. 78 * @discussion The IORegistryEntry base class provides functions for describing graphs of connected registry entries, each with a dictionary-based property table. Entries may be connected in different planes, with differing topologies. Access to the registry is protected against multiple threads. Inside the kernel planes are specified with plane objects and are published by the creator - IOService exports the gIOServicePlane plane object for example. Non kernel clients specify planes by their name. 79 */ 80 81 class IORegistryEntry : public OSObject 82 { 83 friend class IORegistryIterator; 84 85 OSDeclareDefaultStructors(IORegistryEntry); 86 87 protected: 88 /*! @struct ExpansionData 89 * @discussion This structure will be used to expand the capablilties of this class in the future. 90 */ 91 struct ExpansionData; 92 93 /*! @var reserved 94 * Reserved for future use. (Internal use only) */ 95 ExpansionData * reserved; 96 97 private: 98 99 OSDictionary * fRegistryTable; 100 OSDictionary * fPropertyTable; 101 102 public: 103 /* methods available in Mac OS X 10.1 or later */ 104 105 /*! @function copyProperty 106 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later. 107 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 108 * @param aKey The property's name as a C-string. 109 * @param plane The plane to iterate over, eg. gIOServicePlane. 110 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 111 * @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */ 112 113 virtual OSPtr<OSObject> copyProperty( const char * aKey, 114 const IORegistryPlane * plane, 115 IOOptionBits options = 116 kIORegistryIterateRecursively | 117 kIORegistryIterateParents) const; 118 119 /*! @function copyProperty 120 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later. 121 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 122 * @param aKey The property's name as an OSString. 123 * @param plane The plane to iterate over, eg. gIOServicePlane. 124 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 125 * @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */ 126 127 virtual OSPtr<OSObject> copyProperty( const OSString * aKey, 128 const IORegistryPlane * plane, 129 IOOptionBits options = 130 kIORegistryIterateRecursively | 131 kIORegistryIterateParents) const; 132 133 /*! @function copyProperty 134 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later. 135 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 136 * @param aKey The property's name as an OSSymbol. 137 * @param plane The plane to iterate over, eg. gIOServicePlane. 138 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 139 * @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */ 140 141 virtual OSPtr<OSObject> copyProperty( const OSSymbol * aKey, 142 const IORegistryPlane * plane, 143 IOOptionBits options = 144 kIORegistryIterateRecursively | 145 kIORegistryIterateParents) const; 146 147 /*! @function copyParentEntry 148 * @abstract Returns an registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later. 149 * @discussion This function will return the parent to which a registry entry was first attached. Since the majority of registry entrys have only one provider, this is a useful simplification. 150 * @param plane The plane object. 151 * @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */ 152 153 virtual OSPtr<IORegistryEntry> copyParentEntry( const IORegistryPlane * plane ) const; 154 155 /*! @function copyChildEntry 156 * @abstract Returns an registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later. 157 * @discussion This function will return the child which first attached to a registry entry. 158 * @param plane The plane object. 159 * @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */ 160 161 virtual OSPtr<IORegistryEntry> copyChildEntry( const IORegistryPlane * plane ) const; 162 163 /* method available in Mac OS X 10.4 or later */ 164 /*! 165 * @typedef Action 166 * @discussion Type and arguments of callout C function that is used when 167 * a runCommand is executed by a client. Cast to this type when you want a C++ 168 * member function to be used. Note the arg1 - arg3 parameters are passed straight pass through to the action callout. 169 * @param target 170 * Target of the function, can be used as a refcon. Note if a C++ function 171 * was specified, this parameter is implicitly the first parameter in the target 172 * member function's parameter list. 173 * @param arg0 Argument to action from run operation. 174 * @param arg1 Argument to action from run operation. 175 * @param arg2 Argument to action from run operation. 176 * @param arg3 Argument to action from run operation. 177 */ 178 typedef IOReturn (*Action)(OSObject *target, 179 void *arg0, void *arg1, 180 void *arg2, void *arg3); 181 182 /*! @function runPropertyAction 183 * @abstract Single thread a call to an action w.r.t. the property lock 184 * @discussion Client function that causes the given action to be called in a manner that syncrhonises with the registry iterators and serialisers. This functin can be used to synchronously manipulate the property table of this nub 185 * @param action Pointer to function to be executed in work-loop context. 186 * @param arg0 Parameter for action parameter, defaults to 0. 187 * @param arg1 Parameter for action parameter, defaults to 0. 188 * @param arg2 Parameter for action parameter, defaults to 0. 189 * @param arg3 Parameter for action parameter, defaults to 0. 190 * @result Returns the value of the Action callout. 191 */ 192 virtual IOReturn runPropertyAction(Action action, OSObject *target, 193 void *arg0 = NULL, void *arg1 = NULL, 194 void *arg2 = NULL, void *arg3 = NULL); 195 196 #ifdef __BLOCKS__ 197 typedef IOReturn (^ActionBlock)(void); 198 IOReturn runPropertyActionBlock(ActionBlock block); 199 #endif /* __BLOCKS__ */ 200 201 private: 202 #if __LP64__ 203 OSMetaClassDeclareReservedUnused(IORegistryEntry, 0); 204 OSMetaClassDeclareReservedUnused(IORegistryEntry, 1); 205 OSMetaClassDeclareReservedUnused(IORegistryEntry, 2); 206 OSMetaClassDeclareReservedUnused(IORegistryEntry, 3); 207 OSMetaClassDeclareReservedUnused(IORegistryEntry, 4); 208 OSMetaClassDeclareReservedUnused(IORegistryEntry, 5); 209 #else 210 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 0); 211 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 1); 212 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 2); 213 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 3); 214 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 4); 215 OSMetaClassDeclareReservedUsedX86(IORegistryEntry, 5); 216 #endif 217 OSMetaClassDeclareReservedUnused(IORegistryEntry, 6); 218 OSMetaClassDeclareReservedUnused(IORegistryEntry, 7); 219 OSMetaClassDeclareReservedUnused(IORegistryEntry, 8); 220 OSMetaClassDeclareReservedUnused(IORegistryEntry, 9); 221 OSMetaClassDeclareReservedUnused(IORegistryEntry, 10); 222 OSMetaClassDeclareReservedUnused(IORegistryEntry, 11); 223 OSMetaClassDeclareReservedUnused(IORegistryEntry, 12); 224 OSMetaClassDeclareReservedUnused(IORegistryEntry, 13); 225 OSMetaClassDeclareReservedUnused(IORegistryEntry, 14); 226 OSMetaClassDeclareReservedUnused(IORegistryEntry, 15); 227 OSMetaClassDeclareReservedUnused(IORegistryEntry, 16); 228 OSMetaClassDeclareReservedUnused(IORegistryEntry, 17); 229 OSMetaClassDeclareReservedUnused(IORegistryEntry, 18); 230 OSMetaClassDeclareReservedUnused(IORegistryEntry, 19); 231 OSMetaClassDeclareReservedUnused(IORegistryEntry, 20); 232 OSMetaClassDeclareReservedUnused(IORegistryEntry, 21); 233 OSMetaClassDeclareReservedUnused(IORegistryEntry, 22); 234 OSMetaClassDeclareReservedUnused(IORegistryEntry, 23); 235 OSMetaClassDeclareReservedUnused(IORegistryEntry, 24); 236 OSMetaClassDeclareReservedUnused(IORegistryEntry, 25); 237 OSMetaClassDeclareReservedUnused(IORegistryEntry, 26); 238 OSMetaClassDeclareReservedUnused(IORegistryEntry, 27); 239 OSMetaClassDeclareReservedUnused(IORegistryEntry, 28); 240 OSMetaClassDeclareReservedUnused(IORegistryEntry, 29); 241 OSMetaClassDeclareReservedUnused(IORegistryEntry, 30); 242 OSMetaClassDeclareReservedUnused(IORegistryEntry, 31); 243 244 public: 245 246 /* Registry accessors */ 247 248 /*! @function getRegistryRoot 249 * @abstract Returns a pointer to the root instance of the registry. 250 * @discussion This method provides an accessor to the root of the registry for the machine. The root may be passed to a registry iterator when iterating a plane, and contains properties that describe the available planes, and diagnostic information for IOKit. Keys for these properties are in IOKitKeys.h. 251 * @result A pointer to the IORegistryEntry root instance. It should not be released by the caller. */ 252 253 static IORegistryEntry * getRegistryRoot( void ); 254 255 /*! @function getGenerationCount 256 * @abstract Returns an generation count for all registry changing operations. 257 * @discussion This method provides an accessor to the current generation count (or seed) of the registry which changes when any topology change occurs in the registry - this does not include property table changes. It may be used to invalidate any caching of the results from IORegistryEntry methods. 258 * @result An integer generation count. */ 259 260 static SInt32 getGenerationCount( void ); 261 262 /*! @function getPlane 263 * @abstract Looks up the plane object by a C-string name. 264 * @discussion Planes are usually provided as globals by the creator, eg. gIOServicePlane, gIODeviceTreePlane, or gIOAudioPlane, however they may also be looked up by name with this method. 265 * @result A pointer to the plane object, or zero if no such plane exists. The returned plane should not be released. */ 266 267 static const IORegistryPlane * getPlane( const char * name ); 268 269 /* Registry Entry allocation & init */ 270 271 /*! @function init 272 * @abstract Standard init method for all IORegistryEntry subclasses. 273 * @discussion A registry entry must be initialized with this method before it can be used. A property dictionary may passed and will be retained by this method for use as the registry entry's property table, or an empty one will be created. 274 * @param dictionary A dictionary that will become the registry entry's property table (retaining it), or zero which will cause an empty property table to be created. 275 * @result true on success, or false on a resource failure. */ 276 277 virtual bool init( OSDictionary * dictionary = NULL ); 278 279 /*! @function free 280 * @abstract Standard free method for all IORegistryEntry subclasses. 281 * @discussion This method will release any resources of the entry, in particular its property table. Note that the registry entry must always be detached from the registry before free may be called, and subclasses (namely IOService) will have additional protocols for removing registry entries. free should never need be called directly. */ 282 283 virtual void free( void ) APPLE_KEXT_OVERRIDE; 284 285 /*! @function setPropertyTable 286 * @abstract Replace a registry entry's property table. 287 * @discussion This method will release the current property table of a the entry and replace it with another, retaining the new property table. 288 * @param dict The new dictionary to be used as the entry's property table. */ 289 290 virtual void setPropertyTable( OSDictionary * dict ); 291 292 /* Synchronized property accessors; wrappers to OSDictionary 293 * plus property creation helpers */ 294 295 /*! @function setProperty 296 * @abstract Synchronized method to add a property to a registry entry's property table. 297 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 298 * @param aKey The properties name as an OSSymbol. 299 * @param anObject The property value. 300 * @result true on success or false on a resource failure. */ 301 302 virtual bool setProperty(const OSSymbol * aKey, 303 OSObject * anObject); 304 305 #ifdef KERNEL_PRIVATE 306 OSObject * setIndexedProperty(uint32_t index, OSObject * anObject); 307 OSObject * getIndexedProperty(uint32_t index) const; 308 #endif /* KERNEL_PRIVATE */ 309 310 /*! @function setProperty 311 * @abstract Synchronized method to add a property to a registry entry's property table. 312 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 313 * @param aKey The property's name as an OSString. 314 * @param anObject The property value. 315 * @result true on success or false on a resource failure. */ 316 317 virtual bool setProperty(const OSString * aKey, OSObject * anObject); 318 319 /*! @function setProperty 320 * @abstract Synchronized method to add a property to a registry entry's property table. 321 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 322 * @param aKey The property's name as a C-string. 323 * @param anObject The property value. 324 * @result true on success or false on a resource failure. */ 325 326 virtual bool setProperty(const char * aKey, OSObject * anObject); 327 328 /*! @function setProperty 329 * @abstract Synchronized method to construct and add a OSString property to a registry entry's property table. 330 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSString from the supplied C-string, set in the property table with the given name, and released. 331 * @param aKey The property's name as a C-string. 332 * @param aString The property value as a C-string. 333 * @result true on success or false on a resource failure. */ 334 335 virtual bool setProperty(const char * aKey, const char * aString); 336 337 /*! @function setProperty 338 * @abstract Synchronized method to construct and add an OSBoolean property to a registry entry's property table. 339 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSBoolean from the supplied value, set in the property table with the given name, and released. 340 * @param aKey The property's name as a C-string. 341 * @param aBoolean The property's boolean value. 342 * @result true on success or false on a resource failure. */ 343 344 virtual bool setProperty(const char * aKey, bool aBoolean); 345 346 /*! @function setProperty 347 * @abstract Synchronized method to construct and add an OSNumber property to a registry entry's property table. 348 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSNumber from the supplied value and size, set in the property table with the given name, and released. 349 * @param aKey The property's name as a C-string. 350 * @param aValue The property's numeric value. 351 * @param aNumberOfBits The property's size in bits, for OSNumber. 352 * @result true on success or false on a resource failure. */ 353 354 virtual bool setProperty( const char * aKey, 355 unsigned long long aValue, 356 unsigned int aNumberOfBits); 357 358 /*! @function setProperty 359 * @abstract Synchronized method to construct and add an OSData property to a registry entry's property table. 360 * @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSData copied from the supplied data and length, set in the property table with the given name, and released. 361 * @param aKey The property's name as a C-string. 362 * @param bytes The property's value as a pointer. OSData will copy this data. 363 * @param length The property's size in bytes, for OSData. 364 * @result true on success or false on a resource failure. */ 365 366 virtual bool setProperty( const char * aKey, 367 void * bytes, 368 unsigned int length); 369 370 /*! @function removeProperty 371 * @abstract Synchronized method to remove a property from a registry entry's property table. 372 * @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 373 * @param aKey The property's name as an OSSymbol. */ 374 375 virtual void removeProperty( const OSSymbol * aKey); 376 377 /*! @function removeProperty 378 * @abstract Synchronized method to remove a property from a registry entry's property table. 379 * @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 380 * @param aKey The property's name as an OSString. */ 381 382 virtual void removeProperty( const OSString * aKey); 383 384 /*! @function removeProperty 385 * @abstract Synchronized method to remove a property from a registry entry's property table. 386 * @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 387 * @param aKey The property's name as a C-string. */ 388 389 virtual void removeProperty( const char * aKey); 390 391 /*! @function getProperty 392 * @abstract Synchronized method to obtain a property from a registry entry's property table. 393 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 394 * @param aKey The property's name as an OSSymbol. 395 * @result The property value found, or zero. */ 396 397 virtual OSObject * getProperty( const OSSymbol * aKey) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 398 399 /*! @function getProperty 400 * @abstract Synchronized method to obtain a property from a registry entry's property table. 401 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 402 * @param aKey The property's name as an OSString. 403 * @result The property value found, or zero. */ 404 405 virtual OSObject * getProperty( const OSString * aKey) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 406 407 /*! @function getProperty 408 * @abstract Synchronized method to obtain a property from a registry entry's property table. 409 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. 410 * @param aKey The property's name as a C-string. 411 * @result The property value found, or zero. */ 412 413 virtual OSObject * getProperty( const char * aKey) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 414 415 /*! @function propertyExists 416 * @abstract Synchronized method to check if a property exists in a registry entry's property table. 417 * @discussion This method will check if a property exists in a registry entry's property table. This method is synchronized with other IORegistryEntry accesses to the property table. 418 * @param aKey The property's name as an OSSymbol. 419 * @result True if the property value found. */ 420 421 bool propertyExists(const OSSymbol * aKey); 422 423 /*! @function propertyExists 424 * @abstract Synchronized method to check if a property exists in a registry entry's property table. 425 * @discussion This method will check if a property exists in a registry entry's property table. This method is synchronized with other IORegistryEntry accesses to the property table. 426 * @param aKey The property's name as an OSString. 427 * @result True if the property value found. */ 428 429 bool propertyExists(const OSString * aKey); 430 431 /*! @function propertyExists 432 * @abstract Synchronized method to check if a property exists in a registry entry's property table. 433 * @discussion This method will check if a property exists in a registry entry's property table. This method is synchronized with other IORegistryEntry accesses to the property table. 434 * @param aKey The property's name as a C-string. 435 * @result True if the property value found. */ 436 437 bool propertyExists(const char * aKey); 438 439 /*! @function propertyHasValue 440 * @abstract Synchronized method to check if a property in a registry entry's property table has a given value. 441 * @discussion This method will check if a property exists in a registry entry's property table and compares with isEqualTo() the supplied value. This method is synchronized with other IORegistryEntry accesses to the property table. 442 * @param aKey The property's name as an OSSymbol. 443 * @param value The property's value to be compared. 444 * @result True if the property value was found and isEqualTo() the supplied value. */ 445 446 bool propertyHasValue(const OSSymbol * aKey, 447 const OSObject * value); 448 449 /*! @function propertyHasValue 450 * @abstract Synchronized method to check if a property in a registry entry's property table has a given value. 451 * @discussion This method will check if a property exists in a registry entry's property table and compares with isEqualTo() the supplied value. This method is synchronized with other IORegistryEntry accesses to the property table. 452 * @param aKey The property's name as an OSString. 453 * @param value The property's value to be compared. 454 * @result True if the property value was found and isEqualTo() the supplied value. */ 455 456 bool propertyHasValue(const OSString * aKey, 457 const OSObject * value); 458 459 /*! @function propertyHasValue 460 * @abstract Synchronized method to check if a property in a registry entry's property table has a given value. 461 * @discussion This method will check if a property exists in a registry entry's property table and compares with isEqualTo() the supplied value. This method is synchronized with other IORegistryEntry accesses to the property table. 462 * @param aKey The property's name as a C-string. 463 * @param value The property's value to be compared. 464 * @result True if the property value was found and isEqualTo() the supplied value. */ 465 466 bool propertyHasValue(const char * aKey, 467 const OSObject * value); 468 469 /*! @function getProperty 470 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. 471 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 472 * @param aKey The property's name as an OSSymbol. 473 * @param plane The plane to iterate over, eg. gIOServicePlane. 474 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 475 * @result The property value found, or zero. */ 476 477 virtual OSObject * getProperty( const OSSymbol * aKey, 478 const IORegistryPlane * plane, 479 IOOptionBits options = 480 kIORegistryIterateRecursively | 481 kIORegistryIterateParents) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 482 483 /*! @function getProperty 484 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. 485 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 486 * @param aKey The property's name as an OSString. 487 * @param plane The plane to iterate over, eg. gIOServicePlane. 488 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 489 * @result The property value found, or zero. */ 490 491 virtual OSObject * getProperty( const OSString * aKey, 492 const IORegistryPlane * plane, 493 IOOptionBits options = 494 kIORegistryIterateRecursively | 495 kIORegistryIterateParents) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 496 497 /*! @function getProperty 498 * @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. 499 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 500 * @param aKey The property's name as a C-string. 501 * @param plane The plane to iterate over, eg. gIOServicePlane. 502 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 503 * @result The property value found, or zero. */ 504 505 virtual OSObject * getProperty( const char * aKey, 506 const IORegistryPlane * plane, 507 IOOptionBits options = 508 kIORegistryIterateRecursively | 509 kIORegistryIterateParents) const APPLE_KEXT_DEPRECATED_WITH_SHARED_PTR; 510 511 /*! @function propertyExists 512 * @abstract Synchronized method to check if a property exists from a registry entry or one of its parents (or children) in the hierarchy. 513 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 514 * @param aKey The property's name as an OSSymbol. 515 * @param plane The plane to iterate over, eg. gIOServicePlane. 516 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 517 * @result True if the property was found. */ 518 519 bool propertyExists( const OSSymbol * aKey, 520 const IORegistryPlane * plane, 521 uint32_t options = 522 kIORegistryIterateRecursively | 523 kIORegistryIterateParents) const; 524 525 /*! @function propertyExists 526 * @abstract Synchronized method to check if a property exists from a registry entry or one of its parents (or children) in the hierarchy. 527 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 528 * @param aKey The property's name as an OSString. 529 * @param plane The plane to iterate over, eg. gIOServicePlane. 530 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 531 * @result True if the property was found. */ 532 533 bool propertyExists( const OSString * aKey, 534 const IORegistryPlane * plane, 535 uint32_t options = 536 kIORegistryIterateRecursively | 537 kIORegistryIterateParents) const; 538 539 /*! @function propertyExists 540 * @abstract Synchronized method to check if a property exists from a registry entry or one of its parents (or children) in the hierarchy. 541 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 542 * @param aKey The property's name as a C-string. 543 * @param plane The plane to iterate over, eg. gIOServicePlane. 544 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 545 * @result True if the property was found. */ 546 547 bool propertyExists( const char * aKey, 548 const IORegistryPlane * plane, 549 uint32_t options = 550 kIORegistryIterateRecursively | 551 kIORegistryIterateParents) const; 552 553 /*! @function propertyHasValue 554 * @abstract Synchronized method to check if a property has a given value from a registry entry or one of its parents (or children) in the hierarchy. 555 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true if the property isEqualTo() the supplied value. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 556 * @param aKey The property's name as an OSSymbol. 557 * @param value The property value to be compared. 558 * @param plane The plane to iterate over, eg. gIOServicePlane. 559 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 560 * @result True if the property was found and isEqualTo() the supplied value. */ 561 562 bool propertyHasValue( const OSSymbol * aKey, 563 const OSObject * value, 564 const IORegistryPlane * plane, 565 uint32_t options = 566 kIORegistryIterateRecursively | 567 kIORegistryIterateParents) const; 568 569 /*! @function propertyHasValue 570 * @abstract Synchronized method to check if a property has a given value from a registry entry or one of its parents (or children) in the hierarchy. 571 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true if the property isEqualTo() the supplied value. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 572 * @param aKey The property's name as an OSString. 573 * @param value The property value to be compared. 574 * @param plane The plane to iterate over, eg. gIOServicePlane. 575 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 576 * @result True if the property was found and isEqualTo() the supplied value. */ 577 578 bool propertyHasValue( const OSString * aKey, 579 const OSObject * value, 580 const IORegistryPlane * plane, 581 uint32_t options = 582 kIORegistryIterateRecursively | 583 kIORegistryIterateParents) const; 584 585 /*! @function propertyHasValue 586 * @abstract Synchronized method to check if a property has a given value from a registry entry or one of its parents (or children) in the hierarchy. 587 * @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will return true if the property isEqualTo() the supplied value. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s). 588 * @param aKey The property's name as a C-string. 589 * @param value The property value to be compared. 590 * @param plane The plane to iterate over, eg. gIOServicePlane. 591 * @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard propertyExists() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. 592 * @result True if the property was found and isEqualTo() the supplied value. */ 593 594 bool propertyHasValue( const char * aKey, 595 const OSObject * value, 596 const IORegistryPlane * plane, 597 uint32_t options = 598 kIORegistryIterateRecursively | 599 kIORegistryIterateParents) const; 600 601 602 /*! @function copyProperty 603 * @abstract Synchronized method to obtain a property from a registry entry's property table. 604 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table. 605 * @param aKey The property's name as an OSSymbol. 606 * @result The property value found, or zero. It should be released by the caller. */ 607 608 virtual OSPtr<OSObject> copyProperty( const OSSymbol * aKey) const; 609 610 /*! @function copyProperty 611 * @abstract Synchronized method to obtain a property from a registry entry's property table. 612 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table. 613 * @param aKey The property's name as an OSString. 614 * @result The property value found, or zero. It should be released by the caller. */ 615 616 virtual OSPtr<OSObject> copyProperty( const OSString * aKey) const; 617 618 /*! @function copyProperty 619 * @abstract Synchronized method to obtain a property from a registry entry's property table. 620 * @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table. 621 * @param aKey The property's name as a C-string. 622 * @result The property value found, or zero. It should be released by the caller. */ 623 624 virtual OSPtr<OSObject> copyProperty( const char * aKey) const; 625 626 /*! @function dictionaryWithProperties 627 * @abstract Synchronized method to obtain copy a registry entry's property table. 628 * @discussion This method will copy a registry entry's property table, using the OSDictionary::withDictionary semantics. This method is synchronized with other IORegistryEntry accesses to the property table. Since OSDictionary will only copy property values by reference, synchronization is not guaranteed to any collection values. 629 * @result The created dictionary, or zero on a resource value. It should be released by the caller. */ 630 631 virtual OSPtr<OSDictionary> dictionaryWithProperties( void ) const; 632 633 /*! @function serializeProperties 634 * @abstract Synchronized method to serialize a registry entry's property table. 635 * @discussion This method will serialize a registry entry's property table, using the OSDictionary::serialize semantics. This method is synchronized with other IORegistryEntry accesses to the property table. Many non-kernel clients of IOKit read information from the registry via properties, and will invoke this method in a registry entry to create a serialization of all the entry's properties, which is then reconstructed in the client's task as a CFDictionary. This method may be intercepted by subclasses to update their properties or implement a different serialization method, though it is usually better to implement such functionality by creating objects in the property table and implementing their serialize methods, avoiding any need to implement serializeProperties. 636 * @param serialize The OSSerialize instance representing the serialization request. 637 * @result True on success, false otherwise. */ 638 639 virtual bool serializeProperties( OSSerialize * serialize ) const; 640 641 /* Unsynchronized(!) property table access */ 642 643 /*! @function getPropertyTable 644 * @abstract Unsynchronized accessor to a registry entry's property table. 645 * @discussion This method will return a pointer to the live property table as an OSDictionery. Its use is not recommended in most cases, instead use the synchronized accessors and helper functions of IORegistryEntry to access properties. It can only safely be used by one thread, which usually means it can only be used before a registry entry is entered into the registry. 646 * @result A pointer to the property table as an OSDictionary. The pointer is valid while the registry entry is retained, and should not be released by the caller. */ 647 648 /* inline */ OSDictionary * getPropertyTable( void ) const; 649 /* { return(fPropertyTable); } */ 650 651 /* Set properties from user level, to be overridden if supported */ 652 653 /*! @function setProperties 654 * @abstract Optionally supported external method to set properties in a registry entry. 655 * @discussion This method is not implemented by IORegistryEntry, but is available to kernel and non-kernel clients to set properties in a registry entry. IOUserClient provides connection based, more controlled access to this functionality and may be more appropriate for many uses, since there is no differentiation between clients available to this method. 656 * @param properties Any OSObject subclass, to be interpreted by the implementing method - for example an OSDictionary, OSData etc. may all be appropriate. 657 * @result An IOReturn code to be returned to the caller. */ 658 659 virtual IOReturn setProperties( OSObject * properties ); 660 661 /* Topology */ 662 663 /*! @function getParentIterator 664 * @abstract Returns an iterator over an registry entry's parent entries in a specified plane. 665 * @param plane The plane object. 666 * @result Returns an iterator over the parents of the registry entry, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration. */ 667 668 virtual OSPtr<OSIterator> getParentIterator( const IORegistryPlane * plane ) 669 const; 670 virtual void applyToParents( IORegistryEntryApplierFunction applier, 671 void * context, 672 const IORegistryPlane * plane ) const; 673 674 /*! @function getParentEntry 675 * @abstract Returns an registry entry's first parent entry in a plane. 676 * @discussion This function will return the parent to which a registry entry was first attached. Since the majority of registry entrys have only one provider, this is a useful simplification. 677 * @param plane The plane object. 678 * @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. The parent is retained while the entry is attached, and should not be released by the caller. */ 679 680 virtual IORegistryEntry * getParentEntry( const IORegistryPlane * plane ) const; 681 682 /*! @function getChildIterator 683 * @abstract Returns an iterator over an registry entry's child entries in a plane. 684 * @discussion This method creates an iterator which will return each of a registry entry's child entries in a specified plane. 685 * @param plane The plane object. 686 * @result Returns an iterator over the children of the entry, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration. */ 687 688 virtual OSPtr<OSIterator> getChildIterator( const IORegistryPlane * plane ) 689 const; 690 691 #if XNU_KERNEL_PRIVATE 692 uint32_t getChildCount( const IORegistryPlane * plane ) const; 693 OSPtr<OSArray> copyPropertyKeys(void) const; 694 #endif 695 696 virtual void applyToChildren( IORegistryEntryApplierFunction applier, 697 void * context, 698 const IORegistryPlane * plane ) const; 699 700 /*! @function getChildEntry 701 * @abstract Returns an registry entry's first child entry in a plane. 702 * @discussion This function will return the child which first attached to a registry entry. 703 * @param plane The plane object. 704 * @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. The child is retained while the entry is attached, and should not be released by the caller. */ 705 706 virtual IORegistryEntry * getChildEntry( const IORegistryPlane * plane ) const; 707 708 /*! @function isChild 709 * @abstract Determines whether a registry entry is the child of another in a plane. 710 * @discussion This method called in the parent entry determines if the specified entry is a child, in a plane. Additionally, it can check if the child is the only child of the parent entry. 711 * @param child The possible child registry entry. 712 * @param plane The plane object. 713 * @param onlyChild If true, check also if the child is the only child. 714 * @result If the child argument is not a child of the registry entry, false is returned. If onlyChild is true and the child is not the only child of the entry, false is returned, otherwise true is returned. */ 715 716 virtual bool isChild( IORegistryEntry * child, 717 const IORegistryPlane * plane, 718 bool onlyChild = false ) const; 719 720 /*! @function isParent 721 * @abstract Determines whether a registry entry is the parent of another in a plane. 722 * @discussion This method called in the child entry determines if the specified entry is a parent, in a plane. Additionally, it can check if the parent is the only parent of the child entry. 723 * @param parent The possible parent registry entry. 724 * @param plane The plane object. 725 * @param onlyParent If true, check also if the parent is the only parent. 726 * @result If the parent argument is not a parent of the registry entry, false is returned. If onlyParent is true and the parent is not the only parent of the entry, false is returned, otherwise true is returned. */ 727 728 virtual bool isParent( IORegistryEntry * parent, 729 const IORegistryPlane * plane, 730 bool onlyParent = false ) const; 731 732 /*! @function inPlane 733 * @abstract Determines whether a registry entry is attached in a plane. 734 * @discussion This method determines if the entry is attached in a plane to any other entry. It can also be used to determine if the entry is a member of any plane. 735 * @param plane The plane object, 0 indicates any plane. 736 * @result If the entry has a parent in the given plane or if plane = 0 then if entry has any parent; return true, otherwise false. */ 737 738 virtual bool inPlane( const IORegistryPlane * plane = NULL) const; 739 740 /*! @function getDepth 741 * @abstract Counts the maximum number of entries between an entry and the registry root, in a plane. 742 * @discussion This method counts the number of entries between and entry and the registry root, in a plane, for each parent of the entry and returns the maximum value. 743 * @param plane The plane object. 744 * @result The maximum number of entries between the entry and the root. Zero is returned if the entry is not attached in the plane. */ 745 746 virtual unsigned int getDepth( const IORegistryPlane * plane ) const; 747 748 /* Attach / detach */ 749 750 /*! @function attachToParent 751 * @abstract Attaches a entry to a parent entry in a plane. 752 * @discussion This is the usual method of entering an entry into the registry. It is a no-op and success if the entry is already attached to the parent. Attaching the entry into the registry retains both the child and parent while they are attached. This method will call attachToChild in the parent entry if it is not being called from attachToChild. 753 * @param parent The registry entry to attach to. 754 * @param plane The plane object. 755 * @result true on success, or false on a resource failure, or if the parent is the same as the child. */ 756 757 virtual bool attachToParent( IORegistryEntry * parent, 758 const IORegistryPlane * plane ); 759 760 /*! @function detachFromParent 761 * @abstract Detaches an entry from a parent entry in a plane. 762 * @discussion This is the usual method of removing an entry from the registry. It is a no-op if the entry is not attached to the parent. Detaching the entry will release both the child and parent. This method will call detachFromChild in the parent entry if it is not being called from detachFromChild. 763 * @param parent The registry entry to detach from. 764 * @param plane The plane object. */ 765 766 virtual void detachFromParent( IORegistryEntry * parent, 767 const IORegistryPlane * plane ); 768 769 /*! @function attachToChild 770 * @abstract Method called in the parent entry when a child attaches. 771 * @discussion This method is called in the parent entry when a child attaches, to make overrides possible. This method will also call attachToParent in the child entry if it is not being called from attachToParent. It is a no-op and success if the entry is already a child. Attaching the entry into the registry retains both the child and parent while they are attached. 772 * @param child The registry entry being attached. 773 * @param plane The plane object. 774 * @result true on success, or false on a resource failure, or if the parent is the same as the child. */ 775 776 virtual bool attachToChild( IORegistryEntry * child, 777 const IORegistryPlane * plane ); 778 779 /*! @function detachFromChild 780 * @abstract Detaches a child entry from its parent in a plane. 781 * @discussion This method is called in the parent entry when a child detaches, to make overrides possible. It is a no-op if the entry is not a child of the parent. Detaching the entry will release both the child and parent. This method will call detachFromParent in the child entry if it is not being called from detachFromParent. 782 * @param child The registry entry to detach. 783 * @param plane The plane object. */ 784 785 virtual void detachFromChild( IORegistryEntry * child, 786 const IORegistryPlane * plane ); 787 788 /*! @function detachAbove 789 * @abstract Detaches an entry from all its parent entries in a plane. 790 * @discussion This method calls detachFromParent in the entry for each of its parent entries in the plane. 791 * @param plane The plane object. */ 792 793 virtual void detachAbove( const IORegistryPlane * plane ); 794 795 /*! @function detachAll 796 * @abstract Detaches an entry and all its children recursively in a plane. 797 * @discussion This method breaks the registry connections for a subtree. detachAbove is called in the entry, and all child entries and their children in the plane. 798 * @param plane The plane object. */ 799 800 virtual void detachAll( const IORegistryPlane * plane ); 801 802 /* Name, location and path accessors */ 803 804 /*! @function getName 805 * @abstract Returns the name assigned to the registry entry as a C-string. 806 * @discussion Entries can be named in a particular plane, or globally. If the entry is named in plane and the plane is specified that name will be returned, otherwise the global name is returned. The global name defaults to the entry's meta class name if it has not been named. 807 * @param plane The plane object, or zero for the global name. 808 * @result A C-string name, valid while the entry is retained. */ 809 810 virtual const char * getName( const IORegistryPlane * plane = NULL ) const; 811 812 /*! @function copyName 813 * @abstract Returns the name assigned to the registry entry as an OSSymbol. 814 * @discussion Entries can be named in a particular plane, or globally. If the entry is named in plane and the plane is specified that name will be returned, otherwise the global name is returned. The global name defaults to the entry's meta class name if it has not been named. 815 * @param plane The plane object, or zero for the global name. 816 * @result A reference to an OSSymbol for the name, which should be released by the caller. */ 817 818 virtual OSPtr<const OSSymbol> copyName( 819 const IORegistryPlane * plane = NULL ) const; 820 821 /*! @function compareNames 822 * @abstract Compares the name of the entry with one or more names, and optionally returns the matching name. 823 * @discussion This method is called during IOService name matching and elsewhere to compare the entry's global name with a list of names, or a single name. A list of names may be passed as any OSCollection of OSStrings, while a single name may be passed an OSString, in the name parameter. compareNames will call the compareName method for each name, for overrides. 824 * @param name The name or names to compare with as any OSCollection (eg. OSArray, OSSet, OSDictionary) of OSStrings, or a single name may be passed an OSString. 825 * @param matched If the caller wants the successfully matched name returned, pass a non-zero pointer for the matched parameter and an OSString will be returned here. It should be released by the caller. 826 * @result True if one of the names compared true with the entry's global name. */ 827 828 virtual bool compareNames( OSObject * name, OSString ** matched = NULL ) const; 829 830 bool compareNames( OSObject * name, OSSharedPtr<OSString>& matched) const; 831 832 /*! @function compareName 833 * @abstract Compares the name of the entry with one name, and optionally returns the matching name. 834 * @discussion This method is called during IOService name matching and elsewhere from the compareNames method. It should be overridden to provide non-standard name matching. 835 * @param name The name to compare with as an OSString. 836 * @param matched If the caller wants the successfully matched name returned, pass a non-zero pointer for the matched parameter and an OSString will be returned here. It should be released by the caller. Generally, this will be the same as the name parameter, but may not be if wildcards are used. 837 * @result True if the name compared true with the entry's global name. */ 838 839 virtual bool compareName( OSString * name, OSString ** matched = NULL ) const; 840 841 bool compareName( OSString * name, OSSharedPtr<OSString>& matched) const; 842 843 /*! @function setName 844 * @abstract Sets a name for the registry entry, in a particular plane, or globally. 845 * @discussion Entries can be named in a particular plane, or globally. If the plane is specified the name applies only to that plane, otherwise the global name is set. The global name defaults to the entry's meta class name if it has not been named. 846 * @param name An OSSymbol which will be retained. 847 * @param plane The plane object, or zero to set the global name. */ 848 849 virtual void setName( const OSSymbol * name, 850 const IORegistryPlane * plane = NULL ); 851 852 /*! @function setName 853 * @abstract Sets a name for the registry entry, in a particular plane, or globally. 854 * @discussion Entries can be named in a particular plane, or globally. If the plane is specified the name applies only to that plane, otherwise the global name is set. The global name defaults to the entry's meta class name if it has not been named. 855 * @param name A const C-string name which will be copied. 856 * @param plane The plane object, or zero to set the global name. */ 857 858 virtual void setName( const char * name, 859 const IORegistryPlane * plane = NULL ); 860 861 /*! @function getLocation 862 * @abstract Returns the location string assigned to the registry entry as a C-string. 863 * @discussion Entries can given a location string in a particular plane, or globally. If the entry has had a location set in a plane and the plane is specified that location string will be returned, otherwise the global location string is returned. If no global location string has been set, zero is returned. 864 * @param plane The plane object, or zero for the global name. 865 * @result A C-string location string, valid while the entry is retained, or zero. */ 866 867 virtual const char * getLocation( const IORegistryPlane * plane = NULL ) const; 868 869 /*! @function copyLocation 870 * @abstract Returns the location string assigned to the registry entry as an OSSymbol. 871 * @discussion Entries can given a location string in a particular plane, or globally. If the entry has had a location set in a plane and the plane is specified that location string will be returned, otherwise the global location string is returned. If no global location string has been set, zero is returned. 872 * @param plane The plane object, or zero for the global name. 873 * @result A reference to an OSSymbol for the location if one exists, which should be released by the caller, or zero. */ 874 875 virtual OSPtr<const OSSymbol> copyLocation( 876 const IORegistryPlane * plane = NULL ) const; 877 878 /*! @function setLocation 879 * @abstract Sets a location string for the registry entry, in a particular plane, or globally. 880 * @discussion Entries can be given a location string in a particular plane, or globally. If the plane is specified the location applies only to that plane, otherwise the global location is set. The location string may be used during path lookups of registry entries, to distinguish between sibling entries with the same name. The default IORegistryEntry parsing of location strings expects a list of hex numbers separated by commas, though subclasses of IORegistryEntry might do their own parsing. 881 * @param location A C-string location string which will be copied, or an OSSymbol which will be retained. 882 * @param plane The plane object, or zero to set the global location string. */ 883 884 virtual void setLocation( const OSSymbol * location, 885 const IORegistryPlane * plane = NULL ); 886 virtual void setLocation( const char * location, 887 const IORegistryPlane * plane = NULL ); 888 889 /*! @function getPath 890 * @abstract Create a path for a registry entry. 891 * @discussion The path for a registry entry is copied to the caller's buffer. The path describes the entry's attachment in a particular plane, which must be specified. The path begins with the plane name followed by a colon, and then followed by '/' separated path components for each of the entries between the root and the registry entry. Each component is constructed with the getPathComponent method called in each entry. An alias may also exist for the entry, which are described as properties in a registry entry found at /aliases in the plane. If a property value interpreted as a path in a call to IORegistryEntry::fromPath yields the entry, then the property name is used as the entry's path. 892 * @param path A char buffer allocated by the caller. 893 * @param length An in/out parameter - the caller sets the length of the buffer available, and getPath returns the total length of the path copied to the buffer. 894 * @param plane The plane object. 895 * @result getPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path. */ 896 897 virtual bool getPath( char * path, int * length, 898 const IORegistryPlane * plane) const; 899 900 /*! @function getPathComponent 901 * @abstract Create a path component for a registry entry. 902 * @discussion Each component of a path created with getPath is created with getPathComponent. The default implementation concatenates the entry's name in the the plane, with the "at" symbol and the location string of the entry in the plane if it has been set. 903 * @param path A char buffer allocated by the caller. 904 * @param length An in/out parameter - the caller sets the length of the buffer available, and getPathComponent returns the total length of the path component copied to the buffer. 905 * @param plane The plane object. 906 * @result true if the path fits into the supplied buffer or false on a overflow. */ 907 908 virtual bool getPathComponent( char * path, int * length, 909 const IORegistryPlane * plane ) const; 910 911 /*! @function fromPath 912 * @abstract Looks up a registry entry by path. 913 * @discussion This function parses paths to lookup registry entries. The path may begin with the <plane name>: created by getPath, or the plane may be set by the caller. If there are characters remaining unparsed after an entry has been looked up, this may be considered an invalid lookup, or those characters may be passed back to the caller and the lookup successful. 914 * @param path A C-string path. 915 * @param plane The plane to lookup up the path, or zero, in which case the path must begin with the plane name. 916 * @param residualPath If the path may contain residual characters after the last path component, the residual will be copied back to the caller's residualPath buffer. If there are residual characters and no residual buffer is specified, fromPath will fail. 917 * @param residualLength An in/out parameter - the caller sets the length of the residual buffer available, and fromPath returns the total length of the residual path copied to the buffer. If there is no residualBuffer (residualPath = 0) then residualLength may be zero also. 918 * @param fromEntry The lookup will proceed rooted at this entry if non-zero, otherwise it proceeds from the root of the plane. 919 * @result A retained registry entry is returned on success, or zero on failure. The caller should release the entry. */ 920 921 static OSPtr<IORegistryEntry> fromPath( const char * path, 922 const IORegistryPlane * plane = NULL, 923 char * residualPath = NULL, 924 int * residualLength = NULL, 925 IORegistryEntry * fromEntry = NULL ); 926 927 /*! @function fromPath 928 * @abstract Looks up a registry entry by relative path. 929 * @discussion This function looks up a entry below the called entry by a relative path. It is just a convenience that calls IORegistryEntry::fromPath with this as the fromEntry parameter. 930 * @param path See IORegistryEntry::fromPath. 931 * @param plane See IORegistryEntry::fromPath. 932 * @param residualPath See IORegistryEntry::fromPath. 933 * @param residualLength See IORegistryEntry::fromPath. 934 * @result See IORegistryEntry::fromPath. */ 935 936 virtual OSPtr<IORegistryEntry> childFromPath( const char * path, 937 const IORegistryPlane * plane = NULL, 938 char * residualPath = NULL, 939 int * residualLength = NULL ); 940 941 /*! @function dealiasPath 942 * @abstract Strips any aliases from the head of path and returns the full path. 943 * @discussion If the path specified begins with an alias found in the /aliases entry, the value of the alias is returned, and a pointer into the passed in path after the alias is passed back to the caller. If an alias is not found, zero is returned and the path parameter is unchanged. 944 * @param opath An in/out paramter - the caller passes in a pointer to a C-string pointer to a path. If an alias is found, dealiasPath returns a pointer into the path just beyond the end of the alias. 945 * @param plane A plane object must be specified. 946 * @result A C-string pointer to the value of the alias if one is found, or zero if not. */ 947 948 static const char * dealiasPath( const char ** opath, 949 const IORegistryPlane * plane ); 950 951 /*! @function makePlane 952 * @abstract Constructs an IORegistryPlane object. 953 * @discussion Most planes in IOKit are created by the OS, although other planes may be created. 954 * @param name A C-string name for the new plane, to be copied. 955 * @result A new instance of an IORegistryPlane, or zero on failure. */ 956 957 static OSPtr<const IORegistryPlane> makePlane( const char * name ); 958 959 /*! @abstract Returns an ID for the registry entry that is global to all tasks. 960 * @discussion The entry ID returned by getRegistryEntryID can be used to identify a registry entry across all tasks. A registry entry may be looked up by its entry ID by creating a matching dictionary with IORegistryEntryIDMatching() in user space, or <code>IOService::registryEntryIDMatching()</code> in the kernel, to be used with the IOKit matching functions. The ID is valid only until the machine reboots. 961 * @result An ID for the registry entry, assigned when the entry is first attached in the registry. */ 962 963 uint64_t getRegistryEntryID( void ); 964 965 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 966 /* * * * * * * * * * * * internals * * * * * * * * * * * */ 967 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 968 969 virtual bool init( IORegistryEntry * from, 970 const IORegistryPlane * inPlane ); 971 972 #ifdef XNU_KERNEL_PRIVATE 973 public: 974 #else 975 private: 976 #endif 977 static LIBKERN_RETURNS_NOT_RETAINED IORegistryEntry * initialize( void ); 978 979 #ifdef XNU_KERNEL_PRIVATE 980 SInt32 getRegistryEntryGenerationCount( void ) const; 981 void setName(const OSString * name, 982 const IORegistryPlane * plane = NULL); 983 #endif 984 985 private: 986 inline bool arrayMember( OSArray * set, 987 const IORegistryEntry * member, 988 unsigned int * index = NULL ) const; 989 990 bool makeLink( IORegistryEntry * to, 991 unsigned int relation, 992 const IORegistryPlane * plane ) const; 993 void breakLink( IORegistryEntry * to, 994 unsigned int relation, 995 const IORegistryPlane * plane ) const; 996 997 APPLE_KEXT_COMPATIBILITY_VIRTUAL 998 OSArray * getParentSetReference( const IORegistryPlane * plane ) 999 const; 1000 1001 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1002 OSArray * getChildSetReference( const IORegistryPlane * plane ) 1003 const; 1004 1005 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1006 IORegistryEntry * getChildFromComponent( const char ** path, 1007 const IORegistryPlane * plane ); 1008 1009 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1010 LIBKERN_RETURNS_NOT_RETAINED const OSSymbol * hasAlias( 1011 const IORegistryPlane * plane, 1012 char * opath = NULL, int * length = NULL ) const; 1013 1014 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1015 const char * matchPathLocation( const char * cmp, 1016 const IORegistryPlane * plane ); 1017 }; 1018 1019 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1020 1021 /*! @class IORegistryIterator : public OSIterator 1022 * @abstract An iterator over the registry. 1023 * @discussion An iterator that can traverse the children or parents of a registry entry in a plane, and recurse. Access to the registry is protected against multiple threads, but an IORegistryIterator instance is for use by one thread only. */ 1024 1025 class IORegistryIterator : public OSIterator 1026 { 1027 OSDeclareAbstractStructors(IORegistryIterator); 1028 1029 private: 1030 struct IORegCursor { 1031 IORegCursor * next; 1032 IORegistryEntry * current; 1033 OSIterator * iter; 1034 }; 1035 IORegCursor start; 1036 IORegCursor * where; 1037 IORegistryEntry * root; 1038 OSOrderedSet * done; 1039 const IORegistryPlane * plane; 1040 IOOptionBits options; 1041 1042 virtual void free( void ) APPLE_KEXT_OVERRIDE; 1043 1044 public: 1045 /*! @function iterateOver 1046 * @abstract Create an iterator rooted at a given registry entry. 1047 * @discussion This method creates an IORegistryIterator that is set up with options to iterate children or parents of a root entry, and to recurse automatically into entries as they are returned, or only when instructed. The iterator object keeps track of entries that have been recursed into previously to avoid loops. 1048 * @param start The root entry to begin the iteration at. 1049 * @param plane A plane object must be specified. 1050 * @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned. This option affects the behaviour of the getNextObject method, which is defined in the OSIterator superclass. Other methods will override this behaviour. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated. 1051 * @result A created IORegistryIterator instance, to be released by the caller when it has finished with it. */ 1052 1053 static OSPtr<IORegistryIterator> iterateOver( IORegistryEntry * start, 1054 const IORegistryPlane * plane, 1055 IOOptionBits options = 0 ); 1056 1057 /*! @function iterateOver 1058 * @abstract Create an iterator rooted at the registry root. 1059 * @discussion This method creates an IORegistryIterator that is set up with options to iterate children of the registry root entry, and to recurse automatically into entries as they are returned, or only when instructed. The iterator object keeps track of entries that have been recursed into previously to avoid loops. 1060 * @param plane A plane object must be specified. 1061 * @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned. This option affects the behaviour of the getNextObject method, which is defined in the OSIterator superclass. Other methods will override this behaviour. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated. 1062 * @result A created IORegistryIterator instance, to be released by the caller when it has finished with it. */ 1063 1064 static OSPtr<IORegistryIterator> iterateOver( const IORegistryPlane * plane, 1065 IOOptionBits options = 0 ); 1066 1067 /*! @function getNextObject 1068 * @abstract Return the next object in the registry iteration. 1069 * @discussion This method calls either getNextObjectFlat or getNextObjectRecursive depending on the options the iterator was created with. This implements the OSIterator defined getNextObject method. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. 1070 * @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion. The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */ 1071 1072 virtual IORegistryEntry * getNextObject( void ) APPLE_KEXT_OVERRIDE; 1073 1074 /*! @function getNextObjectFlat 1075 * @abstract Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option. 1076 * @discussion This method returns the next child, or parent if the kIORegistryIterateParents option was used to create the iterator, of the current root entry. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. 1077 * @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */ 1078 1079 virtual IORegistryEntry * getNextObjectFlat( void ); 1080 1081 /*! @function getNextObjectRecursive 1082 * @abstract Return the next object in the registry iteration, and enter it. 1083 * @discussion If the iterator has a current entry, and the iterator has not already entered previously, enterEntry is called to recurse into it, ie. make it the new root, and the next child, or parent if the kIORegistryIterateParents option was used to create the iterator, at this new level of recursion is returned. If there is no current entry at this level of recursion, exitEntry is called and the process repeats, until the iteration returns to the entry the iterator was created with and zero is returned. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. 1084 * @result The next registry entry in the iteration (the current entry), or zero if its finished, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */ 1085 1086 virtual IORegistryEntry * getNextObjectRecursive( void ); 1087 1088 /*! @function getCurrentEntry 1089 * @abstract Return the current entry in the registry iteration. 1090 * @discussion This method returns the current entry, last returned by getNextObject et al. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. If the iteration is no longer valid (see isValid), the current entry is zero. 1091 * @result The current registry entry in the iteration, or zero if the last iteration returned zero, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */ 1092 1093 virtual IORegistryEntry * getCurrentEntry( void ); 1094 1095 /*! @function enterEntry 1096 * @abstract Recurse into the current entry in the registry iteration. 1097 * @discussion This method makes the current entry, ie. the last entry returned by getNextObject et al., the root in a new level of recursion. */ 1098 1099 virtual void enterEntry( void ); 1100 1101 /*! @function enterEntry 1102 * @abstract Recurse into the current entry in the registry iteration. 1103 * @discussion This method recurses into an entry as with enterEntry, but also switches from the current plane to a new one set by the caller. 1104 * @param plane The new plane to switch into. */ 1105 1106 virtual void enterEntry( const IORegistryPlane * plane ); 1107 1108 /*! @function exitEntry 1109 * @abstract Exits a level of recursion, restoring the current entry. 1110 * @discussion This method undoes an enterEntry, restoring the current entry. If there are no more levels of recursion to exit false is returned, otherwise true is returned. 1111 * @result true if a level of recursion was undone, false if no recursive levels are left in the iteration. */ 1112 1113 virtual bool exitEntry( void ); 1114 1115 /*! @function reset 1116 * @abstract Exits all levels of recursion, restoring the iterator to its state at creation. 1117 * @discussion This method exits all levels of recursion, and restores the iterator to its state at creation. */ 1118 1119 virtual void reset( void ) APPLE_KEXT_OVERRIDE; 1120 1121 /*! @function isValid 1122 * @abstract Checks that no registry changes have invalidated the iteration. 1123 * @discussion If a registry iteration is invalidated by changes to the registry, it will be made invalid, the currentEntry will be considered zero, and further calls to getNextObject et al. will return zero. The iterator should be reset to restart the iteration when this happens. 1124 * @result false if the iterator has been invalidated by changes to the registry, true otherwise. */ 1125 1126 virtual bool isValid( void ) APPLE_KEXT_OVERRIDE; 1127 1128 /*! @function iterateAll 1129 * @abstract Iterates all entries (with getNextObject) and returns a set of all returned entries. 1130 * @discussion This method will reset, then iterate all entries in the iteration (with getNextObject). 1131 * @result A set of entries returned by the iteration. The caller should release the set when it has finished with it. Zero is returned on a resource failure. */ 1132 1133 virtual OSPtr<OSOrderedSet> iterateAll( void ); 1134 }; 1135 1136 #endif /* _IOKIT_IOREGISTRYENTRY_H */ 1137