Advanced Search

Log In | Not a Member?

Contact ADC

Introduction

The audio HAL provides an abstraction through which applications can access audio hardware. To do this, the HAL provides a small set of AudioObjects that provide access to the various pieces of the system.

AudioObjects all have a set of properties that describe and manipulate their state. A property is accessed via an ordered triple. The first ordinate is the selector which describes the property. The other two ordinates are the scope and element that identify the particular part of the object in which to look for the selector. The AudioObjectPropertyAddress structure encapsulates the property address. The value of a property is an untyped block of data whose content depends on the specifics of the selector. Some selectors also require the use of a qualifier when querying. The qualifier allows for additional information to be provided to be used in the manipulation of the property. Changing the value of a property is always considered asynchronous.

Applications use the routines AudioObjectHasProperty(), AudioObjectIsPropertySettable() and AudioObjectGetPropertyDataSize() to find useful meta-information about the property. Apps use AudioObjectGetPropertyData() and AudioObjectSetPropertyData() to manipulate the value of the property. Apps use AudioObjectAddPropertyListener() and AudioObjectRemovePropertyListener() to register/unregister a function that is to be called when a given property's value changes.

The class of an AudioObject determines the basic functionality of the object in terms of what functions will operate on it as well as the set of properties that can be expected to be implemented by the object. The set of available classes for objects is limited to those defined here. There are no other classes. The set of classes is arranged in a hierarchy such that one class inherits the properties/routines of it's super class.

The base class for all AudioObjects is the class AudioObject. As such, each AudioObject will provide basic properties such as it's class, it's human readable name, and the other AudioObjects it contains. Other important classes include AudioSystemObject, AudioDevice, and AudioStream.

The AudioObjects in the HAL are arranged in a containment hierarchy. The root of the hierarchy is the one and only instance of the AudioSystemObject class. The properties of the AudioSystemObject describe the process global settings such as the various default devices and the notification run loop. The AudioSystemObject also contains all the AudioDevices that are available.

Instances of the AudioDevice class encapsulate individual audio devices. An AudioDevice serves as the basic unit of IO. It provides a single IO cycle, a timing source based on it, and all the buffers synchronized to it. The IO cycle presents all the synchronized buffers to the client in the same call out along with time stamps that specify the current time, when the input data was acquired and when the output data will be presented.

AudioDevices contain instances of the AudioStream class. An AudioStream represents a single buffer of data for transferring across the user/kernel boundary. As such, AudioStreams are the gatekeepers of format information. Each has it's own format and list of available formats. AudioStreams can provide data in any format, including encoded formats and non-audio formats. If the format is a linear PCM format, the data will always be presented as 32 bit, native endian floating point. All conversions to and from the true physical format of the hardware is handled by the device's driver.

Both AudioDevices and AudioStreams can contain instances of the AudioControl class or it's many subclasses. An AudioControl provides properties that describe/manipulate a particular aspect of the object such as gain, mute, data source selection, etc. Many common controls are also also available as properties on the AudioDevice or AudioStream.

Functions

AudioDeviceAddIOProc

Registers the given AudioDeviceIOProc with the AudioDevice.

AudioDeviceAddPropertyListener

Registers the given AudioDevicePropertyListenerProc to receive notifications when the given property changes.

AudioDeviceGetCurrentTime

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

AudioDeviceGetNearestStartTime

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

AudioDeviceGetProperty

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

AudioDeviceGetPropertyInfo

Retrieve information about the given property of an AudioDevice.

AudioDeviceRead

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

AudioDeviceRemoveIOProc

Unregisters the given AudioDeviceIOProc from the AudioDevice.

AudioDeviceRemovePropertyListener

Unregisters the given AudioDevicePropertyListenerProc from receiving notifications when the given property changes.

AudioDeviceSetProperty

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

AudioDeviceStart

Starts IO for the given AudioDeviceIOProc.

AudioDeviceStartAtTime

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

AudioDeviceStop

Stops IO for the given AudioDeviceIOProc.

AudioDeviceTranslateTime

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

AudioHardwareAddPropertyListener

Registers the given AudioHardwarePropertyListenerProc to receive notifications when the given property changes.

AudioHardwareAddRunLoopSource

Add the given CFRunLoopSource to the the HAL's notification CFRunLoop.

AudioHardwareGetProperty

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

AudioHardwareGetPropertyInfo

Retrieve information about the given property.

AudioHardwareRemovePropertyListener

Unregisters the given AudioHardwarePropertyListenerProc from receive notifications when the given property changes.

AudioHardwareRemoveRunLoopSource

Remove the given CFRunLoopSource from the the HAL's notification CFRunLoop.

AudioHardwareSetProperty

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

AudioHardwareUnload

When this routine is called, all IO on all devices within a process will be terminated and all resources capable of being released will be released. This routine essentially returns the HAL to it's uninitialized state.

AudioObjectAddPropertyListener

Registers the given AudioObjectPropertyListenerProc to receive notifications when the given properties change.

AudioObjectGetPropertyData

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

AudioObjectGetPropertyDataSize

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

AudioObjectHasProperty

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

AudioObjectIsPropertySettable

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

AudioObjectRemovePropertyListener

Unregisters the given AudioObjectPropertyListenerProc from receiving notifications when the given properties change.

AudioObjectSetPropertyData

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

AudioObjectShow

Prints to standard out a textural description of the AudioObject.

AudioStreamAddPropertyListener

Registers the given AudioStreamPropertyListenerProc to receive notifications when the given property changes.

AudioStreamGetProperty

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

AudioStreamGetPropertyInfo

Retrieve information about the given property of an AudioStream.

AudioStreamRemovePropertyListener

Unregisters the given AudioStreamPropertyListenerProc from receiving notifications when the given property changes.

AudioStreamSetProperty

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

Registers the given AudioDeviceIOProc with the AudioDevice.

extern OSStatus AudioDeviceAddIOProc(
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc, 
    void*inClientData);  

Parameters

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.

Availability

Introduced in Mac OS X v10.0.

Registers the given AudioDevicePropertyListenerProc to receive notifications when the given property changes.

extern OSStatus AudioDeviceAddPropertyListener(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    AudioDevicePropertyListenerProc inProc, 
    void*inClientData);  

Parameters

inDevice

The AudioDevice with whom to register the listener.

inChannel

The channel of the property to listen to.

isInput

Which section of the AudioDevice to listen to.

inPropertyID

The AudioDevicePropertyID of the property to listen to.

inProc

AudioDevicePropertyListenerProc to call.

inClientData

A pointer to client data that is passed to the listener when it is called.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectAddPropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceGetCurrentTime(
    AudioDeviceID inDevice, 
    AudioTimeStamp*outTime);  

Parameters

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.

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceGetNearestStartTime(
    AudioDeviceID inDevice, 
    AudioTimeStamp*ioRequestedStartTime, 
    UInt32 inFlags);  

Parameters

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.

Availability

Introduced in Mac OS X v10.3.

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

extern OSStatus AudioDeviceGetProperty(
    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.

Discussion

Note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.0.

Retrieve information about the given property of an AudioDevice.

extern OSStatus AudioDeviceGetPropertyInfo(
    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.

Discussion

Note that the same functionality is provided by the functions AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and AudioObjectGetPropertyDataSize().

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceRead(
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inStartTime, 
    AudioBufferList*outData);  

Parameters

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.

Discussion

With the advent of aggregate devices, the need for AudioDeviceRead has gone away. Consequently, this function is a good candidate for deprecation some day.

Availability

Introduced in Mac OS X v10.1.

Unregisters the given AudioDeviceIOProc from the AudioDevice.

extern OSStatus AudioDeviceRemoveIOProc(
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  

Parameters

inDevice

The AudioDevice to unregister the IOProc from.

inProc

The AudioDeviceIOProc to unregister.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.0.

Unregisters the given AudioDevicePropertyListenerProc from receiving notifications when the given property changes.

extern OSStatus AudioDeviceRemovePropertyListener(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    AudioDevicePropertyListenerProc inProc);  

Parameters

inDevice

The AudioDevice with whom to unregister the listener.

inChannel

The channel of the property to unregister from.

isInput

Which section of the AudioDevice to unregister from.

inPropertyID

The AudioDevicePropertyID of the property to stop listening to.

inProc

AudioDevicePropertyListenerProc to unregister.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectRemovePropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceSetProperty(
    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.

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. Also note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.0.

Starts IO for the given AudioDeviceIOProc.

extern OSStatus AudioDeviceStart(
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  

Parameters

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.

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceStartAtTime(
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc, 
    AudioTimeStamp*ioRequestedStartTime, 
    UInt32 inFlags);  

Parameters

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.

Availability

Introduced in Mac OS X v10.3.

Stops IO for the given AudioDeviceIOProc.

extern OSStatus AudioDeviceStop(
    AudioDeviceID inDevice, 
    AudioDeviceIOProc inProc);  

Parameters

inDevice

The AudioDevice to stop the IOProc on.

inProc

The AudioDeviceIOProc to stop.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.0.

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

extern OSStatus AudioDeviceTranslateTime(
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inTime, 
    AudioTimeStamp*outTime);  

Parameters

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.

Availability

Introduced in Mac OS X v10.0.

Registers the given AudioHardwarePropertyListenerProc to receive notifications when the given property changes.

extern OSStatus AudioHardwareAddPropertyListener(
    AudioHardwarePropertyID inPropertyID, 
    AudioHardwarePropertyListenerProc inProc, 
    void*inClientData);  

Parameters

inPropertyID

The AudioHardwarePropertyID of the property to listen to.

inProc

AudioHardwarePropertyListenerProc to call.

inClientData

A pointer to client data that is passed to the listener when it is called.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectAddPropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.0.

Add the given CFRunLoopSource to the the HAL's notification CFRunLoop.

extern OSStatus AudioHardwareAddRunLoopSource(
    CFRunLoopSourceRef inRunLoopSource);  

Parameters

inRunLoopSource

The CFRunLoopSource to add.

Return Value

An OSStatus indicating success or failure.

Discussion

The CFRunLoop the HAL uses for notifications is specified by kAudioHardwarePropertyRunLoop. If kAudioHardwarePropertyRunLoop changes, CFRunLoopSources added with this function will automatically be transferred to the new CFRunLoop.

Availability

Introduced in Mac OS X v10.3.

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

extern OSStatus AudioHardwareGetProperty(
    AudioHardwarePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);  

Parameters

inPropertyID

The AudioHardwarePropertyID of the property to query.

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 AudioSystemObject will put the data for the given property.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.0.

Retrieve information about the given property.

extern OSStatus AudioHardwareGetPropertyInfo(
    AudioHardwarePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);  

Parameters

inPropertyID

The AudioHardwarePropertyID 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.

Discussion

Note that the same functionality is provided by the functions AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and AudioObjectGetPropertyDataSize().

Availability

Introduced in Mac OS X v10.0.

Unregisters the given AudioHardwarePropertyListenerProc from receive notifications when the given property changes.

extern OSStatus AudioHardwareRemovePropertyListener(
    AudioHardwarePropertyID inPropertyID, 
    AudioHardwarePropertyListenerProc inProc);  

Parameters

inPropertyID

The AudioHardwarePropertyID of the property to stop listening to.

inProc

AudioHardwarePropertyListenerProc to unregister.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectRemovePropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.0.

Remove the given CFRunLoopSource from the the HAL's notification CFRunLoop.

extern OSStatus AudioHardwareRemoveRunLoopSource(
    CFRunLoopSourceRef inRunLoopSource);  

Parameters

inRunLoopSource

The CFRunLoopSource to remove.

Return Value

An OSStatus indicating success or failure.

Discussion

The CFRunLoop the HAL uses for notifications is specified by kAudioHardwarePropertyRunLoop.

Availability

Introduced in Mac OS X v10.3.

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

extern OSStatus AudioHardwareSetProperty(
    AudioHardwarePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);  

Parameters

inPropertyID

The AudioHardwarePropertyID of the property to change.

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.

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. Also note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.0.

When this routine is called, all IO on all devices within a process will be terminated and all resources capable of being released will be released. This routine essentially returns the HAL to it's uninitialized state.

extern OSStatus AudioHardwareUnload();  

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.1.

Registers the given AudioObjectPropertyListenerProc to receive notifications when the given properties change.

extern OSStatus AudioObjectAddPropertyListener(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    AudioObjectPropertyListenerProc inListener, 
    void*inClientData);  

Parameters

inObjectID

The AudioObject to register the listener with.

inAddress

The AudioObjectPropertyAddresses indicating which property the listener should be notified about.

inListener

The AudioObjectPropertyListenerProc to call.

inClientData

A pointer to client data that is passed to the listener when it is called.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.4.

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

extern OSStatus AudioObjectGetPropertyData(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32*ioDataSize, 
    void*outData);  

Parameters

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.

Availability

Introduced in Mac OS X v10.4.

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

extern OSStatus AudioObjectGetPropertyDataSize(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32*outDataSize);  

Parameters

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.

Availability

Introduced in Mac OS X v10.4.

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

extern Boolean AudioObjectHasProperty(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress);  

Parameters

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.

Availability

Introduced in Mac OS X v10.4.

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

extern OSStatus AudioObjectIsPropertySettable(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    Boolean*outIsSettable);  

Parameters

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.

Availability

Introduced in Mac OS X v10.4.

Unregisters the given AudioObjectPropertyListenerProc from receiving notifications when the given properties change.

extern OSStatus AudioObjectRemovePropertyListener(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    AudioObjectPropertyListenerProc inListener, 
    void*inClientData);  

Parameters

inObjectID

The AudioObject to unregister the listener from.

inNumberAddresses

The number of elements in the inAddresses array.

inAddresses

The AudioObjectPropertyAddress indicating which property the listener should be removed from.

inListener

The AudioObjectPropertyListenerProc being removed.

inClientData

A pointer to client data that is passed to the listener when it is called.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.4.

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

extern OSStatus AudioObjectSetPropertyData(
    AudioObjectID inObjectID, 
    const AudioObjectPropertyAddress*inAddress, 
    UInt32 inQualifierDataSize, 
    const void*inQualifierData, 
    UInt32 inDataSize, 
    const void*inData);  

Parameters

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.

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.

Availability

Introduced in Mac OS X v10.4.

Prints to standard out a textural description of the AudioObject.

extern void AudioObjectShow(
    AudioObjectID inObjectID);  

Parameters

inObjectID

The AudioObject to show.

Availability

Introduced in Mac OS X v10.4.

Registers the given AudioStreamPropertyListenerProc to receive notifications when the given property changes.

extern OSStatus AudioStreamAddPropertyListener(
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    AudioStreamPropertyListenerProc inProc, 
    void*inClientData);  

Parameters

inStream

The AudioStream with whom to register the listener.

inChannel

The channel of the property to listen to.

inPropertyID

The AudioDevicePropertyID of the property to listen to.

inProc

AudioStreamPropertyListenerProc to call.

inClientData

A pointer to client data that is passed to the listener when it is called.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectAddPropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.1.

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

extern OSStatus AudioStreamGetProperty(
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*ioPropertyDataSize, 
    void*outPropertyData);  

Parameters

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.

Discussion

Note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.1.

Retrieve information about the given property of an AudioStream.

extern OSStatus AudioStreamGetPropertyInfo(
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32*outSize, 
    Boolean*outWritable);  

Parameters

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.

Availability

Introduced in Mac OS X v10.1.

Unregisters the given AudioStreamPropertyListenerProc from receiving notifications when the given property changes.

extern OSStatus AudioStreamRemovePropertyListener(
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    AudioStreamPropertyListenerProc inProc);  

Parameters

inStream

The AudioStream with whom to unregister the listener.

inChannel

The channel of the property to unregister from.

inPropertyID

The AudioDevicePropertyID of the property to stop listening to.

inProc

AudioStreamPropertyListenerProc to unregister.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that the same functionality is provided by AudioObjectRemovePropertyListener in conjunction with AudioObjectPropertyListenerProc.

Availability

Introduced in Mac OS X v10.1.

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

extern OSStatus AudioStreamSetProperty(
    AudioStreamID inStream, 
    const AudioTimeStamp*inWhen, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void*inPropertyData);  

Parameters

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.

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. Also note that the same functionality is provided by the function AudioObjectGetPropertyData().

Availability

Introduced in Mac OS X v10.1.

Typedefs

AudioClassIDs are used to identify the class of an AudioObject.

typedef UInt32 AudioClassID;  

AudioDevice is the base class for all objects that represent an audio device.

typedef AudioObjectID AudioDeviceID;  

Discussion

AudioDevice is a subclass of AudioObject. AudioDevices normally contain AudioStreams and AudioControls, but may contain other things depending on the kind of AudioDevice (e.g. aggregate devices contain other AudioDevices).

An AudioDeviceIOProc is called by an AudioDevice to provide input data read from the device and collect output data to be written to the device for the current IO cycle.

typedef OSStatus (*AudioDeviceIOProc)(
    AudioDeviceID inDevice, 
    const AudioTimeStamp*inNow, 
    const AudioBufferList*inInputData, 
    const AudioTimeStamp*inInputTime, 
    AudioBufferList*outOutputData, 
    const AudioTimeStamp*inOutputTime, 
    void*inClientData);  

Parameters

inDevice

The AudioDevice doing the IO.

inNow

An AudioTimeStamp that indicates the IO cycle started. Note that this time includes any scheduling latency that may have been incurred waking the thread on which IO is being done.

inInputData

An AudioBufferList containing the input data for the current IO cycle. For streams that are disabled, the AudioBuffer's mData field will be NULL but the mDataByteSize field will still say how much data would have been there if it was enabled. Note that the contents of this structure should never be modified.

inInputTime

An AudioTimeStamp that indicates the time at which the first frame in the data was acquired from the hardware. If the device has no input streams, the time stamp will be zeroed out.

outOutputData

An AudioBufferList in which the output data for the current IO cycle is to be placed. On entry, each AudioBuffer's mDataByteSize field indicates the maximum amount of data that can be placed in the buffer and the buffer's memory has been zeroed out. For formats where the number of bytes per packet can vary (as with AC-3, for example), the client has to fill out on exit each mDataByteSize field in each AudioBuffer with the amount of data that was put in the buffer. Otherwise, the mDataByteSize field should not be changed. For streams that are disabled, the AudioBuffer's mData field will be NULL but the mDataByteSize field will still say how much data would have been there if it was enabled. Except as noted above, the contents of this structure should not other wise be modified.

inOutputTime

An AudioTimeStamp that indicates the time at which the first frame in the data will be passed to the hardware. If the device has no output streams, the time stamp will be zeroed out.

inClientData

A pointer to client data established when the AudioDeviceIOProc was registered with the AudioDevice.

Return Value

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

An AudioDevicePropertyID is an integer that identifies a specific piece of information about the object.

typedef AudioObjectPropertySelector AudioDevicePropertyID;  

Clients register an AudioDevicePropertyListenerProc with the AudioDevice object in order to receive notifications when the properties of the object change.

typedef OSStatus (*AudioDevicePropertyListenerProc)(
    AudioDeviceID inDevice, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID, 
    void*inClientData);  

Parameters

inDevice

The AudioDevice whose property has changed.

inChannel

The channel of the property that changed where 0 is the master channel.

isInput

Which section of the AudioDevice changed.

inPropertyID

The AudioDevicePropertyID of the property that changed.

inClientData

A pointer to client data established when the listener proc was registered with the object.

Return Value

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

Discussion

Note that the same functionality is provided by AudioObjectPropertyListenerProc.

An AudioHardwarePropertyID is a integer that identifies a specific piece of information about the AudioSystemObject.

typedef AudioObjectPropertySelector AudioHardwarePropertyID;  

Clients register an AudioHardwarePropertyListenerProc with the AudioSystemObject in order to receive notifications when the properties of the object change.

typedef OSStatus (*AudioHardwarePropertyListenerProc)(
    AudioHardwarePropertyID inPropertyID, 
    void*inClientData);  

Parameters

inPropertyID

The AudioHardwarePropertyID of the property that changed.

inClientData

A pointer to client data established when the listener proc was registered with the AudioSystemObject.

Return Value

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

Discussion

Note that the same functionality is provided by AudioObjectPropertyListenerProc.

AudioObject is the base class for all the objects in the HAL.

typedef UInt32 AudioObjectID;  

Discussion

AudioObjects have properties and can contain other AudioObjects.

An AudioObjectPropertyElement is an integer that identifies, along with the AudioObjectPropertySelector and AudioObjectPropertyScope, a specific piece of information about an AudioObject.

typedef UInt32 AudioObjectPropertyElement;  

Discussion

The element selects one of possibly many items in the section of the object in which to look for the property. Elements are number sequentially where 0 represents the master element. Elements are particular to an instance of a class, meaning that two instances can have different numbers of elements in the same scope. There is no inheritance of elements.

Clients register an AudioObjectPropertyListenerProc with an AudioObject in order to receive notifications when the properties of the object change.

typedef OSStatus (*AudioObjectPropertyListenerProc)(
    AudioObjectID inObjectID, 
    UInt32 inNumberAddresses, 
    const AudioObjectPropertyAddress inAddresses[], 
    void*inClientData);  

Parameters

inObjectID

The AudioObject whose properties have changed.

inNumberAddresses

The number of elements in the inAddresses array.

inAddresses

An array of AudioObjectPropertyAddresses indicating which properties changed.

inClientData

A pointer to client data established when the listener proc was registered with the AudioObject.

Return Value

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

Discussion

Listeners will be called when possibly many properties have changed. Consequently, the implementation of a listener must go through the array of addresses to see what exactly has changed. Note that the array of addresses will always have at least one address in it for which the listener is signed up to receive notifications about but may contain addresses for properties for which the listener is not signed up to receive notifications.

An AudioObjectPropertyScope is a four char code that identifies, along with the AudioObjectPropertySelector and AudioObjectPropertyElement, a specific piece of information about an AudioObject.

typedef UInt32 AudioObjectPropertyScope;  

Discussion

The scope specifies the section of the object in which to look for the property, such as input, output, global, etc. Note that each class has a different set of scopes. A subclass inherits it's superclass's set of scopes.

An AudioObjectPropertySelector is a four char code that identifies, along with the AudioObjectPropertyScope and AudioObjectPropertyElement, a specific piece of information about an AudioObject.

typedef UInt32 AudioObjectPropertySelector;  

Discussion

The property selector specifies the general classification of the property such as volume, stream format, latency, etc. Note that each class has a different set of selectors. A subclass inherits it's super class's set of selectors, although it may not implement them all.

AudioStream is the base class for all objects that represent a stream of data on an audio device.

typedef AudioObjectID AudioStreamID;  

Discussion

AudioStream is a subclass of AudioObject and can contain AudioControls.

Clients register an AudioStreamPropertyListenerProc with the AudioStream object in order to receive notifications when the properties of the object change.

typedef OSStatus (*AudioStreamPropertyListenerProc)(
    AudioStreamID inStream, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID, 
    void*inClientData