AudioDriverPlugIn
Discussion
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
Closes an instance of the driver plug-in.
extern OSStatus AudioDriverPlugInClose (
AudioDeviceID inDevice
);
Parameter Descriptions
- inDevice
- The AudioDeviceID that describes the device who's plug-in instance is being
closed.
- function result
- An OSStatus indicating success or failure.
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
);
Parameter Descriptions
- 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.
- function result
- 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.
Retrieve information about the given property of an AudioDevice.
extern OSStatus AudioDriverPlugInDeviceGetPropertyInfo (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
UInt32* outSize,
Boolean* outWritable
);
Parameter Descriptions
- 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.
- function result
- 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.
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
);
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.
Parameter Descriptions
- 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.
- function result
- 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.
Instantiates a new instance of the driver plug-in.
extern OSStatus AudioDriverPlugInOpen (
AudioDriverPlugInHostInfo* inHostInfo
);
Parameter Descriptions
- inHostInfo
- An AudioDriverPlugInHostInfo struct that tells the plug-in what device it is
being instantiated for.
- function result
- An OSStatus indicating success or failure.
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
);
Parameter Descriptions
- 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.
- function result
- 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.
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
);
Parameter Descriptions
- 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.
- function result
- 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.
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
);
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.
Parameter Descriptions
- 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.
- function result
- 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.
Typedefs
A plug-in calls this routine to notify the HAL that one of it's device's
properties has changed.
typedef OSStatus (typedef OSStatus
*AudioDriverPlugInDevicePropertyChangedProc) (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID
);
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.
Parameter Descriptions
- 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.
- function result
- The return value is currently unused and should always be 0.
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 (typedef OSStatus
*AudioDriverPlugInStreamPropertyChangedProc) (
AudioDeviceID inDevice,
io_object_t inIOAudioStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID
);
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.
Parameter Descriptions
- 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.
- function result
- The return value is currently unused and should always be 0.
Structs
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;
} ;
Field Descriptions
- 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.
(Last Updated 12/13/2004)