public:
virtual bool attachToChild( IORegistryEntry * child, const IORegistryPlane * plane );
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.
Result: true on success, or false on a resource failure, or if the parent is the same as the child.
Name Description child The registry entry being attached. plane The plane object.
public:
virtual bool attachToParent( IORegistryEntry * parent, const IORegistryPlane * plane );
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.
Result: true on success, or false on a resource failure, or if the parent is the same as the child.
Name Description parent The registry entry to attach to. plane The plane object.
public:
virtual bool compareName( OSString * name, OSString ** matched = 0 ) const;
This method is called during IOService name matching and elsewhere from the compareNames method. It should be overridden to provide non-standard name matching.
Result: True if the name compared true with the entry's global name.
Name Description name The name to compare with as an OSString. 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.
public:
virtual bool compareNames( OSObject * name, OSString ** matched = 0 ) const;
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.
Result: True if one of the names compared true with the entry's global name.
Name Description 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. 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.
public:
virtual const OSSymbol * copyLocation( const IORegistryPlane * plane = 0 ) const;
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.
Result: A reference to an OSSymbol for the location if one exists, which should be released by the caller, or zero.
Name Description plane The plane object, or zero for the global name.
public:
virtual const OSSymbol * copyName( const IORegistryPlane * plane = 0 ) const;
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.
Result: A reference to an OSSymbol for the name, which should be released by the caller.
Name Description plane The plane object, or zero for the global name.
public:
static const char * dealiasPath( const char ** opath, const IORegistryPlane * plane );
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.
Result: A C-string pointer to the value of the alias if one is found, or zero if not.
Name Description 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. plane A plane object must be specified.
public:
virtual void detachAbove( const IORegistryPlane * plane );
This method calls detachFromParent in the entry for each of its parent entries in the plane.
Name Description plane The plane object.
public:
virtual void detachAll( const IORegistryPlane * plane );
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.
Name Description plane The plane object.
public:
virtual void detachFromChild( IORegistryEntry * child, const IORegistryPlane * plane );
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.
Name Description parent The registry entry to detach. plane The plane object.
public:
virtual void detachFromParent( IORegistryEntry * parent, const IORegistryPlane * plane );
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.
Name Description parent The registry entry to detach from. plane The plane object.
public:
virtual OSDictionary * dictionaryWithProperties( void ) const;
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.
Result: The created dictionary, or zero on a resource value. It should be released by the caller.public:
virtual void free( void );
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.
public:
virtual IORegistryEntry * childFromPath( const char * path, const IORegistryPlane * plane = 0, char * residualPath = 0, int * residualLength = 0 );
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.
Result: See IORegistryEntry::fromPath.
Name Description path See IORegistryEntry::fromPath. plane See IORegistryEntry::fromPath. residualPath See IORegistryEntry::fromPath. residualLength See IORegistryEntry::fromPath.
public:
static IORegistryEntry * fromPath( const char * path, const IORegistryPlane * plane = 0, char * residualPath = 0, int * residualLength = 0, IORegistryEntry * fromEntry = 0 );
This function parses paths to lookup registry entries. The path may begin with the
Result: A retained registry entry is returned on success, or zero on failure. The caller should release the entry.
Name Description path A C-string path. plane The plane to lookup up the path, or zero, in which case the path must begin with the plane name. 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. 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. fromEntry The lookup will proceed rooted at this entry if non-zero, otherwise it proceeds from the root of the plane.
public:
virtual IORegistryEntry * getChildEntry( const IORegistryPlane * plane ) const;
This function will return the child which first attached to a registry entry.
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.
Name Description plane The plane object.
public:
virtual OSIterator * getChildIterator( const IORegistryPlane * plane ) const;
This method creates an iterator which will return each of a registry entry's child entries in a specified plane.
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.
Name Description plane The plane object.
public:
virtual unsigned int getDepth( const IORegistryPlane * plane ) const;
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.
Result: The maximum number of entries between the entry and the root. Zero is returned if the entry is not attached in the plane.
Name Description plane The plane object.
public:
static SInt32 getGenerationCount( void );
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.
Result: An integer generation count.public:
virtual const char * getLocation( const IORegistryPlane * plane = 0 ) const;
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.
Result: A C-string location string, valid while the entry is retained, or zero.
Name Description plane The plane object, or zero for the global name.
public:
virtual const char * getName( const IORegistryPlane * plane = 0 ) const;
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.
Result: A C-string name, valid while the entry is retained.
Name Description plane The plane object, or zero for the global name.
public:
virtual IORegistryEntry * getParentEntry( const IORegistryPlane * plane ) const;
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.
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.
Name Description plane The plane object.
public:
virtual OSIterator * getParentIterator( const IORegistryPlane * plane ) const;
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.
Name Description plane The plane object.
public:
virtual bool getPath( char * path, int * length, const IORegistryPlane * plane) const;
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.
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.
Name Description path A char buffer allocated by the caller. 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. plane The plane object.
public:
virtual bool getPathComponent( char * path, int * length, const IORegistryPlane * plane ) const;
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.
Result: true if the path fits into the supplied buffer or false on a overflow.
Name Description path A char buffer allocated by the caller. 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. plane The plane object.
public:
static const IORegistryPlane * getPlane( const char * name );
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.
Result: A pointer to the plane object, or zero if no such plane exists. The returned plane should not be released.public:
virtual OSObject * getProperty( const OSSymbol * aKey) const;
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.
Result: The property value found, or zero.
Name Description aKey The property's name as a OSymbol.
public:
virtual OSObject * getProperty( const OSString * aKey) const;
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.
Result: The property value found, or zero.
Name Description aKey The property's name as anOSString.
public:
virtual OSObject * getProperty( const char * aKey) const;
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.
Result: The property value found, or zero.
Name Description aKey The property's name as a C-string.
public:
inline OSDictionary * getPropertyTable( void ) const { return(fPropertyTable); }
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.
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.public:
static IORegistryEntry * getRegistryRoot( void );
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.
Result: A pointer to the IORegistryEntry root instance. It should not be released by the caller.public:
virtual bool inPlane( const IORegistryPlane * plane ) const;
This method determines if the entry is attached in a plane to any other entry.
Result: If the entry has a parent in the plane, true is returned, otherwise false is returned.
Name Description plane The plane object.
public:
virtual bool init( OSDictionary * dictionary = 0 );
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.
Result: true on success, or false on a resource failure.
Name Description 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.
public:
virtual bool isChild( IORegistryEntry * child, const IORegistryPlane * plane, bool onlyChild = false ) const;
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.
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.
Name Description child The possible child registry entry. plane The plane object. onlyChild If true, check also if the child is the only child.
public:
virtual bool isParent( IORegistryEntry * parent, const IORegistryPlane * plane, bool onlyParent = false ) const;
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.
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.
Name Description parent The possible parent registry entry. plane The plane object. onlyParent If true, check also if the parent is the only parent.
public:
virtual void removeProperty( const char * aKey);
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.
Name Description aKey The property's name as a C-string.
public:
virtual void removeProperty( const OSSymbol * aKey);
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.
Name Description aKey The property's name as an OSSymbol.
public:
virtual void removeProperty( const OSString * aKey);
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.
Name Description aKey The property's name as an OSString.
public:
virtual bool serializeProperties( OSSerialize * serialize ) const;
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.
Result: True on success, false otherwise.
Name Description serialize The OSSerialize instance representing the serialization request.
public:
virtual void setLocation( const OSSymbol * location, const IORegistryPlane * plane = 0 );
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.
Name Description location A C-string location string which will be copied, or an OSSymbol which will be retained. plane The plane object, or zero to set the global location string.
public:
virtual void setName( const OSSymbol * name, const IORegistryPlane * plane = 0 );
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.
Name Description name An OSSymbol which will be retained. plane The plane object, or zero to set the global name.
public:
virtual void setName( const char * name, const IORegistryPlane * plane = 0 );
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.
Name Description name A const C-string name which will be copied. plane The plane object, or zero to set the global name.
public:
virtual IOReturn setProperties( OSObject * properties );
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.
Result: An IOReturn code to be returned to the caller.
Name Description properties Any OSObject subclass, to be interpreted by the implementing method - for example an OSDictionary, OSData etc. may all be appropriate.
public:
virtual bool setProperty(const char * aKey, bool aBoolean);
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.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as a C-string. aBoolean The property's boolean value.
public:
virtual bool setProperty(const char * aKey, OSObject * anObject);
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.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as a C-string. anObject The property value.
public:
virtual bool setProperty(const char * aKey, const char * aString);
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.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as a C-string. aString The property value as a C-string.
public:
virtual bool setProperty(const OSString * aKey, OSObject * anObject);
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.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as an OSString. anObject The property value.
public:
virtual bool setProperty(const OSSymbol * aKey, OSObject * anObject);
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.
Result: true on success or false on a resource failure.
Name Description aKey The properties name as an OSSymbol. anObject The property value.
public:
virtual bool setProperty( const char * aKey, void * bytes, unsigned int length);
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 date and length, set in the property table with the given name, and released.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as a C-string. bytes The property's value as a pointer. OSData will copy this data. length The property's size in bytes, for OSData.
public:
virtual bool setProperty( const char * aKey, unsigned long long aValue, unsigned int aNumberOfBits);
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.
Result: true on success or false on a resource failure.
Name Description aKey The property's name as a C-string. aValue The property's numeric value. aNumberOfBits The property's size in bits, for OSNumber.
public:
virtual void setPropertyTable( OSDictionary * dict );
This method will release the current property table of a the entry and replace it with another, retaining the new property table.
Name Description dict The new dictionary to be used as the entry's property table.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)