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

IOAudioControl

Inherits from:	IOService
Declared In:	IOAudioControl.h

Overview

Represents any controllable attribute of an IOAudioDevice.

Discussion

An IOAudioControl instance may belong to one IOAudioPort. Additionally, it may associated with an IOAudioEngine as a default control for that IOAudioEngine.

When its value changes, it sends a notification to the CoreAudio.framework (HAL). It also makes a call to the ValueChangeHandler.

The base IOAudioControl class contains a type, a value and a channel ID representing the channel(s) which the control acts on. It may also contain a readable format for the name of the channel as well as a control ID that can be used to identify unique controls. Additionally it may contain a subType and a usage. Each type has its own set of possible subTypes. There currently four different control types defined: kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector. Each one is represented by a subclass of IOAudioControl: IOAudioLevelControl, IOAudioToggleControl, IOAudioSelectorControl. The level control defines a range of allowed values and has a defined subtype of kIOAudioLevelControlSubTypeVolume used to define a volume control. The toggle control allows for a boolean value and has a defined subtype kIOAudioToggleControlSubTypeMute for a mute control. The selector control has a list of allowed selections with a value and description for each allowed selection and has the following sub types: kIOAudioSelectorControlSubTypeOutput for an output selector and kIOAudioSelectorControlSubTypeInput for an input selector. See the subclass documentation for a more complete description of each

There are enums for default channel ID values and common channel names in IOAudioTypes.h. The channel ID values are prefixed with 'kIOAudioControlChannelID' and the common channel names are prefixed with 'kIOAudioControlChannelName'. All of the attributes of the IOAudioControl are stored in the registry. The key used for each attribute is defined in IOAudioTypes.h with the define matching the following pattern: 'kIOAudioControlKey'. For example: kIOAudioControlChannelIDKey.

In addition to the existing defined control types, drivers can define their own as well for other purposes.

Changes to the IOAudioControl's value made by the CoreAudio.framework are done through the IORegistry. When the CoreAudio.framework initiates a value change, the control receives a setProperties() message. The setProperties() implementation looks for the property 'IOAudioControlValue' and if present, calls setValue() on the driver's IOWorkLoop with the new value. The setValue() function first checks to see if the new value is different. If so, it calls performValueChange() to call through to the driver to make the change in the hardware. If that call succeeds the value is changed and the new value is set in the registry. Additionally notifications are sent to all clients that have registered for them.

Functions

addUserClient: Called on the IOWorkLoop to add a new IOAudioControlUserClient.
addUserClientAction: IOCommandGate Action which calls addUserClient() while holding the IOCommandGate.
clientClosed: Called automatically by the IOAudioControlUserClient when a user client closes its connection to the control.
createUserClient(task_t, void *, UInt32, IOAudioControlUserClient **): Creates a new IOAudioControlUserClient instance.
createUserClient(task_t, void *, UInt32, IOAudioControlUserClient **, OSDictionary *): Creates a new IOAudioControlUserClient instance.
detachUserClientsAction
flushValue: Forces the control to be flushed out to the hardware.
free: Frees all of the resources allocated by the IOAudioControl.
getChannelID: Returns the channel ID for the control.
getCommandGate: Returns the IOCommandGate for this IOAudioControl.
getControlID: Returns the control ID for the control.
getIsStarted: Returns true after start() has been called.
getValue: Returns the current value of the control.
getWorkLoop: Returns the IOWorkLoop for the whole audio driver.
hardwareValueChanged: Updates the value for this control and sends out the value changed notification.
init: Initializes a newly allocated IOAudioControl with the given attributes.
newUserClient: Creates a new user client object for this IOAudioControl instance.
performValueChange: Called by setValue() to make the call to the valueChangeHandler to update the hardware.
removeUserClient: Called on the IOWorkLoop to remove an IOAudioControlUserClient.
removeUserClientAction: IOCommandGate Action which calls removeUserClient() while holding the IOCommandGate.
sendValueChangeNotification: Called when the value has changed for the control.
setChannelID: Called at init time to set the channel ID for this IOAudioControl.
setChannelName: Called at init time to set the channel name for this IOAudioControl.
setControlID: Sets the controlID for this control.
setProperties: Changes a property of this IOService.
setReadOnlyFlag: Call this function to say that a control is read only. This call cannot be undone, so if a control is only temporarily unsetable, do not use this call but instead return an error from the control handler.
setSubType(UInt32): Called at init time to set the control subType.
setSubType(UInt32): Called at init time to set the control type.
setType(UInt32): Called at init time to set the control subType.
setType(UInt32): Called at init time to set the control type.
setUsage: Called at init time to set the control usage.
setValue: Sets the value for this control.
setValueAction: IOCommandGate Action which calls setValue() while holding the IOCommandGate.
start: Starts a newly created IOAudioControl.
stop: Stops the control when the provider is going away.
updateValue: Called by setValue() in order to update the value and the registry.
validateValue: Called by setValue() to verify that the value is valid.
withAttributes: Static function that allocates a new IOAudioControl with the given attributes.

addUserClient

Called on the IOWorkLoop to add a new IOAudioControlUserClient.

protected

virtual IOReturn addUserClient(
    IOAudioControlUserClient *newUserClient);

Parameters

newUserClient: The IOAudioControlUserClientto be added.

Return Value

Returns kIOReturnSuccess on success.

Discussion

There is no need to call this directly. It is called on the workLoop by newUserClient() through addUserClientAction().

addUserClientAction

IOCommandGate Action which calls addUserClient() while holding the IOCommandGate.

protected

static IOReturn addUserClientAction(
    OSObject *owner,
    void *arg1,
    void *arg2,
    void *arg3,
    void *arg4);

Parameters

owner: The owner of the IOCommandGate (the IOAudioControl in this case).
arg1: The IOAudioControlUserClient to be added.

Return Value

Returns the result of addUserClient() - kIOReturnSuccess on success.

Discussion

This is needed to allow addUserClient() to be called on the IOWorkLoop.

clientClosed

Called automatically by the IOAudioControlUserClient when a user client closes its connection to the control.

public

virtual void clientClosed(
    IOAudioControlUserClient *client);

Parameters

client: The user client object that has disconnected.

createUserClient(task_t, void *, UInt32, IOAudioControlUserClient **)

Creates a new IOAudioControlUserClient instance.

public

virtual IOReturn createUserClient(
    task_t task,
    void *securityID,
    UInt32 type,
    IOAudioControlUserClient **newUserClient);

Parameters

task: The task requesting the new user client.
securityID: Optional security paramater passed in by the client - ignored.
type: Optional user client type passed in by the client.
newUserClient: The IOAudioControlUserClient * must be stored in this param on a successful completion.

Return Value

Returns kIOReturnSuccess on success.

Discussion

createUserClient(task_t, void *, UInt32, IOAudioControlUserClient **, OSDictionary *)

Creates a new IOAudioControlUserClient instance.

public

virtual IOReturn createUserClient(
    task_t task,
    void *securityID,
    UInt32 type,
    IOAudioControlUserClient **newUserClient,
    OSDictionary *properties);

Parameters

task: The task requesting the new user client.
securityID: Optional security paramater passed in by the client - ignored.
type: Optional user client type passed in by the client.
newUserClient: The IOAudioControlUserClient * must be stored in this param on a successful completion.
properties: A dictionary of additional properties for the connection.

Return Value

Returns kIOReturnSuccess on success.

Discussion

This function is called by newUserClient() to create a new IOAudioControlUserClient instance. This function may be overridden by subclasses that need to add functionality to the IOAudioControlUserClient. In that case, they must subclass IOAudioControlUserClient and return a new, initialized instance of that subclass. A derived class that requires overriding of createUserClient should override the version with the properties parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive can be used to select between the two behaviors.

detachUserClientsAction

protected

static IOReturn detachUserClientsAction(
    OSObject *owner,
    void *arg1,
    void *arg2,
    void *arg3,
    void *arg4);

flushValue

Forces the control to be flushed out to the hardware.

public

virtual IOReturn flushValue();

Return Value

Returns the result of performValueChange() - kIOReturnSuccess on success.

Discussion

This function calls performValueChange() directly with the current value of the IOAudioControl.

free

Frees all of the resources allocated by the IOAudioControl.

public

virtual void free();

Discussion

Do not call this directly. This is called automatically by the system when the instance's refcount goes to 0. To decrement the refcount, call release() on the object.

getChannelID

Returns the channel ID for the control.

public

virtual UInt32 getChannelID();

getCommandGate

Returns the IOCommandGate for this IOAudioControl.

public

virtual IOCommandGate *getCommandGate();

getControlID

Returns the control ID for the control.

public

virtual UInt32 getControlID();

getIsStarted

Returns true after start() has been called.

public

virtual bool getIsStarted();

Discussion

Used by IOAudioPort and IOAudioEngine to decide if the control needs to be started.

getValue

Returns the current value of the control.

public

virtual OSObject *getValue();

getWorkLoop

Returns the IOWorkLoop for the whole audio driver.

public

virtual IOWorkLoop *getWorkLoop();

hardwareValueChanged

Updates the value for this control and sends out the value changed notification.

public

virtual IOReturn hardwareValueChanged(
    OSObject *newValue);

Parameters

newValue: The new value for this control.

Return Value

Returns kIOReturnSuccess if the value is successfully updated.

Discussion

This is designed to be called by the driver when it detects that the hardware's value has changed without driver intervention (e.g. when an external event causes the change). The difference between hardwareValueChanged() and setValue() is that hardwareValueChanged() doesn't call performValueChange() which sends a message back to the driver to cause it to change the hardware with the new value. This function must be called on the IOWorkLoop.

init

Initializes a newly allocated IOAudioControl with the given attributes.

public

virtual bool init(
    UInt32 type, 
    OSObject *initialValue, 
    UInt32 channelID, 
    const char *channelName = 0, 
    UInt32 cntrlID = 0, 
    UInt32 subType = 0, 
    UInt32 usage = 0, 
    OSDictionary *properties = 0);

Parameters

type: The type of the control. Common, known types are defined in IOAudioTypes.h. They currently consist of kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector.
channelID: The ID of the channel(s) that the control acts on. Common IDs are located in IOAudioTypes.h.
channelName: An optional name for the channel. Common names are located in IOAudioDefines.h. Any name not defined in IOAudioDefines.h must be localized in order to be properly displayed in multiple languages.
cntrlID: An optional ID for the control that can be used to uniquely identify controls
subType: An optional subType specific to the given type
usage: An optional value specifying how the control will be used. Currently defined usages are kIOAudioControlUsageInput, kIOAudioControlUsageOutput and kIOAudioControlUsagePassThru. This value is used when a control is set as a default control on an IOAudioEngine.
properties: Standard property list passed to the init() function of any new IOService. This dictionary gets stored in the registry entry for this instance.

Return Value

Returns true on success.

newUserClient

Creates a new user client object for this IOAudioControl instance.

public

virtual IOReturn newUserClient(
    task_t task,
    void *securityID,
    UInt32 type,
    IOUserClient **handler);

Parameters

task: The task requesting the new user client.
securityID: Optional security paramater passed in by the client - ignored.
type: Optional user client type passed in by the client - 0 for the default user client type.
handler: The new IOUserClient * must be stored in this param on a successful completion.

Return Value

Returns kIOReturnSuccess on success. May also result kIOReturnError or kIOReturnNoMemory.

Discussion

This is called automatically by I/O Kit when a user process opens a connection to this IOAudioControl. This is typically done when the user process needs to register for value change notifications. This implementation allocates a new IOAudioControlUserClient object. There is no need to call this directly.

performValueChange

Called by setValue() to make the call to the valueChangeHandler to update the hardware.

protected

virtual IOReturn performValueChange(
    OSObject *newValue);

Return Value

Returns the result of the handler call (or kIOReturnError on an error).

removeUserClient

Called on the IOWorkLoop to remove an IOAudioControlUserClient.

protected

virtual IOReturn removeUserClient(
    IOAudioControlUserClient *userClient);

Parameters

userClient: The IOAudioControlUserClient to be removed.

Return Value

Returns kIOReturnSuccess on success.

Discussion

This is called on the IOWorkLoop by clientClosed() through removeUserClientAction() when the user client is going away. It should not be called directly.

removeUserClientAction

IOCommandGate Action which calls removeUserClient() while holding the IOCommandGate.

protected

static IOReturn removeUserClientAction(
    OSObject *owner,
    void *arg1,
    void *arg2,
    void *arg3,
    void *arg4);

Parameters

owner: The owner of the IOCommandGate (the IOAudioControl in this case).
arg1: The IOAudioControlUserClient to be removed.

Return Value

Returns the result of removeUserClient() - kIOReturnSuccess on success.

Discussion

This is needed to allow removeUserClient() to be called on the IOWorkLoop.

sendValueChangeNotification

Called when the value has changed for the control.

protected

virtual void sendValueChangeNotification();

Discussion

This function sends out the value change notification to the user clients.

setChannelID

Called at init time to set the channel ID for this IOAudioControl.

protected

virtual void setChannelID(
    UInt32 newChannelID);

setChannelName

Called at init time to set the channel name for this IOAudioControl.

protected

virtual void setChannelName(
    const char *channelName);

setControlID

Sets the controlID for this control.

protected

virtual void setControlID(
    UInt32 cntrlID);

Parameters

cntrlID: The control ID for the control.

Discussion

The control ID is an optional attribute that can be used to track IOAudioControls. A typical use is for the IOAudioDevice to assign a unique controlID to each control that it creates and then do a switch statement on the id of the control when it gets an audioControlValueChanged() notification. Typically the control ID is set when the object is created and doesn't need to be called again.

setProperties

Changes a property of this IOService.

public

virtual IOReturn setProperties(
    OSObject *properties);

Parameters

properties: An OSDictionary containing the properties to change.

Return Value

Returns kIOReturnSuccess on success.

Discussion

This is called when the user client changes a property of this IOAudioControl. In this case it is used to change the value. This function looks for that property and then calls setValue() through the IOCommandGate and setValueAction().

setReadOnlyFlag

Call this function to say that a control is read only. This call cannot be undone, so if a control is only temporarily unsetable, do not use this call but instead return an error from the control handler.

public

virtual void setReadOnlyFlag();

setSubType(UInt32)

Called at init time to set the control subType.

protected

virtual void setType(
    UInt32 type);

setSubType(UInt32)

Called at init time to set the control type.

protected

virtual void setSubType(
    UInt32 subType);

setType(UInt32)

Called at init time to set the control subType.

protected

virtual void setType(
    UInt32 type);

setType(UInt32)

Called at init time to set the control type.

protected

virtual void setSubType(
    UInt32 subType);

setUsage

Called at init time to set the control usage.

protected

virtual void setUsage(
    UInt32 usage);

setValue

Sets the value for this control.

public

virtual IOReturn setValue(
    OSObject *newValue);

Parameters

newValue: The new value for this control.

Return Value

Returns kIOReturnSuccess if the value is successfully set.

Discussion

When the control's value is changed, a call is made to performValueChange(). If that call succeeds, the value is set and sendValueChangeNotification() is called to send a notification to the user clients. This function must be called on the IOWorkLoop.

setValueAction

IOCommandGate Action which calls setValue() while holding the IOCommandGate.

public

static IOReturn setValueAction(
    OSObject *owner,
    void *arg1,
    void *arg2,
    void *arg3,
    void *arg4);

Parameters

owner: The owner of the IOCommandGate (the IOAudioControl in this case).
arg1: The new value for the IOAudioControl.

Return Value

Returns the result of setValue() - kIOReturnSuccess on success.

Discussion

This is needed to allow setValue() to be called on the IOWorkLoop.

start

Starts a newly created IOAudioControl.

public

virtual bool start(
    IOService *provider);

Parameters

provider: The IOAudioPort or IOAudioEngine that owns this control.

Return Value

Returns true on success.

Discussion

This is called automatically by IOAudioPort when addAudioControl() is called or by IOAudioEngine when addDefaultAudioControl() is called. It will only be called by the first call to either addAudioControl() or addDefaultAudioControl().

stop

Stops the control when the provider is going away.

public

virtual void stop(
    IOService *provider);

Parameters

provider: The IOAudioPort or IOAudioEngine that owns this control.

updateValue

Called by setValue() in order to update the value and the registry.

protected

virtual IOReturn updateValue(
    OSObject *newValue);

Parameters

newValue: The new value to b updated.

Return Value

Returns kIOReturnSuccess if the value is successfully updated.

Discussion

It also calls sendValueChangedNotification() to send notifications to the user clients.

validateValue

Called by setValue() to verify that the value is valid.

protected

virtual IOReturn validateValue(
    OSObject *newValue);

Parameters

newValue: The new value to be verified.

Return Value

Returns kIOReturnSuccess if the value is valid.

withAttributes

Static function that allocates a new IOAudioControl with the given attributes.

public

static IOAudioControl *withAttributes(
    UInt32 type, 
    OSObject *initialValue, 
    UInt32 channelID, 
    const char *channelName = 0, 
    UInt32 cntrlID = 0, 
    UInt32 subType = 0, 
    UInt32 usage = 0);

Parameters

type: The type of the control. Common, known types are defined in IOAudioTypes.h. They currently consist of kIOAudioControlTypeLevel, kIOAudioControlTypeToggle, kIOAudioControlTypeSelector.
channelID: The ID of the channel(s) that the control acts on. Common IDs are located in IOAudioTypes.h.
channelName: An optional name for the channel. Common names are located in IOAudioDefines.h. Any name not defined in IOAudioDefines.h must be localized in order to be properly displayed in multiple languages.
cntrlID: An optional ID for the control that can be used to uniquely identify controls
subType: An optional subType specific to the given type
usage: An optional value specifying how the control will be used. Currently defined usages are kIOAudioControlUsageInput, kIOAudioControlUsageOutput and kIOAudioControlUsagePassThru. This value is used when a control is set as a default control on an IOAudioEngine.

Return Value

Returns a newly allocated and initialized IOAudioControl.

Typedefs

IntValueChangeHandler

Handler function used to make a notification when a value is to be changed.

public

typedef IOReturn ( *IntValueChangeHandler)(
    OSObject *target,
    IOAudioControl *audioControl,
    SInt32 oldValue,
    SInt32 newValue);

Fields

target: Reference supplied when the handler was registered.
audioControl: The IOAudioControl that is changing.
oldValue: The old value of the control.
newValue: The new value the control is being changed to.

Return Value

Must return kIOReturnSuccess when the hardware is successfully updated.

Member Data

channelID

protected

UInt32 channelID;

Discussion

The ID of the channel this control affects - may be kIOAudioControlChannelIDAll if it represents all channels.

clients

See Also:

userClients

protected

OSSet *userClients;

Discussion

A list of user clients that have requested value change notifications.

commandGate

protected

IOCommandGate *commandGate;

Discussion

The IOCommandGate for this control - attached to the driver's IOWorkLoop.

controlID

protected

UInt32 controlID;

Discussion

An optional identifier that can be used to identify the control.

isStarted

protected

bool isStarted;

Discussion

Internal state keeping track of when the IOAudioControl has been started.

userClients

See Also:

clients

protected

OSSet *userClients;

Discussion

A list of user clients that have requested value change notifications.

workLoop

protected

IOWorkLoop *workLoop;

Discussion

The IOWorkLoop for the audio driver - shared from the IOAudioDevice.

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