AudioHardwarePlugIn

Introduction

This is the CFPlugIn interface presented by a HAL plug-in. The HAL will create only one instance of each interface. This instance is responsible for providing all required services on behalf of as many devices of the kind it implements.

The Initialize method is called to allow the plug-in to set itself up. At this time any devices of it's kind and their streams can be presented to the system using AudioHardwareDevicesCreated() and AudioHardwareStreamsCreated(). The plug-in is also responsible for managing it's own notifications, and may install any CFRunLoopSources it needs using AudioHardwareAddRunLoopSource() at this time as well.

Teardown() is called when the HAL is unloading itself and the plug-in should dispose of any devices and streams it has created using AudioHardwareDevicesDied() and AudioHardareStreamsDied().

The rest of the methods in this interface correspond to the semantics of their similarly named counterparts in . The HAL basically passes these calls directly to the plug-in in this fashion.

Plug-ins do not have to manage device or stream property listener procs. Instead, a plug-in can call AudioHardwareDevicePropertyChanged() or AudioHardwareStreamPropertyChanged() and the HAL will take care of calling all the appropriate listeners.

COM Interfaces

AudioHardwarePlugInInterface

The CFPlugIn interface to a HAL plug-in.

Functions

AudioHardwareClaimAudioDeviceID

Reserve a new AudioDeviceID.

AudioHardwareClaimAudioStreamID

Reserve a new AudioStreamID.

AudioHardwareDevicePropertyChanged

Tell the HAL that the property of an AudioDevice owned by the plug-in has changed.

AudioHardwareDevicesCreated

Tell the HAL that new AudioDevices have come into being.

AudioHardwareDevicesDied

Tell the HAL that some AudioDevices have gone away.

AudioHardwareStreamPropertyChanged

Tell the HAL that the property of an AudioStream owned by the plug-in has changed.

AudioHardwareStreamsCreated

Tell the HAL that new AudioStreams have come into being.

AudioHardwareStreamsDied

Tell the HAL that some AudioStreams have gone away.

AudioObjectCreate

Instantiates a new AudioObject.

AudioObjectPropertiesChanged

Tell the HAL that properties have changed on the given AudioObject.

AudioObjectsPublishedAndDied

Tell the HAL to publish some AudioObjects and tear down others.

Reserve a new AudioDeviceID.

extern OSStatus AudioHardwareClaimAudioDeviceID(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID*outAudioDeviceID);  

Parameters

inOwner

The plug-in instance requesting the new AudioDeviceID.

outAudioDeviceID

On exit, the new AudioDeviceID.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.3.

Reserve a new AudioStreamID.

extern OSStatus AudioHardwareClaimAudioStreamID(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID inOwningDeviceID, 
    AudioStreamID*outAudioStreamID);  

Parameters

inOwner

The plug-in instance requesting the new AudioStreamID.

inOwningDeviceID

The AudioDeviceID of the AudioDevice that is to own the AudioStream.

outAudioStreamID

On exit, the new AudioStreamID.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that the property of an AudioDevice owned by the plug-in has changed.

extern OSStatus AudioHardwareDevicePropertyChanged(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID inDeviceID, 
    UInt32 inChannel, 
    Boolean isInput, 
    AudioDevicePropertyID inPropertyID);  

Parameters

inOwner

The plug-in instance that owns the AudioDevice whose property has changed.

inDeviceID

The AudioDeviceID of the AudioDevice whose property has changed.

inChannel

The channel of the AudioDevice whose property has changed.

isInput

The section of the AudioDevice whose proeprty has changed.

inPropertyID

The AudioObjectPropertySelector of the property that changed.

Return Value

An OSStatus indicating success or failure.

Discussion

The HAL will take care of calling any registered listeners.

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that new AudioDevices have come into being.

extern OSStatus AudioHardwareDevicesCreated(
    AudioHardwarePlugInRef inOwner, 
    UInt32 inNumberDevices, 
    const AudioDeviceID*inAudioDeviceIDs);  

Parameters

inOwner

The plug-in instance that owns the new AudioDevices.

inNumberDevices

The number of items in the inAudioDeviceIDs array.

inAudioDeviceIDs

An array of AudioDeviceIDs that refer to the new AudioDevices.

Return Value

An OSStatus indicating success or failure.

Discussion

The plug-in must have previously reserved the AudioDeviceIDs using AudioHardwareClaimAudioDeviceID().

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that some AudioDevices have gone away.

extern OSStatus AudioHardwareDevicesDied(
    AudioHardwarePlugInRef inOwner, 
    UInt32 inNumberDevices, 
    const AudioDeviceID*inAudioDeviceIDs);  

Parameters

inOwner

The plug-in instance that owns the dead AudioDevices.

inNumberDevices

The number of items in the inAudioDeviceIDs array.

inAudioDeviceIDs

An array of AudioDeviceIDs that refer to the dead AudioDevices.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that the property of an AudioStream owned by the plug-in has changed.

extern OSStatus AudioHardwareStreamPropertyChanged(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID inOwningDeviceID, 
    AudioStreamID inStreamID, 
    UInt32 inChannel, 
    AudioDevicePropertyID inPropertyID);  

Parameters

inOwner

The plug-in instance that owns the AudioStream whose property has changed.

inOwningDeviceID

The AudioDeviceID of the AudioDevice that owns the AudioStream.

inStreamID

The AudioStreamID of the AudioStream whose property has changed.

inChannel

The channel of the AudioStream whose property has changed.

inPropertyID

The AudioObjectPropertySelector of the property that changed.

Return Value

An OSStatus indicating success or failure.

Discussion

The HAL will take care of calling any registered listeners.

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that new AudioStreams have come into being.

extern OSStatus AudioHardwareStreamsCreated(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID inOwningDeviceID, 
    UInt32 inNumberStreams, 
    const AudioStreamID*inAudioStreamIDs);  

Parameters

inOwner

The plug-in instance that owns the new AudioStreams.

inOwningDeviceID

The AudioDeviceID of the AudioDevice that owns the AudioStreams.

inNumberStreams

The number of items in the inAudioStreamIDs array.

inAudioStreamIDs

An array of AudioStreamIDs that refer to the new AudioStreams.

Return Value

An OSStatus indicating success or failure.

Discussion

The plug-in must have previously reserved the AudioStreamIDs using AudioHardwareClaimAudioStreamID().

Availability

Introduced in Mac OS X v10.3.

Tell the HAL that some AudioStreams have gone away.

extern OSStatus AudioHardwareStreamsDied(
    AudioHardwarePlugInRef inOwner, 
    AudioDeviceID inOwningDeviceID, 
    UInt32 inNumberStreams, 
    const AudioStreamID*inAudioStreamIDs);  

Parameters

inOwner

The plug-in instance that owns the dead AudioStreams.

inOwningDeviceID

The AudioDeviceID of the AudioDevice that owns the AudioStreams.

inNumberDevices

The number of items in the inAudioStreamIDs array.

inAudioStreamIDs

An array of AudioStreamIDs that refer to the dead AudioStreams.

Return Value

An OSStatus indicating success or failure.

Availability

Introduced in Mac OS X v10.3.

Instantiates a new AudioObject.

extern OSStatus AudioObjectCreate(
    AudioHardwarePlugInRef inOwningPlugIn, 
    AudioObjectID inOwningObjectID, 
    AudioClassID inClassID, 
    AudioObjectID*outAudioObjectID);  

Parameters

inOwningPlugIn

The plug-in instance instantiating the new AudioObject.

inOwningObjectID

The AudioObjectID of the AudioObject that owns the new AudioObject.

inClassID

The ID of the class of the new AudioObject.

outAudioObjectID

On exit, the AudioObjectID of the new AudioObject.

Return Value

An OSStatus indicating success or failure.

Discussion

Newly instantiated AudioObjects are not made available to the HAL's clients until the object is published using AudioObjectsPublishedAndDied().

Availability

Introduced in Mac OS X v10.4.

Tell the HAL that properties have changed on the given AudioObject.

extern OSStatus AudioObjectPropertiesChanged(
    AudioHardwarePlugInRef inOwningPlugIn, 
    AudioObjectID inObjectID, 
    UInt32 inNumberAddresses, 
    const AudioObjectPropertyAddress inAddresses[]);  

Parameters

inOwningPlugIn

The plug-in instance that owns the AudioObject whose properties have changed.

inObjectID

The AudioObjectID of the AudioObject whose properties have changed.

inNumberAddresses

The number of items in the inAddresses array.

inAddresses

An array of AudioObjectPropertyAddress structs indicating which properties of the device have changed.

Return Value

An OSStatus indicating success or failure.

Discussion

The HAL will take care of calling any registered listeners.

Availability

Introduced in Mac OS X v10.4.

Tell the HAL to publish some AudioObjects and tear down others.

extern OSStatus AudioObjectsPublishedAndDied(
    AudioHardwarePlugInRef inOwningPlugIn, 
    AudioObjectID inOwningObjectID, 
    UInt32 inNumberPublishedAudioObjects, 
    const AudioObjectID inPublishedAudioObjects[], 
    UInt32 inNumberDeadAudioObjects, 
    const AudioObjectID inDeadAudioObjects[]);  

Parameters

inOwningPlugIn

The plug-in instance that owns the AudioObjects.

inOwningObjectID

The AudioObjectID of the AudioObject that owns the objects being published or destroyed.

inNumberPublishedAudioObjects

The number of items in the inPublishedAudioObjects array.

inPublishedAudioObjects

An array of AudioObjectIDs for the AudioObjects that are to be made available to the HAL's clients.

inNumberDeadAudioObjects

The number of items in the inDeadAudioObjects array.

inDeadAudioObjects

An array of AudioObjectIDs for the AudioObjects that are no longer available.

Return Value

An OSStatus indicating success or failure.

Discussion

Note that all the objects must be owned by inOwningObjectID.

Availability

Introduced in Mac OS X v10.4.

Typedefs

Forward declaration of AudioHardwarePlugInInterface.

typedef struct AudioHardwarePlugInInterface AudioHardwarePlugInInterface;  

A reference to an AudioHardwarePlugInInterface.

typedef AudioHardwarePlugInInterface** AudioHardwarePlugInRef;  

#defines

#define kAudioHardwarePlugInInterface2ID \ 
    CFUUIDGetConstantUUIDWithBytes( NULL, 0x5D, 0x80, 0xCB, 0x6C, 0x48, 0x4F, 0x11, 0xD7, \ 
    0x85, 0x71, 0x00, 0x0A, 0x95, 0x77, 0x12, 0x82) 

Discussion

This is the UUID of version 2 of the plug-in interface (5D80CB6C-484F-11D7-8571-000A95771282).

#define kAudioHardwarePlugInInterface3ID \ 
    CFUUIDGetConstantUUIDWithBytes( NULL, 0x38, 0xD7, 0x8A, 0x18, 0x77, 0xA5, 0x11, 0xD8, \ 
    0xB8, 0xB8, 0x00, 0x0A, 0x95, 0x88, 0x78, 0x7E) 

Discussion

This is the UUID of version 3 of the plug-in interface (38D78A18-77A5-11D8-B8B8-000A9588787E).

#define kAudioHardwarePlugInInterfaceID \ 
    CFUUIDGetConstantUUIDWithBytes( NULL, 0xFA, 0xFC, 0xAF, 0xC3, 0xBA, 0xE8, 0x11, 0xD6, \ 
    0xB4, 0xA8, 0x00, 0x03, 0x93, 0x15, 0xCD, 0x46) 

Discussion

This is the UUID of version 1 of the plug-in interface (FAFCAFC3-BAE8-11D6-B4A8-00039315CD46).

#define kAudioHardwarePlugInTypeID \ 
    CFUUIDGetConstantUUIDWithBytes( NULL, 0xF8, 0xBB, 0x1C, 0x28, 0xBA, 0xE8, 0x11, 0xD6, \ 
    0x9C, 0x31, 0x00, 0x03, 0x93, 0x15, 0xCD, 0x46) 

Discussion

This is the UUID of the plug-in type (F8BB1C28-BAE8-11D6-9C31-00039315CD46).

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