IOAudioControl

Inherits from
IOService
Availability
Available in OS X v10.1 and later.
Declared in
IOAudioControl.h

Overview

Represents any controllable attribute of an IOAudioDevice.

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: 'kIOAudioControl<attribute name>Key'. 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.

Tasks

Miscellaneous

Instance Methods

addUserClient

Called on the IOWorkLoop to add a new IOAudioControlUserClient.

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.

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.

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.

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

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.

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

Creates a new IOAudioControlUserClient instance.

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

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

flushValue

Forces the control to be flushed out to the hardware.

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.

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.

virtual UInt32 getChannelID();

getCommandGate

Returns the IOCommandGate for this IOAudioControl.

virtual IOCommandGate *getCommandGate();

getControlID

Returns the control ID for the control.

virtual UInt32 getControlID();

getIsStarted

Returns true after start() has been called.

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.

virtual OSObject *getValue();

getWorkLoop

Returns the IOWorkLoop for the whole audio driver.

virtual IOWorkLoop *getWorkLoop();

hardwareValueChanged

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

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.

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.

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.

properties

A dictionary of additional properties for the connection.

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. A derived class that requires overriding of newUserClient 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.

performValueChange

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

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.

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.

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.

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.

virtual void setChannelID( UInt32 newChannelID);

setChannelName

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

virtual void setChannelName( const char *channelName);

setControlID

Sets the controlID for this control.

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.

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.

virtual void setReadOnlyFlag();

setSubType(UInt32)

Called at init time to set the control subType.

virtual void setType( UInt32 type);

setSubType(UInt32)

Called at init time to set the control type.

virtual void setSubType( UInt32 subType);

setType(UInt32)

Called at init time to set the control subType.

virtual void setType( UInt32 type);

setType(UInt32)

Called at init time to set the control type.

virtual void setSubType( UInt32 subType);

setUsage

Called at init time to set the control usage.

virtual void setUsage( UInt32 usage);

setValue

Sets the value for this control.

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.

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.

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.

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.

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.

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.

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.

Callbacks

IntValueChangeHandler

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

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

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

Availability
Declared In
IOAudioControl.h

Instance Variables

channelID

UInt32 channelID;

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

clients

OSSet *userClients;

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

See Also

commandGate

IOCommandGate *commandGate;

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

controlID

UInt32 controlID;

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

isStarted

bool isStarted;

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

userClients

OSSet *userClients;

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

See Also

workLoop

IOWorkLoop *workLoop;

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