ADC Home > Reference Library > Reference > Audio > Core Audio > Core Audio Framework Reference

 

AudioDriverPlugIn

Includes:

Introduction

IOAudio family drivers can specify a CFBundle in order to implement device specific properties on behalf of the HAL. The CFBundle provides routines for opening and closing the device as well as the property management routines. The mechanism by which the driver specifies which CFBundle to load is defined by the IOAudio driver family in IOKit. The routines described in this header are loaded by name from the CFBundle.


Functions

AudioDriverPlugInClose
Closes an instance of the driver plug-in.
AudioDriverPlugInDeviceGetProperty
Queries an the AudioDevice object to get the data of the given property and places it in the provided buffer.
AudioDriverPlugInDeviceGetPropertyInfo
Retrieve information about the given property of an AudioDevice.
AudioDriverPlugInDeviceSetProperty
Tells the AudioDevice object to change the value of the given property using the provided data.
AudioDriverPlugInOpen
Instantiates a new instance of the driver plug-in.
AudioDriverPlugInStreamGetProperty
Queries an the AudioStream object to get the data of the given property and places it in the provided buffer.
AudioDriverPlugInStreamGetPropertyInfo
Retrieve information about the given property of an AudioStream.
AudioDriverPlugInStreamSetProperty
Tells the AudioStream object to change the value of the given property using the provided data.

AudioDriverPlugInClose

Closes an instance of the driver plug-in. 

extern OSStatus AudioDriverPlugInClose(
    AudioDeviceID inDevice);
Parameters
inDevice
The AudioDeviceID that describes the device who's plug-in instance is being closed.
Return Value

An OSStatus indicating success or failure.

AudioDriverPlugInDeviceGetProperty

Queries an the AudioDevice object to get the data of the given property and places it in the provided buffer. 

extern OSStatus AudioDriverPlugInDeviceGetProperty(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);
Parameters
inDevice
The AudioDevice to query.
inChannel
The channel of the property to query where 0 is the master channel.
isInput
Which section of the AudioDevice to query.
inPropertyID
The AudioDevicePropertyID of the property to query.
ioPropertyDataSize
A UInt32 which on entry indicates the size of the buffer pointed to by outData and on exit indicates how much of the buffer was used.
outPropertyData
The buffer into which the object will put the data for the given property.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

AudioDriverPlugInDeviceGetPropertyInfo

Retrieve information about the given property of an AudioDevice. 

extern OSStatus AudioDriverPlugInDeviceGetPropertyInfo(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);
Parameters
inDevice
The AudioDevice to query.
inChannel
The channel of the property to query where 0 is the master channel.
isInput
Which section of the AudioDevice to query.
inPropertyID
The AudioDevicePropertyID of the property to query.
outSize
A pointer to a UInt32 that receives the size of the property data in bytes on exit. This can be NULL if the size information is not being requested.
outWritable
A pointer to a Boolean that receives indication of whether or not the given property can be set. This can be NULL if the writability is not being requested.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

AudioDriverPlugInDeviceSetProperty

Tells the AudioDevice object to change the value of the given property using the provided data. 

extern OSStatus AudioDriverPlugInDeviceSetProperty(
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inWhen, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);
Parameters
inDevice
The AudioDevice to change.
inWhen
A pointer to an AudioTimeStamp that says when to change the property's value relative to the device's time base. NULL means execute the change immediately.
inChannel
The channel of the property to change where 0 is the master channel.
isInput
Which section of the AudioDevice to change.
inPropertyID
The AudioDevicePropertyID of the property to change.
inPropertyDataSize
A UInt32 indicating the size of the buffer pointed to by inData.
inPropertyData
The buffer containing the data to be used to change the property's value.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

Discussion

Note that the value of the property should not be considered changed until the HAL has called the listeners as many properties values are changed asynchronously.

AudioDriverPlugInOpen

Instantiates a new instance of the driver plug-in. 

extern OSStatus AudioDriverPlugInOpen(
    AudioDriverPlugInHostInfo*inHostInfo);
Parameters
inHostInfo
An AudioDriverPlugInHostInfo struct that tells the plug-in what device it is being instantiated for.
Return Value

An OSStatus indicating success or failure.

AudioDriverPlugInStreamGetProperty

Queries an the AudioStream object to get the data of the given property and places it in the provided buffer. 

extern OSStatus AudioDriverPlugInStreamGetProperty(
    AudioDeviceID inDevice, 
    io_object_t inIOAudioStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);
Parameters
inDevice
The AudioDevice who's stream is being queried.
inIOAudioStream
The IOAudioStream to query.
inChannel
The channel of the property to query where 0 is the master channel.
inPropertyID
The AudioDevicePropertyID of the property to query.
ioPropertyDataSize
A UInt32 which on entry indicates the size of the buffer pointed to by outData and on exit indicates how much of the buffer was used.
outPropertyData
The buffer into which the object will put the data for the given property.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

AudioDriverPlugInStreamGetPropertyInfo

Retrieve information about the given property of an AudioStream. 

extern OSStatus AudioDriverPlugInStreamGetPropertyInfo(
    AudioDeviceID inDevice, 
    io_object_t inIOAudioStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);
Parameters
inDevice
The AudioDevice who's stream is being queried.
inIOAudioStream
The IOAudioStream to query.
inChannel
The channel of the property to query where 0 is the master channel.
inPropertyID
The AudioDevicePropertyID of the property to query.
outSize
A pointer to a UInt32 that receives the size of the property data in bytes on exit. This can be NULL if the size information is not being requested.
outWritable
A pointer to a Boolean that receives indication of whether or not the given property can be set. This can be NULL if the writability is not being requested.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

AudioDriverPlugInStreamSetProperty

Tells the AudioStream object to change the value of the given property using the provided data. 

extern OSStatus AudioDriverPlugInStreamSetProperty(
    AudioDeviceID inDevice, 
    io_object_t inIOAudioStream, 
    const AudioTimeStamp*inWhen, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);
Parameters
inDevice
The AudioDevice who's stream is being changed.
inIOAudioStream
The IOAudioStream to change.
inWhen
A pointer to an AudioTimeStamp that says when to change the property's value relative to the device's time base. NULL means execute the change immediately.
inChannel
The channel of the property to change where 0 is the master channel.
inPropertyID
The AudioDevicePropertyID of the property to change.
inPropertyDataSize
A UInt32 indicating the size of the buffer pointed to by inData.
inPropertyData
The buffer containing the data to be used to change the property's value.
Return Value

An OSStatus indicating success or failure. Note that if the plug-in does not implement the given property, it should return kAudioHardwareUnknownPropertyError to ensure that the HAL handles the property normally.

Discussion

Note that the value of the property should not be considered changed until the HAL has called the listeners as many properties values are changed asynchronously.

Typedefs

AudioDriverPlugInDevicePropertyChangedProc

A plug-in calls this routine to notify the HAL that one of it's device's properties has changed. 

typedef OSStatus (*AudioDriverPlugInDevicePropertyChangedProc)(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID);
Parameters
inDevice
The device whose property has changed.
inChannel
The channel of the device the property that has changed belongs to.
isInput
The section of the device the property that has changed belongs to.
inPropertyID
The selector of the property that has changed.
Return Value

The return value is currently unused and should always be 0.

Discussion

The HAL will notify any listeners on behalf of the plug-in. The pointer to this routine is supplied to the plug-in when it is opened.

AudioDriverPlugInStreamPropertyChangedProc

A plug-in calls this routine to notify the HAL that a property of one of the streams of one of it's devices has changed. 

typedef OSStatus (*AudioDriverPlugInStreamPropertyChangedProc)(
    AudioDeviceID inDevice, 
    io_object_t inIOAudioStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID);
Parameters
inDevice
The device whose property has changed.
inIOAudioStream
The stream whose property has changed.
inChannel
The channel of the stream the property that has changed belongs to.
inPropertyID
The selector of the property that has changed.
Return Value

The return value is currently unused and should always be 0.

Discussion

The HAL will notify any listeners on behalf of the plug-in. The pointer to this routine is supplied to the plug-in when it is opened.

Structs and Unions

AudioDriverPlugInHostInfo

This structure provides the plug-in with all the info it needs with respect to communicating with the HAL. 

struct AudioDriverPlugInHostInfo { 
    AudioDeviceID mDeviceID; 
    io_object_t mIOAudioDevice; 
    io_object_t mIOAudioEngine; 
    AudioDriverPlugInDevicePropertyChangedProc mDevicePropertyChangedProc; 
    AudioDriverPlugInStreamPropertyChangedProc mStreamPropertyChangedProc; 
};
Fields
mDeviceID
The AudioDeviceID of the audio device.
mIOAudioDevice
The io_object_t that points to the IOAudioDevice object for the device in the driver.
mIOAudioEngine
The io_object_t that points to the IOAudioEngine object for the device in the driver.
mDevicePropertyChangedProc
The AudioDriverPlugInDevicePropertyChangedProc the plug-in should call when a device property changes.
mStreamPropertyChangedProc
The AudioDriverPlugInStreamPropertyChangedProc the plug-in should call when a stream property changes.

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: 2006-10-25