Mac Developer Library

Developer

IOAudioControl Class Reference

Options
Deployment Target:

On This Page
Language:

IOAudioControl

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.1 and later.

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.

  • Called on the IOWorkLoop to add a new IOAudioControlUserClient.

    Declaration

    C++

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

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual void clientClosed( IOAudioControlUserClient *client);

    Parameters

    client

    The user client object that has disconnected.

  • Creates a new IOAudioControlUserClient instance.

    Declaration

    C++

    virtual IOReturn createUserClient( task_ttask, void *securityID, UInt32type, 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.

  • Creates a new IOAudioControlUserClient instance.

    Declaration

    C++

    virtual IOReturn createUserClient( task_ttask, void *securityID, UInt32type, 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.

  • Declaration

    C++

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

  • Forces the control to be flushed out to the hardware.

    Declaration

    C++

    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.

  • Frees all of the resources allocated by the IOAudioControl.

    Declaration

    C++

    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.

  • Returns the channel ID for the control.

    Declaration

    C++

    virtual UInt32 getChannelID();

  • Returns the IOCommandGate for this IOAudioControl.

    Declaration

    C++

    virtual IOCommandGate *getCommandGate();

  • Returns the control ID for the control.

    Declaration

    C++

    virtual UInt32 getControlID();

  • Returns true after start() has been called.

    Declaration

    C++

    virtual bool getIsStarted();

    Discussion

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

  • Returns the current value of the control.

    Declaration

    C++

    virtual OSObject *getValue();

  • Returns the IOWorkLoop for the whole audio driver.

    Declaration

    C++

    virtual IOWorkLoop *getWorkLoop();

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

    Declaration

    C++

    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.

  • Initializes a newly allocated IOAudioControl with the given attributes.

    Declaration

    C++

    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.

  • Creates a new user client object for this IOAudioControl instance.

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IOReturn performValueChange( OSObject *newValue);

    Return Value

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

  • Called on the IOWorkLoop to remove an IOAudioControlUserClient.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Called when the value has changed for the control.

    Declaration

    C++

    virtual void sendValueChangeNotification();

    Discussion

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

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

    Declaration

    C++

    virtual void setChannelID( UInt32 newChannelID);

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

    Declaration

    C++

    virtual void setChannelName( const char *channelName);

  • Sets the controlID for this control.

    Declaration

    C++

    virtual void setControlID( UInt32cntrlID);

    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.

  • Changes a property of this IOService.

    Declaration

    C++

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

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

    Declaration

    C++

    virtual void setReadOnlyFlag();

  • Called at init time to set the control subType.

    Declaration

    C++

    virtual void setType( UInt32 type);

  • Called at init time to set the control type.

    Declaration

    C++

    virtual void setSubType( UInt32 subType);

  • Called at init time to set the control subType.

    Declaration

    C++

    virtual void setType( UInt32 type);

  • Called at init time to set the control type.

    Declaration

    C++

    virtual void setSubType( UInt32 subType);

  • Called at init time to set the control usage.

    Declaration

    C++

    virtual void setUsage( UInt32 usage);

  • Sets the value for this control.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Starts a newly created IOAudioControl.

    Declaration

    C++

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

  • Stops the control when the provider is going away.

    Declaration

    C++

    virtual void stop( IOService *provider);

    Parameters

    provider

    The IOAudioPort or IOAudioEngine that owns this control.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IOReturn validateValue( OSObject *newValue);

    Parameters

    newValue

    The new value to be verified.

    Return Value

    Returns kIOReturnSuccess if the value is valid.

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

    Declaration

    C++

    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

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

    Declaration

    C++

    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.

    Import Statement

    Objective-C

    #include <IOAudioControl.h>;

    Availability

    Available in OS X v10.1 through OS X v10.5.

Instance Variables

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

    Declaration

    C++

    IOWorkLoop *workLoop;

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

    Declaration

    C++

    OSSet *userClients;

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

    Declaration

    C++

    bool isStarted;

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

    Declaration

    C++

    UInt32 controlID;

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

    Declaration

    C++

    IOCommandGate *commandGate;

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

    Declaration

    C++

    OSSet *userClients;

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

    Declaration

    C++

    UInt32 channelID;