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

 


AudioHardwarePlugInInterface

Superclass:
struct
Declared In:

Introduction

The CFPlugIn interface to a HAL plug-in.

Discussion

In CFPlugIn terms, AudioHardwarePlugInInterface is a subclass of IUnknown.



Functions

AddRef
The IUnknown method for retaining a reference to a CFPlugIn type.
DeviceAddIOProc
Registers the given AudioDeviceIOProc with the AudioDevice.
DeviceGetCurrentTime
Retrieves the current time from an AudioDevice. Note that the device has to be running.
DeviceGetNearestStartTime
Query an AudioDevice to get a time equal to or later than the given time that is the best time to start IO.
DeviceGetProperty
Queries an the AudioDevice object to get the data of the given property and places it in the provided buffer.
DeviceGetPropertyInfo
Retrieve information about the given property of an AudioDevice.
DeviceRead
Read some data from an AudioDevice starting at the given time.
DeviceRemoveIOProc
Unregisters the given AudioDeviceIOProc from the AudioDevice.
DeviceSetProperty
Tells the AudioDevice object to change the value of the given property using the provided data.
DeviceStart
Starts IO for the given AudioDeviceIOProc.
DeviceStartAtTime
Starts IO for the given AudioDeviceIOProc and aligns the IO cycle of the AudioDevice with the given time.
DeviceStop
Stops IO for the given AudioDeviceIOProc.
DeviceTranslateTime
Translates the time in the AudioDevice's time base from one representation to another. Note that the device has to be running
Initialize
This method is called to initialize the instance of the plug-in.
InitializeWithObjectID
This method is called to initialize the instance of the plug-in.
ObjectGetPropertyData
Queries an AudioObject to get the data of the given property and places it in the provided buffer.
ObjectGetPropertyDataSize
Queries an AudioObject to find the size of the data for the given property.
ObjectHasProperty
Queries an AudioObject about whether or not it has the given property.
ObjectIsPropertySettable
Queries an AudioObject about whether or not the given property can be set using AudioObjectSetPropertyData.
ObjectSetPropertyData
Tells an AudioObject to change the value of the given property using the provided data.
ObjectShow
Prints to standard out a textural description of the AudioObject.
QueryInterface
The IUnknown method for finding an interface on a CFPlugIn type.
Release
The IUnknown method for releasing a reference to a CFPlugIn type.
STDMETHODCALLTYPE *AddRef
The IUnknown method for retaining a reference to a CFPlugIn type.
STDMETHODCALLTYPE *QueryInterface
The IUnknown method for finding an interface on a CFPlugIn type.
STDMETHODCALLTYPE *Release
The IUnknown method for releasing a reference to a CFPlugIn type.
StreamGetProperty
Queries an the AudioStream object to get the data of the given property and places it in the provided buffer.
StreamGetPropertyInfo
Retrieve information about the given property of an AudioStream.
StreamSetProperty
Tells the AudioStream object to change the value of the given property using the provided data.
Teardown
This method is called to tear down the instance of the plug-in.

AddRef


The IUnknown method for retaining a reference to a CFPlugIn type.

See Also:
STDMETHODCALLTYPE *AddRef
ULONG (STDMETHODCALLTYPE *AddRef)(
    void*inSelf);  
Parameters
inSelf
The CFPlugIn type to retain.
Return Value

The resulting reference count after the new reference is added.


DeviceAddIOProc


Registers the given AudioDeviceIOProc with the AudioDevice.

OSStatus (*DeviceAddIOProc)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc, 
    void*inClientData);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to register the IOProc with.
inProc
The AudioDeviceIOProc to register.
inClientData
A pointer to client data that is passed back to the IOProc when it is called.
Return Value

An OSStatus indicating success or failure.

Discussion

A client may have multiple IOProcs for a given device, but the device is free to only accept as many as it can handle. Note that it is not recommended for clients to have more than a single IOProc registered at a time as this can be wasteful of system resources. Rather, it is recommended that the client do any necessary mixing itself so that only one IOProc is necessary.


DeviceGetCurrentTime


Retrieves the current time from an AudioDevice. Note that the device has to be running.

OSStatus (*DeviceGetCurrentTime)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioTimeStamp*outTime);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to from which to get the time.
outTime
An AudioTimeStamp into which the current time is put.
Return Value

An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be returned if the AudioDevice isn't running.


DeviceGetNearestStartTime


Query an AudioDevice to get a time equal to or later than the given time that is the best time to start IO.

OSStatus (*DeviceGetNearestStartTime)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioTimeStamp*ioRequestedStartTime, 
    UInt32 inFlags);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to query.
ioRequestedStartTime
A pointer to an AudioTimeStamp that, on entry, is the requested start time. On exit, it will have the a time equal to or later than the requested time, as dictated by the device's constraints.
inFlags
A UInt32 containing flags that modify how this function behaves.
Return Value

An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be returned if the AudioDevice isn't running. kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does not support starting at a specific time.

Discussion

The time that is returned is dictated by the constraints of the device and the system. For instance, the driver of a device that provides both audio and video data may only allow start times that coincide with the edge of a video frame. Also, if the device already has one or more active IOProcs, the start time will be shifted to the beginning of the next IO cycle so as not to cause discontinuities in the existing IOProcs. Another reason the start time may shift is to allow for aligning the buffer accesses in an optimal fashion. Note that the device must be running to use this function.


DeviceGetProperty


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

OSStatus (*DeviceGetProperty)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
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.


DeviceGetPropertyInfo


Retrieve information about the given property of an AudioDevice.

OSStatus (*DeviceGetPropertyInfo)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
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.


DeviceRead


Read some data from an AudioDevice starting at the given time.

OSStatus (*DeviceRead)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inStartTime, 
    AudioBufferList*outData);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to read from.
inStartTime
An AudioTimeStamp indicating the time from which to read the data. In general, the valid range of time (in frames) is from the current time minus the maximum IO buffer size to the current time minus the safety offset.
outData
An AudioBufferList that must be the same size and shape as that returned by kAudioDevicePropertyStreamConfiguration. Further, the AudioBufferList must have been previously registered with the device via kAudioDevicePropertyRegisterBufferList. On exit, the mDataSize fields will be updated with the amount of data read.
Return Value

An OSStatus indicating success or failure. kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does not support direct reading.


DeviceRemoveIOProc


Unregisters the given AudioDeviceIOProc from the AudioDevice.

OSStatus (*DeviceRemoveIOProc)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to unregister the IOProc from.
inProc
The AudioDeviceIOProc to unregister.
Return Value

An OSStatus indicating success or failure.


DeviceSetProperty


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

OSStatus (*DeviceSetProperty)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inWhen, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
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.


DeviceStart


Starts IO for the given AudioDeviceIOProc.

OSStatus (*DeviceStart)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to start the IOProc on.
inProc
The AudioDeviceIOProc to start. Note that this can be NULL, which starts the hardware regardless of whether or not there are any IOProcs registered. This is necessary if any of the AudioDevice's timing services are to be used. A balancing call to AudioDeviceStop with a NULL IOProc is required to stop the hardware.
Return Value

An OSStatus indicating success or failure.


DeviceStartAtTime


Starts IO for the given AudioDeviceIOProc and aligns the IO cycle of the AudioDevice with the given time.

OSStatus (*DeviceStartAtTime)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc, 
    AudioTimeStamp*ioRequestedStartTime, 
    UInt32 inFlags);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to start the IOProc on.
inProc
The AudioDeviceIOProc to start. Note that this can be NULL, which starts the hardware regardless of whether or not there are any IOProcs registered.
ioRequestedStartTime
A pointer to an AudioTimeStamp that, on entry, is the requested time to start the IOProc. On exit, it will be the actual time the IOProc will start.
inFlags
A UInt32 containing flags that modify how this function behaves.
Return Value

An OSStatus indicating success or failure. kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does not support starting at a specific time and inProc and ioRequestedStartTime are not NULL.


DeviceStop


Stops IO for the given AudioDeviceIOProc.

OSStatus (*DeviceStop)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice to stop the IOProc on.
inProc
The AudioDeviceIOProc to stop.
Return Value

An OSStatus indicating success or failure.


DeviceTranslateTime


Translates the time in the AudioDevice's time base from one representation to another. Note that the device has to be running

OSStatus (*DeviceTranslateTime)(
    AudioHardwarePlugInRef inSelf, 
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inTime, 
    AudioTimeStamp*outTime);  
Parameters
inSelf
The plug-in instance that owns the AudioDevice.
inDevice
The AudioDevice whose time base governs the translation.
inTime
An AudioTimeStamp containing the time to be translated.
outTime
An AudioTimeStamp into which the translated time is put. On entry, the mFlags field specifies which representations to translate the input time into. Because not every device supports all time representations, on exit, the mFlags field will indicate which translations were actually done.
Return Value

An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be returned if the AudioDevice isn't running.


Initialize


This method is called to initialize the instance of the plug-in.

OSStatus (*Initialize)(
    AudioHardwarePlugInRef inSelf);  
Parameters
inSelf
The instance to initialize.
Return Value

An OSStatus indicating success or failure.

Discussion

As part of initialization, the plug-in should publish all the AudioObjects it knows about at the time.


InitializeWithObjectID


This method is called to initialize the instance of the plug-in.

OSStatus (*InitializeWithObjectID)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID);  
Parameters
inSelf
The instance to initialize.
inObjectID
The AudioObjectID the plug-in is to use to identify itself.
Return Value

An OSStatus indicating success or failure.

Discussion

As part of initialization, the plug-in should publish all the AudioObjects it knows about at the time. This method supersedes the Initialize method for version 3 plug-ins so that an AudioObjectID can be associated with the plug-in right from the start.


ObjectGetPropertyData


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

OSStatus (*ObjectGetPropertyData)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32*ioDataSize, 
    void*outData);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to query.
inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
inQualifierDataSize
A UInt32 indicating the size of the buffer pointed to by inQualifierData. Note that not all properties require qualification, in which case this value will be 0.
inQualifierData,
A buffer of data to be used in determining the data of the property being queried. Note that not all properties require qualification, in which case this value will be NULL.
ioDataSize
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.
outData
The buffer into which the AudioObject will put the data for the given property.
Return Value

An OSStatus indicating success or failure.


ObjectGetPropertyDataSize


Queries an AudioObject to find the size of the data for the given property.

OSStatus (*ObjectGetPropertyDataSize)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32*outDataSize);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to query.
inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
inQualifierDataSize
A UInt32 indicating the size of the buffer pointed to by inQualifierData. Note that not all properties require qualification, in which case this value will be 0.
inQualifierData,
A buffer of data to be used in determining the data of the property being queried. Note that not all properties require qualification, in which case this value will be NULL.
outDataSize
A UInt32 indicating how many bytes the data for the given property occupies.
Return Value

An OSStatus indicating success or failure.


ObjectHasProperty


Queries an AudioObject about whether or not it has the given property.

Boolean (*ObjectHasProperty)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to query.
inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
Return Value

A Boolean indicating whether or not the AudioObject has the given property.


ObjectIsPropertySettable


Queries an AudioObject about whether or not the given property can be set using AudioObjectSetPropertyData.

OSStatus (*ObjectIsPropertySettable)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    Boolean*outIsSettable);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to query.
inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
outIsSettable
A Boolean indicating whether or not the property can be set.
Return Value

An OSStatus indicating success or failure.


ObjectSetPropertyData


Tells an AudioObject to change the value of the given property using the provided data.

OSStatus (*ObjectSetPropertyData)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32 inDataSize, 
    const void*inData);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to change.
inAddress
An AudioObjectPropertyAddress indicating which property is being changed.
inQualifierDataSize
A UInt32 indicating the size of the buffer pointed to by inQualifierData. Note that not all properties require qualification, in which case this value will be 0.
inQualifierData
A buffer of data to be used in determining the data of the property being queried. Note that not all properties require qualification, in which case this value will be NULL.
inDataSize
A UInt32 indicating the size of the buffer pointed to by inData.
inData
The buffer containing the data to be used to change the property's value.
Return Value

An OSStatus indicating success or failure.


ObjectShow


Prints to standard out a textural description of the AudioObject.

void (*ObjectShow)(
    AudioHardwarePlugInRef inSelf, 
    AudioObjectID inObjectID);  
Parameters
inSelf
The plug-in instance that owns the AudioObject.
inObjectID
The AudioObject to show.

QueryInterface


The IUnknown method for finding an interface on a CFPlugIn type.

See Also:
STDMETHODCALLTYPE *QueryInterface
HRESULT (STDMETHODCALLTYPE *QueryInterface)(
    void*inSelf, 
    REFIID inUUID, 
    LPVOID*outInterface);  
Parameters
inSelf
The CFPlugIn type to query.
inUUID
The UUID of the interface to find.
outInterface
The returned interface or NULL if none was found.
Return Value

An error code indicating success of failure.


Release


The IUnknown method for releasing a reference to a CFPlugIn type.

See Also:
STDMETHODCALLTYPE *Release
ULONG (STDMETHODCALLTYPE *Release)(
    void*inSelf);  
Parameters
inSelf
The CFPlugIn type to release.
Return Value

The resulting reference count after the reference has been removed.


STDMETHODCALLTYPE *AddRef


The IUnknown method for retaining a reference to a CFPlugIn type.

See Also:
AddRef
ULONG (STDMETHODCALLTYPE *AddRef)(
    void*inSelf);  
Parameters
inSelf
The CFPlugIn type to retain.

STDMETHODCALLTYPE *QueryInterface


The IUnknown method for finding an interface on a CFPlugIn type.

See Also:
QueryInterface
HRESULT (STDMETHODCALLTYPE *QueryInterface)(
    void*inSelf, 
    REFIID inUUID, 
    LPVOID*outInterface);  
Parameters
inSelf
The CFPlugIn type to query.
inUUID
The UUID of the interface to find.
outInterface
The returned interface or NULL if none was found.

STDMETHODCALLTYPE *Release


The IUnknown method for releasing a reference to a CFPlugIn type.

See Also:
Release
ULONG (STDMETHODCALLTYPE *Release)(
    void*inSelf);  
Parameters
inSelf
The CFPlugIn type to release.

StreamGetProperty


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

OSStatus (*StreamGetProperty)(
    AudioHardwarePlugInRef inSelf, 
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);  
Parameters
inSelf
The plug-in instance that owns the AudioStream.
inStream
The AudioStream 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.


StreamGetPropertyInfo


Retrieve information about the given property of an AudioStream.

OSStatus (*StreamGetPropertyInfo)(
    AudioHardwarePlugInRef inSelf, 
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);  
Parameters
inSelf
The plug-in instance that owns the AudioStream.
inStream
The AudioStream 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.


StreamSetProperty


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

OSStatus (*StreamSetProperty)(
    AudioHardwarePlugInRef inSelf, 
    AudioStreamID inStream, 
    const AudioTimeStamp*inWhen, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);  
Parameters
inSelf
The plug-in instance that owns the AudioStream.
inStream
The AudioStream 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.


Teardown


This method is called to tear down the instance of the plug-in.

OSStatus (*Teardown)(
    AudioHardwarePlugInRef inSelf);  
Parameters
inSelf
The instance to tear down.
Return Value

An OSStatus indicating success or failure.

Globals


_reserved


A standard part of the IUnknown interface.

void* _reserved;  


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