Mac Developer Library

Developer

IOAudioControl Class Reference

Options
Deployment Target:

On This Page
Language:

IOAudioControl

Represents any controllable attribute of an IOAudioDevice. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.1 and later.
  • 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().

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

  • Declaration

    C++

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

    Import Statement

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

    Import Statement

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

    Import Statement

  • Returns the channel ID for the control.

    Declaration

    C++

    virtual UInt32 getChannelID();

    Import Statement

  • Returns the IOCommandGate for this IOAudioControl.

    Declaration

    C++

    virtual IOCommandGate *getCommandGate();

    Import Statement

  • Returns the control ID for the control.

    Declaration

    C++

    virtual UInt32 getControlID();

    Import Statement

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

    Import Statement

  • Returns the current value of the control.

    Declaration

    C++

    virtual OSObject *getValue();

    Import Statement

  • Returns the IOWorkLoop for the whole audio driver.

    Declaration

    C++

    virtual IOWorkLoop *getWorkLoop();

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Declaration

    C++

    virtual void setChannelID( UInt32 newChannelID);

    Import Statement

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

    Declaration

    C++

    virtual void setChannelName( const char *channelName);

    Import Statement

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

    Import Statement

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

    Import Statement

  • 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();

    Import Statement

  • Called at init time to set the control subType.

    Declaration

    C++

    virtual void setType( UInt32 type);

    Import Statement

  • Called at init time to set the control type.

    Declaration

    C++

    virtual void setSubType( UInt32 subType);

    Import Statement

  • Called at init time to set the control subType.

    Declaration

    C++

    virtual void setType( UInt32 type);

    Import Statement

  • Called at init time to set the control type.

    Declaration

    C++

    virtual void setSubType( UInt32 subType);

    Import Statement

  • Called at init time to set the control usage.

    Declaration

    C++

    virtual void setUsage( UInt32 usage);

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    Import Statement

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

    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;