Defined Types
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 (typedef OSStatus
*AudioDeviceIOProc) (
AudioDeviceID inDevice,
const AudioTimeStamp* inNow,
const AudioBufferList* inInputData,
const AudioTimeStamp* inInputTime,
AudioBufferList* outOutputData,
const AudioTimeStamp* inOutputTime,
void* inClientData
);
Parameter Descriptions
- 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.
- function result
- 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 (typedef OSStatus
*AudioDevicePropertyListenerProc) (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- 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.
- function result
- The return value is currently unused and should always be 0.
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 (typedef OSStatus
*AudioHardwarePropertyListenerProc) (
AudioHardwarePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property that changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the AudioSystemObject.
- function result
- The return value is currently unused and should always be 0.
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 (typedef OSStatus
*AudioObjectPropertyListenerProc) (
AudioObjectID inObjectID,
UInt32 inNumberAddresses,
const AudioObjectPropertyAddress inAddresses[],
void* inClientData
);
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.
Parameter Descriptions
- 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.
- function result
- The return value is currently unused and should always be 0.
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 (typedef OSStatus
*AudioStreamPropertyListenerProc) (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- inStream
- The AudioStream whose property has changed.
- inChannel
- The channel of the property that changed where 0 is the master channel.
- inPropertyID
- The AudioDevicePropertyID of the property that changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the object.
- function result
- The return value is currently unused and should always be 0.
(Last Updated 12/13/2004)