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.
95     @param plane The plane to iterate over, eg. gIOServicePlane.
100                                      const IORegistryPlane * plane,
109     @param plane The plane to iterate over, eg. gIOServicePlane.
114                                      const IORegistryPlane * plane,
123     @param plane The plane to iterate over, eg. gIOServicePlane.
128                                      const IORegistryPlane * plane,
134     @abstract Returns an registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.
136     @param plane The plane object.
137     @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. */
139     virtual IORegistryEntry * copyParentEntry( const IORegistryPlane * plane ) const;
142     @abstract Returns an registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.
144     @param plane The plane object.
145     @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. */
147     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;
231     @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.
244     @abstract Looks up the plane object by a C-string name.
246     @result A pointer to the plane object, or zero if no such plane exists. The returned plane should not be released. */
394     @param plane The plane to iterate over, eg. gIOServicePlane.
399                                     const IORegistryPlane * plane,
408     @param plane The plane to iterate over, eg. gIOServicePlane.
413                                     const IORegistryPlane * plane,
422     @param plane The plane to iterate over, eg. gIOServicePlane.
427                                     const IORegistryPlane * plane,
494     @abstract Returns an iterator over an registry entry's parent entries in a specified plane.
495     @param plane The plane object.
498     virtual OSIterator * getParentIterator( const IORegistryPlane * plane )
502                                  const IORegistryPlane * plane ) const;
505     @abstract Returns an registry entry's first parent entry in a plane.
507     @param plane The plane object.
508     @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. */
510     virtual IORegistryEntry * getParentEntry( const IORegistryPlane * plane ) const;
513     @abstract Returns an iterator over an registry entry's child entries in a plane.
514     @discussion This method creates an iterator which will return each of a registry entry's child entries in a specified plane.
515     @param plane The plane object.
518     virtual OSIterator * getChildIterator( const IORegistryPlane * plane )
523                                   const IORegistryPlane * plane ) const;
526     @abstract Returns an registry entry's first child entry in a plane.
528     @param plane The plane object.
529     @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. */
531     virtual IORegistryEntry * getChildEntry( const IORegistryPlane * plane ) const;
534     @abstract Determines whether a registry entry is the child of another in a plane.
535     @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.
537     @param plane The plane object.
542                                 const IORegistryPlane * plane,
546     @abstract Determines whether a registry entry is the parent of another in a plane.
547     @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.
549     @param plane The plane object.
554                                 const IORegistryPlane * plane,
558     @abstract Determines whether a registry entry is attached in a plane.
559     @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.
560     @param plane The plane object, 0 indicates any plane.
561     @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. */
563     virtual bool inPlane( const IORegistryPlane * plane = 0) const;
566     @abstract Counts the maximum number of entries between an entry and the registry root, in a plane.
567     @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.
568     @param plane The plane object.
569     @result The maximum number of entries between the entry and the root. Zero is returned if the entry is not attached in the plane. */
571     virtual unsigned int getDepth( const IORegistryPlane * plane ) const;
576     @abstract Attaches a entry to a parent entry in a plane.
579     @param plane The plane object.
583                                 const IORegistryPlane * plane );
586     @abstract Detaches an entry from a parent entry in a plane.
589     @param plane The plane object. */
592                                 const IORegistryPlane * plane );
598     @param plane The plane object.
602                                 const IORegistryPlane * plane );
605     @abstract Detaches a child entry from its parent in a plane.
608     @param plane The plane object. */
611                                 const IORegistryPlane * plane );
614     @abstract Detaches an entry from all its parent entries in a plane.
615     @discussion This method calls detachFromParent in the entry for each of its parent entries in the plane.
616     @param plane The plane object. */
618     virtual void detachAbove( const IORegistryPlane * plane );
621     @abstract Detaches an entry and all its children recursively in a plane.
622     @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.
623     @param plane The plane object. */
625     virtual void detachAll( const IORegistryPlane * plane );
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.
635     virtual const char * getName( const IORegistryPlane * plane = 0 ) const;
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.
644 				const IORegistryPlane * plane = 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.
668     @param plane The plane object, or zero to set the global name. */
671 				const IORegistryPlane * plane = 0 );
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.
677     @param plane The plane object, or zero to set the global name. */
680 				const IORegistryPlane * plane = 0 );
684     @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.
685     @param plane The plane object, or zero for the global name.
688     virtual const char * getLocation( const IORegistryPlane * plane = 0 ) const;
692     @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.
693     @param plane The plane object, or zero for the global name.
697 				const IORegistryPlane * plane = 0 ) const;
700     @abstract Sets a location string for the registry entry, in a particular plane, or globally.
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.
703     @param plane The plane object, or zero to set the global location string. */
706 				const IORegistryPlane * plane = 0 );
708 				const IORegistryPlane * plane = 0 );
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.
715     @param plane The plane object.
716     @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. */
719                             const IORegistryPlane * plane) const;
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.
726     @param plane The plane object.
730                                     const IORegistryPlane * plane ) const;
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.
739     @param fromEntry The lookup will proceed rooted at this entry if non-zero, otherwise it proceeds from the root of the plane.
743                                         const IORegistryPlane * plane = 0,
752     @param plane See IORegistryEntry::fromPath.
758                                              const IORegistryPlane * plane = 0,
766     @param plane A plane object must be specified.
770                                     const IORegistryPlane * plane );
775     @param name A C-string name for the new plane, to be copied.
807                     const IORegistryPlane * plane ) const;
810                     const IORegistryPlane * plane ) const;
813 	OSArray * getParentSetReference( const IORegistryPlane * plane )
817     OSArray * getChildSetReference( const IORegistryPlane * plane )
822 				const IORegistryPlane * plane );
825     const OSSymbol * hasAlias(  const IORegistryPlane * plane,
830 				const IORegistryPlane * plane );
838     @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. */
854     const IORegistryPlane *	plane;
864     @param plane A plane object must be specified.
869                                              const IORegistryPlane * plane,
875     @param plane A plane object must be specified.
879     static IORegistryIterator * iterateOver( const IORegistryPlane * plane,
918     @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.
919     @param plane The new plane to switch into. */
921     virtual void enterEntry( const IORegistryPlane * plane );