iokit/IOKit/IORegistryEntry.h

61     @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.
94     @param aKey The property's name as a C-string.
108     @param aKey The property's name as an OSString.
122     @param aKey The property's name as an OSSymbol.
244     @abstract Looks up the plane object by a C-string name.
245     @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.
248     static const IORegistryPlane * getPlane( const char * name );
279     @param aKey The properties name as an OSSymbol.
288     @param aKey The property's name as an OSString.
297     @param aKey The property's name as a C-string.
305     @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.
306     @param aKey The property's name as a C-string.
314     @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.
315     @param aKey The property's name as a C-string.
323     @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.
324     @param aKey The property's name as a C-string.
335     @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.
336     @param aKey The property's name as a C-string.
348     @param aKey The property's name as an OSSymbol. */
355     @param aKey The property's name as an OSString. */
362     @param aKey The property's name as a C-string. */
369     @param aKey The property's name as an OSSymbol.
377     @param aKey The property's name as an OSString.
385     @param aKey The property's name as a C-string.
393     @param aKey The property's name as an OSSymbol.
407     @param aKey The property's name as an OSString.
421     @param aKey The property's name as a C-string.
435     @param aKey The property's name as an OSSymbol.
443     @param aKey The property's name as an OSString.
451     @param aKey The property's name as a C-string.
630     @abstract Returns the name assigned to the registry entry as a C-string.
631     @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.
632     @param plane The plane object, or zero for the global name.
633     @result A C-string name, valid while the entry is retained. */
638     @abstract Returns the name assigned to the registry entry as an OSSymbol.
639     @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.
640     @param plane The plane object, or zero for the global name.
641     @result A reference to an OSSymbol for the name, which should be released by the caller. */
647     @abstract Compares the name of the entry with one or more names, and optionally returns the matching name.
648     @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.
649     @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.
650     @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.
651     @result True if one of the names compared true with the entry's global name. */
653     virtual bool compareNames( OSObject * name, OSString ** matched = 0 ) const;
656     @abstract Compares the name of the entry with one name, and optionally returns the matching name.
657     @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.
658     @param name The name to compare with as an OSString.
659     @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.
660     @result True if the name compared true with the entry's global name. */
662     virtual bool compareName( OSString * name, OSString ** matched = 0 ) const;
665     @abstract Sets a name for the registry entry, in a particular plane, or globally.
666     @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.
667     @param name An OSSymbol which will be retained.
668     @param plane The plane object, or zero to set the global name. */
670     virtual void setName( const OSSymbol * name,
674     @abstract Sets a name for the registry entry, in a particular plane, or globally.
675     @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.
676     @param name A const C-string name which will be copied.
677     @param plane The plane object, or zero to set the global name. */
679     virtual void setName( const char * name,
685     @param plane The plane object, or zero for the global name.
693     @param plane The plane object, or zero for the global name.
701     @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.
712     @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.
723     @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.
734     @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.
736     @param plane The plane to lookup up the path, or zero, in which case the path must begin with the plane name.
775     @param name A C-string name for the new plane, to be copied.
778     static const IORegistryPlane * makePlane( const char * name );