ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IORegistryEntry

Inherits from:	OSObject
Declared In:	IORegistryEntry.h

Overview

The base class for all objects in the I/O Registry.

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.

Functions

attachToChild: Method called in the parent entry when a child attaches.
attachToParent: Attaches a entry to a parent entry in a plane.
childFromPath: Looks up a registry entry by relative path.
compareName: Compares the name of the entry with one name, and optionally returns the matching name.
compareNames: Compares the name of the entry with one or more names, and optionally returns the matching name.
copyChildEntry: Returns a registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.
copyLocation: Returns the location string assigned to the registry entry as an OSSymbol.
copyName: Returns the name assigned to the registry entry as an OSSymbol.
copyParentEntry: Returns a registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.
copyProperty(const char *): Synchronized method to obtain a property from a registry entry's property table.
copyProperty(const char *, const IORegistryPlane *, IOOptionBits): 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.
copyProperty(const OSString *): Synchronized method to obtain a property from a registry entry's property table.
copyProperty(const OSString *, const IORegistryPlane *, IOOptionBits): 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.
copyProperty(const OSSymbol *): Synchronized method to obtain a property from a registry entry's property table.
copyProperty(const OSSymbol *, const IORegistryPlane *, IOOptionBits): 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.
dealiasPath: Strips any aliases from the head of path and returns the full path.
detachAbove: Detaches an entry from all its parent entries in a plane.
detachAll: Detaches an entry and all its children recursively in a plane.
detachFromChild: Detaches a child entry from its parent in a plane.
detachFromParent: Detaches an entry from a parent entry in a plane.
dictionaryWithProperties: Synchronized method to obtain copy a registry entry's property table.
free: Standard free method for all IORegistryEntry subclasses.
fromPath: Looks up a registry entry by path.
getChildEntry: Returns a registry entry's first child entry in a plane.
getChildIterator: Returns an iterator over a registry entry's child entries in a plane.
getDepth: Counts the maximum number of entries between an entry and the registry root, in a plane.
getGenerationCount: Returns an generation count for all registry changing operations.
getLocation: Returns the location string assigned to the registry entry as a C string.
getName: Returns the name assigned to the registry entry as a C string.
getParentEntry: Returns a registry entry's first parent entry in a plane.
getParentIterator: Returns an iterator over a registry entry's parent entries in a specified plane.
getPath: Create a path for a registry entry.
getPathComponent: Create a path component for a registry entry.
getPlane: Looks up the plane object by a C string name.
getProperty(const char *): Synchronized method to obtain a property from a registry entry's property table.
getProperty(const char *, const IORegistryPlane *, IOOptionBits): Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
getProperty(const OSString *): Synchronized method to obtain a property from a registry entry's property table.
getProperty(const OSString *, const IORegistryPlane *, IOOptionBits): Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
getProperty(const OSSymbol *): Synchronized method to obtain a property from a registry entry's property table.
getProperty(const OSSymbol *, const IORegistryPlane *, IOOptionBits): Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
getPropertyTable: Unsynchronized accessor to a registry entry's property table.
getRegistryRoot: Returns a pointer to the root instance of the registry.
init: Standard init method for all IORegistryEntry subclasses.
inPlane: Determines whether a registry entry is attached in a plane.
isChild: Determines whether a registry entry is the child of another in a plane.
isParent: Determines whether a registry entry is the parent of another in a plane.
removeProperty: Synchronized method to remove a property from a registry entry's property table.
removeProperty(const OSString *): Synchronized method to remove a property from a registry entry's property table.
removeProperty(const OSSymbol *): Synchronized method to remove a property from a registry entry's property table.
runPropertyAction: Single thread a call to an action w.r.t. the property lock
serializeProperties: Synchronized method to serialize a registry entry's property table.
setLocation: Sets a location string for the registry entry, in a particular plane, or globally.
setName(const char *, const IORegistryPlane *): Sets a name for the registry entry, in a particular plane, or globally.
setName(const OSSymbol *, const IORegistryPlane *): Sets a name for the registry entry, in a particular plane, or globally.
setProperties: Optionally supported external method to set properties in a registry entry.
setProperty: Synchronized method to construct and add an OSData property to a registry entry's property table.
setProperty(const char *, bool): Synchronized method to construct and add an OSBoolean property to a registry entry's property table.
setProperty(const char *, const char *): Synchronized method to construct and add a OSString property to a registry entry's property table.
setProperty(const char *, OSObject *): Synchronized method to add a property to a registry entry's property table.
setProperty(const char *, unsigned long long, unsigned int): Synchronized method to construct and add an OSNumber property to a registry entry's property table.
setProperty(const OSString *, OSObject *): Synchronized method to add a property to a registry entry's property table.
setProperty(const OSSymbol *, OSObject *): Synchronized method to add a property to a registry entry's property table.
setPropertyTable: Replace a registry entry's property table.

attachToChild

Method called in the parent entry when a child attaches.

public

virtual bool attachToChild(
    IORegistryEntry *child, 
    const IORegistryPlane * plane );

Parameters

child: The registry entry being attached.
plane: The plane object.

Return Value

true on success, or false on a resource failure, or if the parent is the same as the child.

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.

attachToParent

Attaches a entry to a parent entry in a plane.

public

virtual bool attachToParent(
    IORegistryEntry *parent, 
    const IORegistryPlane * plane );

Parameters

parent: The registry entry to attach to.
plane: The plane object.

Return Value

true on success, or false on a resource failure, or if the parent is the same as the child.

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.

childFromPath

Looks up a registry entry by relative path.

public

virtual IORegistryEntry * childFromPath(
    const char * path, 
    const IORegistryPlane * plane = 0, 
    char *residualPath = 0, 
    int *residualLength = 0 );

Parameters

path: See fromPath.
plane: See fromPath.
residualPath: See fromPath.
residualLength: See fromPath.

Return Value

See fromPath.

Discussion

This function looks up a entry below the called entry by a relative path. It is just a convenience that calls fromPath with this as the fromEntry parameter.

compareName

Compares the name of the entry with one name, and optionally returns the matching name.

public

virtual bool compareName(
    OSString *name,
    OSString **matched = 0 ) const;

Parameters

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.

Return Value

True if the name compared true with the entry's global name.

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.

compareNames

Compares the name of the entry with one or more names, and optionally returns the matching name.

public

virtual bool compareNames(
    OSObject *name,
    OSString **matched = 0 ) const;

Parameters

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.

Return Value

True if one of the names compared true with the entry's global name.

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.

copyChildEntry

Returns a registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.

public

virtual IORegistryEntry * copyChildEntry(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

Discussion

This function will return the child which first attached to a registry entry.

copyLocation

Returns the location string assigned to the registry entry as an OSSymbol.

public

virtual const OSSymbol * copyLocation( const IORegistryPlane * plane = 0 ) const;

Parameters

plane: The plane object, or zero for the global name.

Return Value

A reference to an OSSymbol for the location if one exists, which should be released by the caller, or zero.

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.

copyName

Returns the name assigned to the registry entry as an OSSymbol.

public

virtual const OSSymbol * copyName( const IORegistryPlane * plane = 0 ) const;

Parameters

plane: The plane object, or zero for the global name.

Return Value

A reference to an OSSymbol for the name, which should be released by the caller.

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.

copyParentEntry

Returns a registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.

public

virtual IORegistryEntry * copyParentEntry(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

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.

copyProperty(const char *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * copyProperty(
    const char * aKey) const;

Parameters

aKey: The property's name as a C string.

Return Value

The property value found, or zero. It should be released by the caller.

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.

copyProperty(const char , const IORegistryPlane , IOOptionBits)

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.

public

virtual OSObject * copyProperty(
    const char * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as a C string.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero. A reference on any found property is returned to caller, which should be released.

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).

copyProperty(const OSString *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * copyProperty(
    const OSString * aKey) const;

Parameters

aKey: The property's name as an OSString.

Return Value

The property value found, or zero. It should be released by the caller.

Discussion

copyProperty(const OSString , const IORegistryPlane , IOOptionBits)

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.

public

virtual OSObject * copyProperty(
    const OSString * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as an OSString.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero. A reference on any found property is returned to caller, which should be released.

Discussion

copyProperty(const OSSymbol *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * copyProperty(
    const OSSymbol * aKey) const;

Parameters

aKey: The property's name as an OSSymbol.

Return Value

The property value found, or zero. It should be released by the caller.

Discussion

copyProperty(const OSSymbol , const IORegistryPlane , IOOptionBits)

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.

public

virtual OSObject * copyProperty(
    const OSSymbol * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as an OSSymbol.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero. A reference on any found property is returned to caller, which should be released.

Discussion

dealiasPath

Strips any aliases from the head of path and returns the full path.

public

static const char * dealiasPath( const char ** opath, const IORegistryPlane * plane );

Parameters

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.

Return Value

A C string pointer to the value of the alias if one is found, or zero if not.

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.

detachAbove

Detaches an entry from all its parent entries in a plane.

public

virtual void detachAbove(
    const IORegistryPlane * plane );

Parameters

plane: The plane object.

Discussion

This method calls detachFromParent in the entry for each of its parent entries in the plane.

detachAll

Detaches an entry and all its children recursively in a plane.

public

virtual void detachAll(
    const IORegistryPlane * plane );

Parameters

plane: The plane object.

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.

detachFromChild

Detaches a child entry from its parent in a plane.

public

virtual void detachFromChild(
    IORegistryEntry *child, 
    const IORegistryPlane * plane );

Parameters

parent: The registry entry to detach.
plane: The plane object.

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.

detachFromParent

Detaches an entry from a parent entry in a plane.

public

virtual void detachFromParent(
    IORegistryEntry *parent, 
    const IORegistryPlane * plane );

Parameters

parent: The registry entry to detach from.
plane: The plane object.

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.

dictionaryWithProperties

Synchronized method to obtain copy a registry entry's property table.

public

virtual OSDictionary * dictionaryWithProperties(
    void ) const;

Return Value

The created dictionary, or zero on a resource value. It should be released by the caller.

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.

free

Standard free method for all IORegistryEntry subclasses.

public

virtual void free(
    void );

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.

fromPath

Looks up a registry entry by path.

public

static IORegistryEntry * fromPath(
    const char * path, 
    const IORegistryPlane * plane = 0, 
    char *residualPath = 0, 
    int *residualLength = 0, 
    IORegistryEntry *fromEntry = 0 );

Parameters

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.

Return Value

A retained registry entry is returned on success, or zero on failure. The caller should release the entry.

Discussion

This function parses paths to lookup registry entries. The path may begin with the : 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.

getChildEntry

Returns a registry entry's first child entry in a plane.

public

virtual IORegistryEntry * getChildEntry(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

Discussion

This function will return the child which first attached to a registry entry.

getChildIterator

Returns an iterator over a registry entry's child entries in a plane.

public

virtual OSIterator * getChildIterator(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

Discussion

This method creates an iterator which will return each of a registry entry's child entries in a specified plane.

getDepth

Counts the maximum number of entries between an entry and the registry root, in a plane.

public

virtual unsigned int getDepth(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

The maximum number of entries between the entry and the root. Zero is returned if the entry is not attached in the plane.

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.

getGenerationCount

Returns an generation count for all registry changing operations.

public

static SInt32 getGenerationCount(
    void );

Return Value

An integer generation count.

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.

getLocation

Returns the location string assigned to the registry entry as a C string.

public

virtual const char * getLocation( const IORegistryPlane * plane = 
    0 ) const;

Parameters

plane: The plane object, or zero for the global name.

Return Value

A C string location string, valid while the entry is retained, or zero.

Discussion

getName

Returns the name assigned to the registry entry as a C string.

public

virtual const char * getName( const IORegistryPlane * plane = 
    0 ) const;

Parameters

plane: The plane object, or zero for the global name.

Return Value

A C string name, valid while the entry is retained.

Discussion

getParentEntry

Returns a registry entry's first parent entry in a plane.

public

virtual IORegistryEntry * getParentEntry(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

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.

getParentIterator

Returns an iterator over a registry entry's parent entries in a specified plane.

public

virtual OSIterator * getParentIterator(
    const IORegistryPlane * plane ) const;

Parameters

plane: The plane object.

Return Value

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.

getPath

Create a path for a registry entry.

public

virtual bool getPath(
    char *path,
    int *length, 
    const IORegistryPlane * plane) const;

Parameters

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.

Return Value

getPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path.

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.

getPathComponent

Create a path component for a registry entry.

public

virtual bool getPathComponent(
    char *path,
    int *length, 
    const IORegistryPlane * plane ) const;

Parameters

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.

Return Value

true if the path fits into the supplied buffer or false on a overflow.

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.

getPlane

Looks up the plane object by a C string name.

public

static const IORegistryPlane * getPlane( const char * name );

Return Value

A pointer to the plane object, or zero if no such plane exists. The returned plane should not be released.

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.

getProperty(const char *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * getProperty(
    const char * aKey) const;

Parameters

aKey: The property's name as a C string.

Return Value

The property value found, or zero.

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.

getProperty(const char , const IORegistryPlane , IOOptionBits)

Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.

public

virtual OSObject * getProperty(
    const char * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as a C string.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero.

Discussion

getProperty(const OSString *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * getProperty(
    const OSString * aKey) const;

Parameters

aKey: The property's name as an OSString.

Return Value

The property value found, or zero.

Discussion

getProperty(const OSString , const IORegistryPlane , IOOptionBits)

Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.

public

virtual OSObject * getProperty(
    const OSString * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as an OSString.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero.

Discussion

getProperty(const OSSymbol *)

Synchronized method to obtain a property from a registry entry's property table.

public

virtual OSObject * getProperty(
    const OSSymbol * aKey) const;

Parameters

aKey: The property's name as an OSSymbol.

Return Value

The property value found, or zero.

Discussion

getProperty(const OSSymbol , const IORegistryPlane , IOOptionBits)

Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.

public

virtual OSObject * getProperty(
    const OSSymbol * aKey, 
    const IORegistryPlane * plane, 
    IOOptionBits options = kIORegistryIterateRecursively | kIORegistryIterateParents) const;

Parameters

aKey: The property's name as an OSSymbol.
plane: The plane to iterate over, eg. gIOServicePlane.
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.

Return Value

The property value found, or zero.

Discussion

getPropertyTable

Unsynchronized accessor to a registry entry's property table.

public

OSDictionary * getPropertyTable(
    void ) const;

Return Value

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.

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.

getRegistryRoot

Returns a pointer to the root instance of the registry.

public

static IORegistryEntry * getRegistryRoot(
    void );

Return Value

A pointer to the IORegistryEntry root instance. It should not be released by the caller.

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.

init

Standard init method for all IORegistryEntry subclasses.

public

virtual bool init(
    OSDictionary *dictionary = 0 );

Parameters

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.

Return Value

true on success, or false on a resource failure.

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.

inPlane

Determines whether a registry entry is attached in a plane.

public

virtual bool inPlane(
    const IORegistryPlane * plane = 0) const;

Parameters

plane: The plane object, 0 indicates any plane.

Return Value

If the entry has a parent in the given plane or if plane = 0 then if entry has any parent; return true, otherwise false.

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.

isChild

Determines whether a registry entry is the child of another in a plane.

public

virtual bool isChild(
    IORegistryEntry *child, 
    const IORegistryPlane * plane, 
    bool onlyChild = false ) const;

Parameters

child: The possible child registry entry.
plane: The plane object.
onlyChild: If true, check also if the child is the only child.

Return Value

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.

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.

isParent

Determines whether a registry entry is the parent of another in a plane.

public

virtual bool isParent(
    IORegistryEntry *parent, 
    const IORegistryPlane * plane, 
    bool onlyParent = false ) const;

Parameters

parent: The possible parent registry entry.
plane: The plane object.
onlyParent: If true, check also if the parent is the only parent.

Return Value

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.

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.

removeProperty

Synchronized method to remove a property from a registry entry's property table.

public

virtual void removeProperty(
    const char * aKey);

Parameters

aKey: The property's name as a C string.

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.

removeProperty(const OSString *)

Synchronized method to remove a property from a registry entry's property table.

public

virtual void removeProperty(
    const OSString * aKey);

Parameters

aKey: The property's name as an OSString.

Discussion

removeProperty(const OSSymbol *)

Synchronized method to remove a property from a registry entry's property table.

public

virtual void removeProperty(
    const OSSymbol * aKey);

Parameters

aKey: The property's name as an OSSymbol.

Discussion

runPropertyAction

Single thread a call to an action w.r.t. the property lock

public

virtual IOReturn runPropertyAction(
    Action action,
    OSObject *target, 
    void *arg0 = 0,
    void *arg1 = 0, 
    void *arg2 = 0,
    void *arg3 = 0);

Parameters

action: Pointer to function to be executed in work-loop context.
arg0: Parameter for action parameter, defaults to 0.
arg1: Parameter for action parameter, defaults to 0.
arg2: Parameter for action parameter, defaults to 0.
arg3: Parameter for action parameter, defaults to 0.

Return Value

Returns the value of the Action callout.

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

serializeProperties

Synchronized method to serialize a registry entry's property table.

public

virtual bool serializeProperties(
    OSSerialize *serialize ) const;

Parameters

serialize: The OSSerialize instance representing the serialization request.

Return Value

True on success, false otherwise.

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.

setLocation

Sets a location string for the registry entry, in a particular plane, or globally.

public

virtual void setLocation(
    const OSSymbol * location, 
    const IORegistryPlane * plane = 0 );

Parameters

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.

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.

setName(const char , const IORegistryPlane )

Sets a name for the registry entry, in a particular plane, or globally.

public

virtual void setName(
    const char * name, 
    const IORegistryPlane * plane = 0 );

Parameters

name: A const C string name which will be copied.
plane: The plane object, or zero to set the global name.

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.

setName(const OSSymbol , const IORegistryPlane )

Sets a name for the registry entry, in a particular plane, or globally.

public

virtual void setName(
    const OSSymbol * name, 
    const IORegistryPlane * plane = 0 );

Parameters

name: An OSSymbol which will be retained.
plane: The plane object, or zero to set the global name.

Discussion

setProperties

Optionally supported external method to set properties in a registry entry.

public

virtual IOReturn setProperties(
    OSObject *properties );

Parameters

properties: Any OSObject subclass, to be interpreted by the implementing method - for example an OSDictionary, OSData etc. may all be appropriate.

Return Value

An IOReturn code to be returned to the caller.

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.

setProperty

Synchronized method to construct and add an OSData property to a registry entry's property table.

public

virtual bool setProperty(
    const char * aKey, 
    void * bytes, 
    unsigned int length);

Parameters

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.

Return Value

true on success or false on a resource failure.

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.

setProperty(const char *, bool)

Synchronized method to construct and add an OSBoolean property to a registry entry's property table.

public

virtual bool setProperty(
    const char * aKey,
    bool aBoolean);

Parameters

aKey: The property's name as a C string.
aBoolean: The property's boolean value.

Return Value

true on success or false on a resource failure.

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.

setProperty(const char , const char )

Synchronized method to construct and add a OSString property to a registry entry's property table.

public

virtual bool setProperty(
    const char * aKey,
    const char * aString);

Parameters

aKey: The property's name as a C string.
aString: The property value as a C string.

Return Value

true on success or false on a resource failure.

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.

setProperty(const char , OSObject )

Synchronized method to add a property to a registry entry's property table.

public

virtual bool setProperty(
    const char * aKey,
    OSObject * anObject);

Parameters

aKey: The property's name as a C string.
anObject: The property value.

Return Value

true on success or false on a resource failure.

Discussion

setProperty(const char *, unsigned long long, unsigned int)

Synchronized method to construct and add an OSNumber property to a registry entry's property table.

public

virtual bool setProperty(
    const char * aKey, 
    unsigned long long aValue, 
    unsigned int aNumberOfBits);

Parameters

aKey: The property's name as a C string.
aValue: The property's numeric value.
aNumberOfBits: The property's size in bits, for OSNumber.

Return Value

true on success or false on a resource failure.

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.

setProperty(const OSString , OSObject )

Synchronized method to add a property to a registry entry's property table.

public

virtual bool setProperty(
    const OSString * aKey,
    OSObject * anObject);

Parameters

aKey: The property's name as an OSString.
anObject: The property value.

Return Value

true on success or false on a resource failure.

Discussion

setProperty(const OSSymbol , OSObject )

Synchronized method to add a property to a registry entry's property table.

public

virtual bool setProperty(
    const OSSymbol * aKey,
    OSObject * anObject);

Parameters

aKey: The properties name as an OSSymbol.
anObject: The property value.

Return Value

true on success or false on a resource failure.

Discussion

setPropertyTable

Replace a registry entry's property table.

public

virtual void setPropertyTable(
    OSDictionary *dict );

Parameters

dict: The new dictionary to be used as the entry's property table.

Discussion

This method will release the current property table of a the entry and replace it with another, retaining the new property table.

Typedefs

Action

public

typedef IOReturn ( *Action)(
    OSObject *target, 
    void *arg0,
    void *arg1, 
    void *arg2,
    void *arg3);

Fields

target: Target of the function, can be used as a refcon. Note if a C++ function was specified, this parameter is implicitly the first parameter in the target member function's parameter list.
arg0: Argument to action from run operation.
arg1: Argument to action from run operation.
arg2: Argument to action from run operation.
arg3: Argument to action from run operation.

Discussion

Type and arguments of callout C function that is used when a runCommand is executed by a client. Cast to this type when you want a C++ member function to be used. Note the arg1 - arg3 parameters are passed straight pass through to the action callout.

Structs and Unions

ExpansionData

protected

struct ExpansionData;

Discussion

This structure will be used to expand the capablilties of this class in the future.

Member Data

reserved

protected

ExpansionData * reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19