1
{==================================================================================================
2
File: CoreAudio/AudioHardware.h
4
Contains: API for communicating with audio hardware.
6
Version: Technology: Mac OS X
9
Copyright: (c) 1985-2005 by Apple Computer, Inc., all rights reserved.
11
==================================================================================================}
13
{ Pascal Translation: Gale R Paeper, <gpaeper@empirenet.com>, 2006 }
16
Modified for use with Free Pascal
18
Please report any bugs to <gpc@microbizz.nl>
29
{$setc UNIVERSAL_INTERFACES_VERSION := $0342}
30
{$setc GAP_INTERFACES_VERSION := $0200}
32
{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
33
{$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
36
{$ifc defined CPUPOWERPC and defined CPUI386}
37
{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
39
{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
40
{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
43
{$ifc not defined __ppc__ and defined CPUPOWERPC}
48
{$ifc not defined __i386__ and defined CPUI386}
54
{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
55
{$error Conflicting definitions for __ppc__ and __i386__}
58
{$ifc defined __ppc__ and __ppc__}
59
{$setc TARGET_CPU_PPC := TRUE}
60
{$setc TARGET_CPU_X86 := FALSE}
61
{$elifc defined __i386__ and __i386__}
62
{$setc TARGET_CPU_PPC := FALSE}
63
{$setc TARGET_CPU_X86 := TRUE}
65
{$error Neither __ppc__ nor __i386__ is defined.}
67
{$setc TARGET_CPU_PPC_64 := FALSE}
69
{$ifc defined FPC_BIG_ENDIAN}
70
{$setc TARGET_RT_BIG_ENDIAN := TRUE}
71
{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
72
{$elifc defined FPC_LITTLE_ENDIAN}
73
{$setc TARGET_RT_BIG_ENDIAN := FALSE}
74
{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
76
{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
78
{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
79
{$setc CALL_NOT_IN_CARBON := FALSE}
80
{$setc OLDROUTINENAMES := FALSE}
81
{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
82
{$setc OPAQUE_UPP_TYPES := TRUE}
83
{$setc OTCARBONAPPLICATION := TRUE}
84
{$setc OTKERNEL := FALSE}
85
{$setc PM_USE_SESSION_APIS := TRUE}
86
{$setc TARGET_API_MAC_CARBON := TRUE}
87
{$setc TARGET_API_MAC_OS8 := FALSE}
88
{$setc TARGET_API_MAC_OSX := TRUE}
89
{$setc TARGET_CARBON := TRUE}
90
{$setc TARGET_CPU_68K := FALSE}
91
{$setc TARGET_CPU_MIPS := FALSE}
92
{$setc TARGET_CPU_SPARC := FALSE}
93
{$setc TARGET_OS_MAC := TRUE}
94
{$setc TARGET_OS_UNIX := FALSE}
95
{$setc TARGET_OS_WIN32 := FALSE}
96
{$setc TARGET_RT_MAC_68881 := FALSE}
97
{$setc TARGET_RT_MAC_CFM := FALSE}
98
{$setc TARGET_RT_MAC_MACHO := TRUE}
99
{$setc TYPED_FUNCTION_POINTERS := TRUE}
100
{$setc TYPE_BOOL := FALSE}
101
{$setc TYPE_EXTENDED := FALSE}
102
{$setc TYPE_LONGLONG := TRUE}
103
uses MacTypes, CFRunLoop, CoreAudioTypes;
106
//==================================================================================================
107
//#pragma mark Overview
109
@header AudioHardware
110
The audio HAL provides an abstraction through which applications can access audio hardware. To
111
do this, the HAL provides a small set of AudioObjects that provide access to the various pieces
114
AudioObjects all have a set of properties that describe and manipulate their state. A property
115
is accessed via an ordered triple. The first ordinate is the selector which describes the
116
property. The other two ordinates are the scope and element that identify the particular part of
117
the object in which to look for the selector. The AudioObjectPropertyAddress structure
118
encapsulates the property address. The value of a property is an untyped block of data whose
119
content depends on the specifics of the selector. Some selectors also require the use of a
120
qualifier when querying. The qualifier allows for additional information to be provided to be
121
used in the manipulation of the property. Changing the value of a property is always considered
124
Applications use the routines AudioObjectHasProperty(), AudioObjectIsPropertySettable() and
125
AudioObjectGetPropertyDataSize() to find useful meta-information about the property. Apps use
126
AudioObjectGetPropertyData() and AudioObjectSetPropertyData() to manipulate the value of the
127
property. Apps use AudioObjectAddPropertyListener() and AudioObjectRemovePropertyListener() to
128
register/unregister a function that is to be called when a given property's value changes.
130
The class of an AudioObject determines the basic functionality of the object in terms of what
131
functions will operate on it as well as the set of properties that can be expected to be
132
implemented by the object. The set of available classes for objects is limited to those defined
133
here. There are no other classes. The set of classes is arranged in a hierarchy such that one
134
class inherits the properties/routines of it's super class.
136
The base class for all AudioObjects is the class AudioObject. As such, each AudioObject will
137
provide basic properties such as it's class, it's human readable name, and the other
138
AudioObjects it contains. Other important classes include AudioSystemObject, AudioDevice, and
141
The AudioObjects in the HAL are arranged in a containment hierarchy. The root of the hierarchy
142
is the one and only instance of the AudioSystemObject class. The properties of the
143
AudioSystemObject describe the process global settings such as the various default devices and
144
the notification run loop. The AudioSystemObject also contains all the AudioDevices that are
147
Instances of the AudioDevice class encapsulate individual audio devices. An AudioDevice serves
148
as the basic unit of IO. It provides a single IO cycle, a timing source based on it, and all the
149
buffers synchronized to it. The IO cycle presents all the synchronized buffers to the client in
150
the same call out along with time stamps that specify the current time, when the input data was
151
acquired and when the output data will be presented.
153
AudioDevices contain instances of the AudioStream class. An AudioStream represents a single
154
buffer of data for transferring across the user/kernel boundary. As such, AudioStreams are the
155
gatekeepers of format information. Each has it's own format and list of available formats.
156
AudioStreams can provide data in any format, including encoded formats and non-audio formats. If
157
the format is a linear PCM format, the data will always be presented as 32 bit, native endian
158
floating point. All conversions to and from the true physical format of the hardware is handled
159
by the device's driver.
161
Both AudioDevices and AudioStreams can contain instances of the AudioControl class or it's many
162
subclasses. An AudioControl provides properties that describe/manipulate a particular aspect of
163
the object such as gain, mute, data source selection, etc. Many common controls are also
164
also available as properties on the AudioDevice or AudioStream.
169
//==================================================================================================
170
//#pragma mark Error Constants
173
@enum Error Constants
174
@abstract The error constants unique to the HAL.
175
@discussion These are the error constants that are unique to the HAL. Note that the HAL's
176
functions can and will return other codes that are not listed here. While these
177
constants give a general idea of what might have gone wrong during the execution
178
of an API call, if an API call returns anything other than kAudioHardwareNoError
179
it is to be viewed as the same failure regardless of what constant is actually
181
@constant kAudioHardwareNoError
182
The function call completed successfully.
183
@constant kAudioHardwareNotRunningError
184
The function call requires that the hardware be running but it isn't.
185
@constant kAudioHardwareUnspecifiedError
186
The function call failed while doing something that doesn't provide any
188
@constant kAudioHardwareUnknownPropertyError
189
The AudioObject doesn't know about the property at the given address.
190
@constant kAudioHardwareBadPropertySizeError
191
An improperly sized buffer was provided when accessing the data of a
193
@constant kAudioHardwareIllegalOperationError
194
The requested operation couldn't be completed.
195
@constant kAudioHardwareBadObjectError
196
The AudioObjectID passed to the function doesn't map to a valid AudioObject.
197
@constant kAudioHardwareBadDeviceError
198
The AudioDeviceID passed to the function doesn't map to a valid AudioDevice.
199
@constant kAudioHardwareBadStreamError
200
The AudioStreamID passed to the function doesn't map to a valid AudioStream.
201
@constant kAudioHardwareUnsupportedOperationError
202
The AudioObject doesn't support the requested operation.
203
@constant kAudioDeviceUnsupportedFormatError
204
The AudioStream doesn't support the requested format.
205
@constant kAudioDevicePermissionsError
206
The requested operation can't be completed because the process doesn't have
210
kAudioHardwareNoError = 0;
211
kAudioHardwareNotRunningError = $73746F70 (* 'stop' *);
212
kAudioHardwareUnspecifiedError = $77686174 (* 'what' *);
213
kAudioHardwareUnknownPropertyError = $77686F3F (* 'who?' *);
214
kAudioHardwareBadPropertySizeError = $2173697A (* '!siz' *);
215
kAudioHardwareIllegalOperationError = $6E6F7065 (* 'nope' *);
216
kAudioHardwareBadObjectError = $216F626A (* '!obj' *);
217
kAudioHardwareBadDeviceError = $21646576 (* '!dev' *);
218
kAudioHardwareBadStreamError = $21737472 (* '!str' *);
219
kAudioHardwareUnsupportedOperationError = $756E6F70 (* 'unop' *);
220
kAudioDeviceUnsupportedFormatError = $21646174 (* '!dat' *);
221
kAudioDevicePermissionsError = $21686F67 (* '!hog' *);
223
//==================================================================================================
224
//#pragma mark Property Support Types
227
@typedef AudioObjectPropertySelector
228
@abstract An AudioObjectPropertySelector is a four char code that identifies, along with
229
the AudioObjectPropertyScope and AudioObjectPropertyElement, a specific piece of
230
information about an AudioObject.
231
@discussion The property selector specifies the general classification of the property such
232
as volume, stream format, latency, etc. Note that each class has a different set
233
of selectors. A subclass inherits it's super class's set of selectors, although
234
it may not implement them all.
237
AudioObjectPropertySelector = UInt32;
240
@typedef AudioObjectPropertyScope
241
@abstract An AudioObjectPropertyScope is a four char code that identifies, along with the
242
AudioObjectPropertySelector and AudioObjectPropertyElement, a specific piece of
243
information about an AudioObject.
244
@discussion The scope specifies the section of the object in which to look for the property,
245
such as input, output, global, etc. Note that each class has a different set of
246
scopes. A subclass inherits it's superclass's set of scopes.
249
AudioObjectPropertyScope = UInt32;
252
@typedef AudioObjectPropertyElement
253
@abstract An AudioObjectPropertyElement is an integer that identifies, along with the
254
AudioObjectPropertySelector and AudioObjectPropertyScope, a specific piece of
255
information about an AudioObject.
256
@discussion The element selects one of possibly many items in the section of the object in
257
which to look for the property. Elements are number sequentially where 0
258
represents the master element. Elements are particular to an instance of a
259
class, meaning that two instances can have different numbers of elements in the
260
same scope. There is no inheritance of elements.
263
AudioObjectPropertyElement = UInt32;
266
@struct AudioObjectPropertyAddress
267
@abstract An AudioObjectPropertyAddress collects the three parts that identify a specific
268
property together in a struct for easy transmission.
270
The AudioObjectPropertySelector for the property.
272
The AudioObjectPropertyScope for the property.
274
The AudioObjectPropertyElement for the property.
277
AudioObjectPropertyAddress = record
278
mSelector: AudioObjectPropertySelector;
279
mScope: AudioObjectPropertyScope;
280
mElement: AudioObjectPropertyElement;
282
AudioObjectPropertyAddressPtr = ^AudioObjectPropertyAddress;
284
//==================================================================================================
285
//#pragma mark Property Support Constants
288
@enum Property Wildcard Constants
289
@abstract Constants that are used as wildcards in an AudioObjectPropertyAddress.
290
@discussion Wildcards match any and all values for there associated type. They are
291
especially useful for registering listener procs to receive notifications and
292
for querying an AudioObject's list of AudioControls.
293
@constant kAudioObjectPropertySelectorWildcard
294
The wildcard value for AudioObjectPropertySelectors.
295
@constant kAudioObjectPropertyScopeWildcard
296
The wildcard value for AudioObjectPropertyScopes.
297
@constant kAudioObjectPropertyElementWildcard
298
The wildcard value for AudioObjectPropertyElements.
299
@constant kAudioPropertyWildcardPropertyID
300
A synonym for kAudioObjectPropertySelectorWildcard.
301
@constant kAudioPropertyWildcardSection
302
The wildcard value for the isInput argument of AudioDeviceGetPropertyInfo(),
303
AudioDeviceGetProperty(), and AudioDeviceSetProperty().
304
@constant kAudioPropertyWildcardChannel
305
A synonym for kAudioObjectPropertyElementWildcard.
308
kAudioObjectPropertySelectorWildcard = $2A2A2A2A (* '****' *);
309
kAudioObjectPropertyScopeWildcard = $2A2A2A2A (* '****' *);
310
kAudioObjectPropertyElementWildcard = $FFFFFFFF;
311
kAudioPropertyWildcardPropertyID = kAudioObjectPropertySelectorWildcard;
312
kAudioPropertyWildcardSection = $FF;
313
kAudioPropertyWildcardChannel = kAudioObjectPropertyElementWildcard;
315
//==================================================================================================
316
//#pragma mark AudioObject Types
319
@typedef AudioClassID
320
@abstract AudioClassIDs are used to identify the class of an AudioObject.
323
AudioClassID = UInt32;
326
@typedef AudioObjectID
327
@abstract AudioObject is the base class for all the objects in the HAL.
328
@discussion AudioObjects have properties and can contain other AudioObjects.
331
AudioObjectID = UInt32;
334
@typedef AudioObjectPropertyListenerProc
335
@abstract Clients register an AudioObjectPropertyListenerProc with an AudioObject in order
336
to receive notifications when the properties of the object change.
337
@discussion Listeners will be called when possibly many properties have changed.
338
Consequently, the implementation of a listener must go through the array of
339
addresses to see what exactly has changed. Note that the array of addresses will
340
always have at least one address in it for which the listener is signed up to
341
receive notifications about but may contain addresses for properties for which
342
the listener is not signed up to receive notifications.
344
The AudioObject whose properties have changed.
345
@param inNumberAddresses
346
The number of elements in the inAddresses array.
348
An array of AudioObjectPropertyAddresses indicating which properties
351
A pointer to client data established when the listener proc was registered
352
with the AudioObject.
353
@result The return value is currently unused and should always be 0.
356
AudioObjectPropertyListenerProc = function( inObjectID: AudioObjectID; inNumberAddresses: UInt32; {const} inAddresses: {variable-size-array} AudioObjectPropertyAddressPtr; inClientData: UnivPtr ): OSStatus;
358
//==================================================================================================
359
//#pragma mark AudioObject Constants
362
@enum AudioObject Class Constants
363
@abstract Various constants related to AudioObjects.
364
@constant kAudioObjectPropertyScopeGlobal
365
The AudioObjectPropertyScope for properties that apply to the object as a
366
whole. All AudioObjects have a global scope and for some it is their only
368
@constant kAudioObjectPropertyElementMaster
369
The AudioObjectPropertyElement value for properties that apply to the master
370
element or to the entire scope.
371
@constant kAudioObjectClassID
372
The AudioClassID that identifies the AudioObject class.
373
@constant kAudioObjectClassIDWildcard
374
The wildcard value for AudioClassIDs.
375
@constant kAudioObjectUnknown
376
The AudioObjectID for a non-existant AudioObject.
379
kAudioObjectPropertyScopeGlobal = $676C6F62 (* 'glob' *);
380
kAudioObjectPropertyElementMaster = 0;
381
kAudioObjectClassID = $616F626A (* 'aobj' *);
382
kAudioObjectClassIDWildcard = $2A2A2A2A (* '****' *);
383
kAudioObjectUnknown = 0;
385
//==================================================================================================
386
//#pragma mark AudioObject Properties
389
@enum AudioObject Property Selectors
390
@abstract AudioObjectPropertySelector values that apply to all AudioObjects.
391
@constant kAudioObjectPropertyClass
392
An AudioClassID that identifies the class of the AudioObject.
393
@constant kAudioObjectPropertyOwner
394
An AudioObjectID that identifies the the AudioObject that owns the given
395
AudioObject. Note that all AudioObjects are owned by some other AudioObject.
396
The only exception is the AudioSystemObject, for which the value of this
397
property is kAudioObjectUnknown.
398
@constant kAudioObjectPropertyCreator
399
A CFString that contains the bundle ID of the plug-in that instantiated the
401
@constant kAudioObjectPropertyObjectName
402
A CFString that contains the human readable name of the object. The caller
403
is responsible for releasing the returned CFObject.
404
@constant kAudioObjectPropertyManufacturer
405
A CFString that contains the human readable name of the manufacturer of the
406
hardware the AudioObject is a part of. The caller is responsible for
407
releasing the returned CFObject.
408
@constant kAudioObjectPropertyElementName
409
A CFString that contains a human readable name for the given element in the
410
given scope. The caller is responsible for releasing the returned CFObject.
411
@constant kAudioObjectPropertyElementCategoryName
412
A CFString that contains a human readable name for the category of the given
413
element in the given scope. The caller is responsible for releasing the
415
@constant kAudioObjectPropertyElementNumberName
416
A CFString that contains a human readable name for the number of the given
417
element in the given scope. The caller is responsible for releasing the
419
@constant kAudioObjectPropertyOwnedObjects
420
An array of AudioObjectIDs that represent all the AudioObjects owned by the
421
given object. The qualifier is an array of AudioClassIDs. If it is
422
non-empty, the returned array of AudioObjectIDs will only refer to objects
423
whose class is in the qualifier array or whose is a subclass of one in the
425
@constant kAudioObjectPropertyListenerAdded
426
An AudioObjectPropertyAddress indicating the address to which a new listener
427
was added. Note that this property is not for applications to use. Rather,
428
this property is for the HAL shell to notify AudioObjects implemented by an
429
AudioPlugIn when a listener is added.
430
@constant kAudioObjectPropertyListenerRemoved
431
An AudioObjectPropertyAddress indicating the address to which a listener was
432
removed. Note that this property is not for applications to use. Rather,
433
this property is for the HAL shell to notify AudioObjects implemented by an
434
AudioPlugIn when a listener is removed.
437
kAudioObjectPropertyClass = $636C6173 (* 'clas' *);
438
kAudioObjectPropertyOwner = $73746476 (* 'stdv' *);
439
kAudioObjectPropertyCreator = $6F706C67 (* 'oplg' *);
440
kAudioObjectPropertyName = $6C6E616D (* 'lnam' *);
441
kAudioObjectPropertyManufacturer = $6C6D616B (* 'lmak' *);
442
kAudioObjectPropertyElementName = $6C63686E (* 'lchn' *);
443
kAudioObjectPropertyElementCategoryName = $6C63636E (* 'lccn' *);
444
kAudioObjectPropertyElementNumberName = $6C636E6E (* 'lcnn' *);
445
kAudioObjectPropertyOwnedObjects = $6F776E64 (* 'ownd' *);
446
kAudioObjectPropertyListenerAdded = $6C697361 (* 'lisa' *);
447
kAudioObjectPropertyListenerRemoved = $6C697372 (* 'lisr' *);
449
//==================================================================================================
450
//#pragma mark AudioObject Functions
453
@functiongroup AudioObject
457
@function AudioObjectShow
458
@abstract Prints to standard out a textural description of the AudioObject.
460
The AudioObject to show.
462
procedure AudioObjectShow( inObjectID: AudioObjectID ); external name '_AudioObjectShow';
463
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
466
@function AudioObjectHasProperty
467
@abstract Queries an AudioObject about whether or not it has the given property.
469
The AudioObject to query.
471
An AudioObjectPropertyAddress indicating which property is being queried.
472
@result A Boolean indicating whether or not the AudioObject has the given property.
474
function AudioObjectHasProperty( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress ): Boolean; external name '_AudioObjectHasProperty';
475
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
478
@function AudioObjectIsPropertySettable
479
@abstract Queries an AudioObject about whether or not the given property can be set using
480
AudioObjectSetPropertyData.
482
The AudioObject to query.
484
An AudioObjectPropertyAddress indicating which property is being queried.
486
A Boolean indicating whether or not the property can be set.
487
@result An OSStatus indicating success or failure.
489
function AudioObjectIsPropertySettable( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; var outIsSettable: Boolean ): OSStatus; external name '_AudioObjectIsPropertySettable';
490
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
493
@function AudioObjectGetPropertyDataSize
494
@abstract Queries an AudioObject to find the size of the data for the given property.
496
The AudioObject to query.
498
An AudioObjectPropertyAddress indicating which property is being queried.
499
@param inQualifierDataSize
500
A UInt32 indicating the size of the buffer pointed to by inQualifierData.
501
Note that not all properties require qualification, in which case this
503
@param inQualifierData,
504
A buffer of data to be used in determining the data of the property being
505
queried. Note that not all properties require qualification, in which case
506
this value will be NULL.
508
A UInt32 indicating how many bytes the data for the given property occupies.
509
@result An OSStatus indicating success or failure.
511
function AudioObjectGetPropertyDataSize( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; inQualifierDataSize: UInt32; inQualifierData: {const} UnivPtr; var outDataSize: UInt32 ): OSStatus; external name '_AudioObjectGetPropertyDataSize';
512
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
515
@function AudioObjectGetPropertyData
516
@abstract Queries an AudioObject to get the data of the given property and places it in
519
The AudioObject to query.
521
An AudioObjectPropertyAddress indicating which property is being queried.
522
@param inQualifierDataSize
523
A UInt32 indicating the size of the buffer pointed to by inQualifierData.
524
Note that not all properties require qualification, in which case this
526
@param inQualifierData,
527
A buffer of data to be used in determining the data of the property being
528
queried. Note that not all properties require qualification, in which case
529
this value will be NULL.
531
A UInt32 which on entry indicates the size of the buffer pointed to by
532
outData and on exit indicates how much of the buffer was used.
534
The buffer into which the AudioObject will put the data for the given
536
@result An OSStatus indicating success or failure.
538
function AudioObjectGetPropertyData( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; inQualifierDataSize: UInt32; inQualifierData: {const} UnivPtr; var ioDataSize: UInt32; outData: UnivPtr ): OSStatus; external name '_AudioObjectGetPropertyData';
539
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
542
@function AudioObjectSetPropertyData
543
@abstract Tells an AudioObject to change the value of the given property using the
545
@discussion Note that the value of the property should not be considered changed until the
546
HAL has called the listeners as many properties values are changed
549
The AudioObject to change.
551
An AudioObjectPropertyAddress indicating which property is being changed.
552
@param inQualifierDataSize
553
A UInt32 indicating the size of the buffer pointed to by inQualifierData.
554
Note that not all properties require qualification, in which case this
556
@param inQualifierData,
557
A buffer of data to be used in determining the data of the property being
558
queried. Note that not all properties require qualification, in which case
559
this value will be NULL.
561
A UInt32 indicating the size of the buffer pointed to by inData.
563
The buffer containing the data to be used to change the property's value.
564
@result An OSStatus indicating success or failure.
566
function AudioObjectSetPropertyData( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; inQualifierDataSize: UInt32; inQualifierData: {const} UnivPtr; inDataSize: UInt32; inData: {const} UnivPtr ): OSStatus; external name '_AudioObjectSetPropertyData';
567
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
570
@function AudioObjectAddPropertyListener
571
@abstract Registers the given AudioObjectPropertyListenerProc to receive notifications
572
when the given properties change.
574
The AudioObject to register the listener with.
576
The AudioObjectPropertyAddresses indicating which property the listener
577
should be notified about.
579
The AudioObjectPropertyListenerProc to call.
581
A pointer to client data that is passed to the listener when it is called.
582
@result An OSStatus indicating success or failure.
584
function AudioObjectAddPropertyListener( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; inListener: AudioObjectPropertyListenerProc; inClientData: UnivPtr ): OSStatus; external name '_AudioObjectAddPropertyListener';
585
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
588
@function AudioObjectRemovePropertyListener
589
@abstract Unregisters the given AudioObjectPropertyListenerProc from receiving
590
notifications when the given properties change.
592
The AudioObject to unregister the listener from.
593
@param inNumberAddresses
594
The number of elements in the inAddresses array.
596
The AudioObjectPropertyAddress indicating which property the listener should
599
The AudioObjectPropertyListenerProc being removed.
601
A pointer to client data that is passed to the listener when it is called.
602
@result An OSStatus indicating success or failure.
604
function AudioObjectRemovePropertyListener( inObjectID: AudioObjectID; const (*var*) inAddress: AudioObjectPropertyAddress; inListener: AudioObjectPropertyListenerProc; inClientData: UnivPtr ): OSStatus; external name '_AudioObjectRemovePropertyListener';
605
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
607
//==================================================================================================
608
//#pragma mark AudioControl Constants
611
@enum AudioControl Base Class IDs
612
@abstract The AudioClassIDs that identify the various AudioControl base classes.
613
@constant kAudioControlClassID
614
The AudioClassID that identifies the AudioControl class.
615
@constant kAudioLevelControlClassID
616
The AudioClassID that identifies the AudioLevelControl class which is a
617
subclass of AudioControl. AudioLevelControls manipulate gain/attenuation
618
stages in the hardware.
619
@constant kAudioBooleanControlClassID
620
The AudioClassID that identifies the AudioBooleanControl class which is a
621
subclass of AudioControl. AudioBooleanControls manipulate on/off switches
623
@constant kAudioSelectorControlClassID
624
The AudioClassID that identifies the AudioSelectorControl class which is a
625
subclass of AudioControl. AudioSelectorControls manipulate controls that
626
have multiple, but discreet values.
627
@constant kAudioStereoPanControlClassID
628
The AudioClassID that identifies the AudioStereoPanControl class which is
629
a subclass of AudioControl. AudioStereoPanControls manipulate the pot for
630
panning a mono signal between a left/right pair of outputs.
633
kAudioControlClassID = $6163746C (* 'actl' *);
634
kAudioLevelControlClassID = $6C65766C (* 'levl' *);
635
kAudioBooleanControlClassID = $746F676C (* 'togl' *);
636
kAudioSelectorControlClassID = $736C6374 (* 'slct' *);
637
kAudioStereoPanControlClassID = $7370616E (* 'span' *);
640
@enum AudioLevelControl Subclass IDs
641
@abstract The four char codes that identify the various standard subclasses of
643
@constant kAudioVolumeControlClassID
644
An AudioLevelControl for a general gain/attenuation stage.
645
@constant kAudioLFEVolumeControlClassID
646
An AudioLevelControl for an LFE channel that results from bass management
647
such as the iSub. Note that LFE channels that are represented as normal
648
audio channels (in other words, real data is being fed them in an IOProc)
649
will use kAudioVolumeControlClassID to manipulate the level.
650
@constant kAudioBootChimeVolumeControlClassID
651
An AudioLevelControl for the boot chime of the CPU.
654
kAudioVolumeControlClassID = $766C6D65 (* 'vlme' *);
655
kAudioLFEVolumeControlClassID = $73756276 (* 'subv' *);
656
kAudioBootChimeVolumeControlClassID = $7072616D (* 'pram' *);
659
@enum AudioBooleanControl Subclass IDs
660
@abstract The four char codes that identify the various standard subclasses of
662
@constant kAudioMuteControlClassID
663
An AudioBooleanControl where a true value means that mute is enabled making
664
that element inaudible.
665
@constant kAudioSoloControlClassID
666
An AudioBooleanControl where a true value means that solo is enabled making
667
just that element audible and the other elements inaudible.
668
@constant kAudioJackControlClassID
669
An AudioBooleanControl where a true value means something is plugged into
671
@constant kAudioLFEMuteControlClassID
672
An AudioBooleanControl where true means that mute is enabled make that LFE
673
element inaudible. This control is for LFE channels that result from bass
674
management such as the iSub. Note that LFE channels that are represented as
675
normal audio channels (in other words, real data is being fed them in an
676
IOProc) will use kAudioVolumeControlClassID to manipulate mute.
677
@constant kAudioISubOwnerClassID
678
An AudioBooleanControl where true means that the AudioDevice that
679
ultimately owns the control also owns any iSub attached to the CPU.
682
kAudioMuteControlClassID = $6D757465 (* 'mute' *);
683
kAudioSoloControlClassID = $736F6C6F (* 'solo' *);
684
kAudioJackControlClassID = $6A61636B (* 'jack' *);
685
kAudioLFEMuteControlClassID = $7375626D (* 'subm' *);
686
kAudioISubOwnerControlClassID = $61746368 (* 'atch' *);
689
@enum AudioSelectorControl Subclass IDs
690
@abstract The four char codes that identify the various standard subclasses of
691
AudioSelectorControl.
692
@constant kAudioDataSourceControlClassID
693
An AudioSelectorControl that identifies where the data for the element is
695
@constant kAudioDataDestinationControlClassID
696
An AudioSelectorControl that identifies where the data for the element is
698
@constant kAudioClockSourceControlClassID
699
An AudioSelectorControl that identifies where the timing info for the object
701
@constant kAudioLineLevelControlClassID
702
An AudioSelectorControl that identifies the nominal line level for the
703
element. Note that this is not a gain stage but rather indicating the
704
voltage standard (if any) used for the element, such as +4dBu, -10dBV,
708
kAudioDataSourceControlClassID = $64737263 (* 'dsrc' *);
709
kAudioDataDestinationControlClassID = $64657374 (* 'dest' *);
710
kAudioClockSourceControlClassID = $636C636B (* 'clck' *);
711
kAudioLineLevelControlClassID = $6E6C766C (* 'nlvl' *);
713
//==================================================================================================
714
//#pragma mark AudioControl Properties
717
@enum AudioControl Properties
718
@abstract AudioObjectPropertySelector values that apply to all AudioControls.
719
@discussion AudioControl is a subclass of AudioObject and has only the single scope,
720
kAudioObjectPropertyScopeGlobal, and only a master element.
721
@constant kAudioControlPropertyScope
722
The AudioObjectPropertyScope in the owning AudioObject that contains the
724
@constant kAudioControlPropertyElement
725
The AudioObjectPropertyElement in the owning AudioObject that contains the
727
@constant kAudioControlPropertyVariant
728
A UInt32 that identifies the specific variant of an AudioControl. This
729
allows the owning AudioObject to support controls that are of the same basic
730
class (that is, the values of kAudioObjectPropertyClass are the same) but
731
may control a part of the object for which the standard controls do not
735
kAudioControlPropertyScope = $63736370 (* 'cscp' *);
736
kAudioControlPropertyElement = $63656C6D (* 'celm' *);
737
kAudioControlPropertyVariant = $63766172 (* 'cvar' *);
740
@enum AudioLevelControl Properties
741
@abstract AudioObjectPropertySelector values that apply to all AudioLevelControls.
742
@discussion AudioLevelControl is a subclass of AudioControl and has only the single scope,
743
kAudioObjectPropertyScopeGlobal, and only a master element.
744
@constant kAudioLevelControlPropertyScalarValue
745
A Float32 that represents the value of the boot chime volume control. The
746
range is between 0.0 and 1.0 (inclusive).
747
@constant kAudioLevelControlPropertyDecibelValue
748
A Float32 that represents the value of the boot chime volume control in dB.
749
@constant kAudioLevelControlPropertyDecibelRange
750
An AudioValueRange that contains the minimum and maximum dB values the
751
boot chime control can have.
752
@constant kAudioLevelControlPropertyConvertScalarToDecibels
753
A Float32 that on input contains a scalar volume value for the boot chime
754
and on exit contains the equivalent dB value.
755
@constant kAudioLevelControlPropertyConvertDecibelsToScalar
756
A Float32 that on input contains a dB volume value for the boot chime and on
757
exit contains the equivalent scalar value.
760
kAudioLevelControlPropertyScalarValue = $6C637376 (* 'lcsv' *);
761
kAudioLevelControlPropertyDecibelValue = $6C636476 (* 'lcdv' *);
762
kAudioLevelControlPropertyDecibelRange = $6C636472 (* 'lcdr' *);
763
kAudioLevelControlPropertyConvertScalarToDecibels = $6C637364 (* 'lcsd' *);
764
kAudioLevelControlPropertyConvertDecibelsToScalar = $6C636473 (* 'lcds' *);
767
@enum AudioBooleanControl Properties
768
@abstract AudioObjectPropertySelector values that apply to all AudioBooleanControls.
769
@discussion AudioBooleanControl is a subclass of AudioControl and has only the single scope,
770
kAudioObjectPropertyScopeGlobal, and only a master element.
771
@constant kAudioBooleanControlPropertyValue
772
A UInt32 where 0 means false and 1 means true.
775
kAudioBooleanControlPropertyValue = $6263766C (* 'bcvl' *);
778
@enum AudioSelectorControl Properties
779
@abstract AudioObjectPropertySelector values that apply to all AudioSelectorControls.
780
@discussion AudioSelectorControl is a subclass of AudioControl and has only the single
781
scope, kAudioObjectPropertyScopeGlobal, and only a master element.
782
@constant kAudioSelectorControlPropertyCurrentItem
783
A UInt32 that is the ID of the item currently selected.
784
@constant kAudioSelectorControlPropertyAvailableItems
785
An array of UInt32s that represent the IDs of all the items available.
786
@constant kAudioSelectorControlPropertyItemName
787
This property translates the given item ID into a human readable name. The
788
qualifier contains the ID of the item to be translated and name is returned
789
as a CFString as the property data. The caller is responsible for releasing
790
the returned CFObject.
793
kAudioSelectorControlPropertyCurrentItem = $73636369 (* 'scci' *);
794
kAudioSelectorControlPropertyAvailableItems = $73636169 (* 'scai' *);
795
kAudioSelectorControlPropertyItemName = $7363696E (* 'scin' *);
798
@enum AudioClockSourceControl Properties
799
@abstract AudioObjectPropertySelector values that apply only to AudioClockSourceControls.
800
@discussion These properties supplement the regular AudioSelectorControl Properties.
801
@constant kAudioClockSourceControlPropertyItemKind
802
This property returns a UInt32 that identifies the kind of clock source
803
the item ID refers to. The qualifier contains the ID of the item. Values for
804
this property are defined in <IOAudio/audio/IOAudioTypes.h>.
807
kAudioClockSourceControlPropertyItemKind = $636C6B6B (* 'clkk' *);
810
@enum AudioStereoPanControl Properties
811
@abstract AudioObjectPropertySelector values that apply to all AudioStereoPanControls.
812
@discussion AudioStereoPanControl is a subclass of AudioControl and has only the single
813
scope, kAudioObjectPropertyScopeGlobal, and only a master element.
814
@constant kAudioStereoPanControlPropertyValue
815
A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center.
816
@constant kAudioStereoPanControlPropertyPanningChannels
817
An array of two UInt32s that indicate which elements of the owning object
818
the signal is being panned between.
821
kAudioStereoPanControlPropertyValue = $73706376 (* 'spcv' *);
822
kAudioStereoPanControlPropertyPanningChannels = $73706363 (* 'spcc' *);
824
//==================================================================================================
825
//#pragma mark AudioSystemObject Types
828
@typedef AudioHardwarePropertyID
829
@abstract An AudioHardwarePropertyID is a integer that identifies a specific piece of
830
information about the AudioSystemObject.
833
AudioHardwarePropertyID = AudioObjectPropertySelector;
836
@typedef AudioHardwarePropertyListenerProc
837
@abstract Clients register an AudioHardwarePropertyListenerProc with the AudioSystemObject
838
in order to receive notifications when the properties of the object change.
839
@discussion Note that the same functionality is provided by AudioObjectPropertyListenerProc.
841
The AudioHardwarePropertyID of the property that changed.
843
A pointer to client data established when the listener proc was registered
844
with the AudioSystemObject.
845
@result The return value is currently unused and should always be 0.
848
AudioHardwarePropertyListenerProc = function( inPropertyID: AudioHardwarePropertyID; inClientData: UnivPtr ): OSStatus;
850
//==================================================================================================
851
//#pragma mark AudioSystemObject Constants
854
@enum AudioSystemObject Class Constants
855
@abstract Various constants related to the AudioSystemObject.
856
@constant kAudioSystemObjectClassID
857
The AudioClassID that identifies the AudioSystemObject class.
858
@constant kAudioObjectSystemObject
859
The AudioObjectID that always refers to the one and only instance of the
863
kAudioSystemObjectClassID = $61737973 (* 'asys' *);
864
kAudioObjectSystemObject = 1;
866
//==================================================================================================
867
//#pragma mark AudioSystemObject Properties
870
@enum AudioSystemObject Properties
871
@abstract AudioObjectPropertySelector values that apply to the AudioSystemObject.
872
@discussion The AudioSystemObject has one scope, kAudioObjectPropertyScopeGlobal, and only a
874
@constant kAudioHardwarePropertyProcessIsMaster
875
A UInt32 where 1 means that the current process contains the master instance
876
of the HAL. The master instance of the HAL is the only instance in which
877
plug-ins should save/restore their devices' settings.
878
@constant kAudioHardwarePropertyIsInitingOrExiting
879
A UInt32 whose value will be non-zero if the HAL is either in the midst of
880
initializing or in the midst of exiting the process.
881
@constant kAudioHardwarePropertyDevices
882
An array of the AudioDeviceIDs that represent all the devices currently
883
available to the system.
884
@constant kAudioHardwarePropertyDefaultInputDevice
885
The AudioDeviceID of the default input AudioDevice.
886
@constant kAudioHardwarePropertyDefaultOutputDevice
887
The AudioDeviceID of the default output AudioDevice.
888
@constant kAudioHardwarePropertyDefaultOutputDevice
889
The AudioDeviceID of the output AudioDevice to use for system related sound
890
from the alert sound to digital call progress.
891
@constant kAudioHardwarePropertyDeviceForUID
892
Using an AudioValueTranslation structure, this property translates the input
893
CFStringRef containing a UID into the AudioDeviceID that refers to the
894
AudioDevice with that UID. This property will return kAudioDeviceUnknown if
895
the given UID does not match any currently available AudioDevice.
896
@constant kAudioHardwarePropertySleepingIsAllowed
897
A UInt32 where 1 means that the process will allow the CPU to idle sleep
898
even if there is audio IO in progress. A 0 means that the CPU will not be
899
allowed to idle sleep. Note that this property won't affect when the CPU is
901
@constant kAudioHardwarePropertyUnloadingIsAllowed
902
A UInt32 where 1 means that this process wants the HAL to unload itself
903
after a period of inactivity where there are no IOProcs and no listeners
904
registered with any AudioObject.
905
@constant kAudioHardwarePropertyHogModeIsAllowed
906
A UInt32 where 1 means that this process wants the HAL to automatically take
907
hog mode and 0 means that the HAL should not automatically take hog mode on
908
behalf of the process. Processes that only ever use the default device are
909
the sort of that should set this property's value to 0.
910
@constant kAudioHardwarePropertyRunLoop
911
The CFRunLoopRef the HAL is currently attaching all of it's system
912
notification handlers to. By default, the HAL will create and manage it's
913
own thread for this job. Clients can set this property to tell the HAL to
914
use a thread of the client's choosing. The caller is responsible for
915
releasing the returned CFObject.
916
@constant kAudioHardwarePropertyPlugInForBundleID
917
Using an AudioValueTranslation structure, this property translates the input
918
CFString containing a bundle ID into the AudioObjectID of the AudioPlugIn
919
that corresponds to it. This property will return kAudioObjectUnkown if the
920
given bundle ID doesn't match any AudioPlugIns.
923
kAudioHardwarePropertyProcessIsMaster = $6D617374 (* 'mast' *);
924
kAudioHardwarePropertyIsInitingOrExiting = $696E6F74 (* 'inot' *);
925
kAudioHardwarePropertyDevices = $64657623 (* 'dev#' *);
926
kAudioHardwarePropertyDefaultInputDevice = $64496E20 (* 'dIn ' *);
927
kAudioHardwarePropertyDefaultOutputDevice = $644F7574 (* 'dOut' *);
928
kAudioHardwarePropertyDefaultSystemOutputDevice = $734F7574 (* 'sOut' *);
929
kAudioHardwarePropertyDeviceForUID = $64756964 (* 'duid' *);
930
kAudioHardwarePropertySleepingIsAllowed = $736C6570 (* 'slep' *);
931
kAudioHardwarePropertyUnloadingIsAllowed = $756E6C64 (* 'unld' *);
932
kAudioHardwarePropertyHogModeIsAllowed = $686F6772 (* 'hogr' *);
933
kAudioHardwarePropertyRunLoop = $726E6C70 (* 'rnlp' *);
934
kAudioHardwarePropertyPlugInForBundleID = $70696269 (* 'pibi' *);
937
@enum AudioSystemObject Properties Implemented via AudioControl objects
938
@abstract AudioObjectPropertySelector values for AudioSystemObject properties that are
939
implemented by AudioControl objects.
940
@discussion These properties are also accessible by locating the AudioControl object
941
attached to the AudioSystemObject and using that object to access the properties
943
@constant kAudioHardwarePropertyBootChimeVolumeScalar
944
A Float32 that represents the value of the boot chime volume control. The
945
range is between 0.0 and 1.0 (inclusive). This property is implemented by an
946
AudioControl object that is a subclass of AudioBootChimeVolumeControl.
947
@constant kAudioHardwarePropertyBootChimeVolumeDecibels
948
A Float32 that represents the value of the boot chime volume control in dB.
949
This property is implemented by an AudioControl object that is a subclass
950
of AudioBootChimeVolumeControl.
951
@constant kAudioHardwarePropertyBootChimeVolumeRangeDecibels
952
An AudioValueRange that contains the minimum and maximum dB values the
953
boot chime control can have. This property is implemented by an AudioControl
954
object that is a subclass of AudioBootChimeVolumeControl.
955
@constant kAudioHardwarePropertyBootChimeVolumeScalarToDecibels
956
A Float32 that on input contains a scalar volume value for the boot chime
957
and on exit contains the equivalent dB value. This property is implemented
958
by an AudioControl object that is a subclass of AudioBootChimeVolumeControl.
959
@constant kAudioHardwarePropertyBootChimeVolumeDecibelsToScalar
960
A Float32 that on input contains a dB volume value for the boot chime and on
961
exit contains the equivalent scalar value. This property is implemented by
962
an AudioControl object that is a subclass of AudioBootChimeVolumeControl.
965
kAudioHardwarePropertyBootChimeVolumeScalar = $62627673 (* 'bbvs' *);
966
kAudioHardwarePropertyBootChimeVolumeDecibels = $62627664 (* 'bbvd' *);
967
kAudioHardwarePropertyBootChimeVolumeRangeDecibels = $62626423 (* 'bbd#' *);
968
kAudioHardwarePropertyBootChimeVolumeScalarToDecibels = $62763264 (* 'bv2d' *);
969
kAudioHardwarePropertyBootChimeVolumeDecibelsToScalar = $62643276 (* 'bd2v' *);
971
//==================================================================================================
972
//#pragma mark AudioSystemObject Functions
975
@functiongroup AudioSystemObject
979
@function AudioHardwareAddRunLoopSource
980
@abstract Add the given CFRunLoopSource to the the HAL's notification CFRunLoop.
981
@discussion The CFRunLoop the HAL uses for notifications is specified by
982
kAudioHardwarePropertyRunLoop. If kAudioHardwarePropertyRunLoop changes,
983
CFRunLoopSources added with this function will automatically be transferred to
985
@param inRunLoopSource
986
The CFRunLoopSource to add.
987
@result An OSStatus indicating success or failure.
989
function AudioHardwareAddRunLoopSource( inRunLoopSource: CFRunLoopSourceRef ): OSStatus; external name '_AudioHardwareAddRunLoopSource';
990
(* AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER *)
993
@function AudioHardwareRemoveRunLoopSource
994
@abstract Remove the given CFRunLoopSource from the the HAL's notification CFRunLoop.
995
@discussion The CFRunLoop the HAL uses for notifications is specified by
996
kAudioHardwarePropertyRunLoop.
997
@param inRunLoopSource
998
The CFRunLoopSource to remove.
999
@result An OSStatus indicating success or failure.
1001
function AudioHardwareRemoveRunLoopSource( inRunLoopSource: CFRunLoopSourceRef ): OSStatus; external name '_AudioHardwareRemoveRunLoopSource';
1002
(* AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER *)
1005
@function AudioHardwareUnload
1006
@abstract When this routine is called, all IO on all devices within a process will be
1007
terminated and all resources capable of being released will be released. This
1008
routine essentially returns the HAL to it's uninitialized state.
1009
@result An OSStatus indicating success or failure.
1011
function AudioHardwareUnload: OSStatus; external name '_AudioHardwareUnload';
1012
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
1015
@function AudioHardwareGetPropertyInfo
1016
@abstract Retrieve information about the given property.
1017
@discussion Note that the same functionality is provided by the functions
1018
AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and
1019
AudioObjectGetPropertyDataSize().
1021
The AudioHardwarePropertyID of the property to query.
1023
A pointer to a UInt32 that receives the size of the property data in bytes
1024
on exit. This can be NULL if the size information is not being requested.
1026
A pointer to a Boolean that receives indication of whether or not the given
1027
property can be set. This can be NULL if the writability is not being
1029
@result An OSStatus indicating success or failure.
1031
function AudioHardwareGetPropertyInfo( inPropertyID: AudioHardwarePropertyID; outSize: UInt32Ptr; outWritable: BooleanPtr ): OSStatus; external name '_AudioHardwareGetPropertyInfo';
1032
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1035
@function AudioHardwareGetProperty
1036
@abstract Queries an the AudioSystemObject to get the data of the given property and
1037
places it in the provided buffer.
1038
@discussion Note that the same functionality is provided by the function
1039
AudioObjectGetPropertyData().
1041
The AudioHardwarePropertyID of the property to query.
1043
A UInt32 which on entry indicates the size of the buffer pointed to by
1044
outData and on exit indicates how much of the buffer was used.
1046
The buffer into which the AudioSystemObject will put the data for the given
1048
@result An OSStatus indicating success or failure.
1050
function AudioHardwareGetProperty( inPropertyID: AudioHardwarePropertyID; var ioPropertyDataSize: UInt32; outPropertyData: UnivPtr ): OSStatus; external name '_AudioHardwareGetProperty';
1051
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1054
@function AudioHardwareSetProperty
1055
@abstract Tells the AudioSystemObject to change the value of the given property using the
1057
@discussion Note that the value of the property should not be considered changed until the
1058
HAL has called the listeners as many properties values are changed
1059
asynchronously. Also note that the same functionality is provided by the
1060
function AudioObjectGetPropertyData().
1062
The AudioHardwarePropertyID of the property to change.
1064
A UInt32 indicating the size of the buffer pointed to by inData.
1066
The buffer containing the data to be used to change the property's value.
1067
@result An OSStatus indicating success or failure.
1069
function AudioHardwareSetProperty( inPropertyID: AudioHardwarePropertyID; inPropertyDataSize: UInt32; inPropertyData: {const} UnivPtr ): OSStatus; external name '_AudioHardwareSetProperty';
1070
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1073
@function AudioHardwareAddPropertyListener
1074
@abstract Registers the given AudioHardwarePropertyListenerProc to receive notifications
1075
when the given property changes.
1076
@discussion Note that the same functionality is provided by AudioObjectAddPropertyListener
1077
in conjunction with AudioObjectPropertyListenerProc.
1079
The AudioHardwarePropertyID of the property to listen to.
1081
AudioHardwarePropertyListenerProc to call.
1083
A pointer to client data that is passed to the listener when it is called.
1084
@result An OSStatus indicating success or failure.
1086
function AudioHardwareAddPropertyListener( inPropertyID: AudioHardwarePropertyID; inProc: AudioHardwarePropertyListenerProc; inClientData: UnivPtr ): OSStatus; external name '_AudioHardwareAddPropertyListener';
1087
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1090
@function AudioHardwareRemovePropertyListener
1091
@abstract Unregisters the given AudioHardwarePropertyListenerProc from receive
1092
notifications when the given property changes.
1093
@discussion Note that the same functionality is provided by
1094
AudioObjectRemovePropertyListener in conjunction with
1095
AudioObjectPropertyListenerProc.
1097
The AudioHardwarePropertyID of the property to stop listening to.
1099
AudioHardwarePropertyListenerProc to unregister.
1100
@result An OSStatus indicating success or failure.
1102
function AudioHardwareRemovePropertyListener( inPropertyID: AudioHardwarePropertyID; inProc: AudioHardwarePropertyListenerProc ): OSStatus; external name '_AudioHardwareRemovePropertyListener';
1103
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1105
//==================================================================================================
1106
//#pragma mark AudioPlugIn Constants
1109
@enum AudioPlugIn Class Constants
1110
@abstract Various constants related to AudioPlugIns.
1111
@constant kAudioPlugInClassID
1112
The AudioClassID that identifies the AudioPlugIn class.
1115
kAudioPlugInClassID = $61706C67 (* 'aplg' *);
1117
//==================================================================================================
1118
//#pragma mark AudioPlugIn Properties
1121
@enum AudioPlugIn Properties
1122
@abstract AudioObjectPropertySelector values that apply to AudioPlugIns.
1123
@discussion AudioPlugIn is a subclass of AudioObject that represents a plug-in loaded by the
1124
HAL that conforms to the API in <CoreAudio/AudioHardwarePlugIn.h>. AudioPlugIns
1125
have one scope, kAudioObjectPropertyScopeGlobal, and only a master element.
1126
@constant kAudioPlugInPropertyBundleID
1127
A CFString that contains the bundle identifier for the AudioPlugIn. The
1128
caller is responsible for releasing the returned CFObject.
1129
@constant kAudioPlugInCreateAggregateDevice
1130
This property is used to tell a plug-in to create a new
1131
AudioAggregateDevice. It's value is only read. The qualifier data for this
1132
property is a CFDictionary containing a description of the
1133
AudioAggregateDevice to create. The keys for the CFDictionary are defined in
1134
the AudioAggregateDevice Constants section. The value of the property that
1135
gets returned is the AudioObjectID of the newly created device.
1136
@constant kAudioPlugInDestroyAggregateDevice
1137
This property is used to tell a plug-in to destroy an AudioAggregateDevice.
1138
Like kAudioPlugInCreateAggregateDevice, this property is read only. The
1139
value of the property is the AudioObjectID of the AudioAggregateDevice to
1143
kAudioPlugInPropertyBundleID = $70696964 (* 'piid' *);
1144
kAudioPlugInCreateAggregateDevice = $63616767 (* 'cagg' *);
1145
kAudioPlugInDestroyAggregateDevice = $64616767 (* 'dagg' *);
1147
//==================================================================================================
1148
//#pragma mark AudioDevice Types
1151
@typedef AudioDeviceID
1152
@abstract AudioDevice is the base class for all objects that represent an audio device.
1153
@discussion AudioDevice is a subclass of AudioObject. AudioDevices normally contain
1154
AudioStreams and AudioControls, but may contain other things depending on the
1155
kind of AudioDevice (e.g. aggregate devices contain other AudioDevices).
1158
AudioDeviceID = AudioObjectID;
1161
@typedef AudioDevicePropertyID
1162
@abstract An AudioDevicePropertyID is an integer that identifies a specific piece of
1163
information about the object.
1166
AudioDevicePropertyID = AudioObjectPropertySelector;
1169
@struct AudioHardwareIOProcStreamUsage
1170
@abstract This structure describes which streams a given AudioDeviceIOProc will use. It is
1171
used in conjunction with kAudioDevicePropertyIOProcStreamUsage.
1173
The IOProc whose stream usage is being specified.
1174
@field mNumberStreams
1175
The number of streams being specified.
1177
An array of UInt32's whose length is specified by mNumberStreams. Each
1178
element of the array corresponds to a stream. A value of 0 means the stream
1179
is not to be enabled. Any other value means the stream is to be used.
1182
AudioHardwareIOProcStreamUsage = record
1184
mNumberStreams: UInt32;
1185
mStreamIsOn: array[0..0] of UInt32;
1189
@typedef AudioDeviceIOProc
1190
@abstract An AudioDeviceIOProc is called by an AudioDevice to provide input data read from
1191
the device and collect output data to be written to the device for the current
1194
The AudioDevice doing the IO.
1196
An AudioTimeStamp that indicates the IO cycle started. Note that this time
1197
includes any scheduling latency that may have been incurred waking the
1198
thread on which IO is being done.
1200
An AudioBufferList containing the input data for the current IO cycle. For
1201
streams that are disabled, the AudioBuffer's mData field will be NULL but
1202
the mDataByteSize field will still say how much data would have been there
1203
if it was enabled. Note that the contents of this structure should never be
1206
An AudioTimeStamp that indicates the time at which the first frame in the
1207
data was acquired from the hardware. If the device has no input streams, the
1208
time stamp will be zeroed out.
1209
@param outOutputData
1210
An AudioBufferList in which the output data for the current IO cycle is to
1211
be placed. On entry, each AudioBuffer's mDataByteSize field indicates the
1212
maximum amount of data that can be placed in the buffer and the buffer's
1213
memory has been zeroed out. For formats where the number of bytes per packet
1214
can vary (as with AC-3, for example), the client has to fill out on exit
1215
each mDataByteSize field in each AudioBuffer with the amount of data that
1216
was put in the buffer. Otherwise, the mDataByteSize field should not be
1217
changed. For streams that are disabled, the AudioBuffer's mData field will
1218
be NULL but the mDataByteSize field will still say how much data would have
1219
been there if it was enabled. Except as noted above, the contents of this
1220
structure should not other wise be modified.
1222
An AudioTimeStamp that indicates the time at which the first frame in the
1223
data will be passed to the hardware. If the device has no output streams,
1224
the time stamp will be zeroed out.
1226
A pointer to client data established when the AudioDeviceIOProc was
1227
registered with the AudioDevice.
1228
@result The return value is currently unused and should always be 0.
1231
AudioDeviceIOProc = function( inDevice: AudioDeviceID; const (*var*) inNow: AudioTimeStamp; const (*var*) inInputData: AudioBufferList; const (*var*) inInputTime: AudioTimeStamp; var outOutputData: AudioBufferList; const (*var*) inOutputTime: AudioTimeStamp; inClientData: UnivPtr ): OSStatus;
1234
@typedef AudioDevicePropertyListenerProc
1235
@abstract Clients register an AudioDevicePropertyListenerProc with the AudioDevice object
1236
in order to receive notifications when the properties of the object change.
1237
@discussion Note that the same functionality is provided by AudioObjectPropertyListenerProc.
1239
The AudioDevice whose property has changed.
1241
The channel of the property that changed where 0 is the master channel.
1243
Which section of the AudioDevice changed.
1245
The AudioDevicePropertyID of the property that changed.
1247
A pointer to client data established when the listener proc was registered
1249
@result The return value is currently unused and should always be 0.
1252
AudioDevicePropertyListenerProc = function( inDevice: AudioDeviceID; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; inClientData: UnivPtr ): OSStatus;
1254
//==================================================================================================
1255
//#pragma mark AudioDevice Constants
1258
@enum AudioDevice Class Constants
1259
@abstract Various constants related to AudioDevices.
1260
@constant kAudioDevicePropertyScopeInput
1261
The AudioObjectPropertyScope for properties that apply to the input signal
1262
paths of the AudioDevice.
1263
@constant kAudioDevicePropertyScopeOutput
1264
The AudioObjectPropertyScope for properties that apply to the output signal
1265
paths of the AudioDevice.
1266
@constant kAudioDevicePropertyScopePlayThrough
1267
The AudioObjectPropertyScope for properties that apply to the play through
1268
signal paths of the AudioDevice.
1269
@constant kAudioDeviceClassID
1270
The AudioClassID that identifies the AudioDevice class.
1271
@constant kAudioDeviceUnknown
1272
The AudioObjectID for a nonexistent AudioObject.
1275
kAudioDevicePropertyScopeInput = $696E7074 (* 'inpt' *);
1276
kAudioDevicePropertyScopeOutput = $6F757470 (* 'outp' *);
1277
kAudioDevicePropertyScopePlayThrough = $70747275 (* 'ptru' *);
1278
kAudioDeviceClassID = $61646576 (* 'adev' *);
1279
kAudioDeviceUnknown = kAudioObjectUnknown;
1282
@enum StartAtTime/GetNearestStartTime Flags
1283
@abstract The flags that can be passed to control the behavior of AudioDeviceStartAtTime()
1284
andAudioDeviceGetNearestStartTime().
1285
@constant kAudioDeviceStartTimeIsInputFlag
1286
Set to indicate that the requested time refers to an input time. Clear to
1287
indicate that it is an output time.
1288
@constant kAudioDeviceStartTimeDontConsultDeviceFlag
1289
Set to indicate that the device should not be consulted when determining the
1290
start time. Clear to indicate that the device should be consulted. This flag
1291
cannot be set if kAudioDeviceStartTimeDontConsultHALFlag is set.
1292
@constant kAudioDeviceStartTimeDontConsultHALFlag
1293
Set to indicate that the HAL should not be consulted when determining the
1294
start time. Clear to indicate that the HAL should be consulted. This flag
1295
cannot be set if kAudioDeviceStartTimeDontConsultDeviceFlag is set.
1298
kAudioDeviceStartTimeIsInputFlag = 1 shl 0;
1299
kAudioDeviceStartTimeDontConsultDeviceFlag = 1 shl 1;
1300
kAudioDeviceStartTimeDontConsultHALFlag = 1 shl 2;
1302
//==================================================================================================
1303
//#pragma mark AudioDevice Properties
1306
@enum AudioDevice Properties
1307
@abstract AudioObjectPropertySelector values that apply to AudioDevice objects.
1308
@discussion AudioDevices have four scopes: kAudioDevicePropertyScopeGlobal,
1309
kAudioDevicePropertyScopeInput, kAudioDevicePropertyScopeOutput, and
1310
kAudioDevicePropertyScopePlayThrough. They have a master element and an element
1311
for each channel in each stream numbered according to the starting channel
1312
number of each stream.
1313
@constant kAudioDevicePropertyPlugIn
1314
An OSStatus that contains any error codes generated by loading the IOAudio
1315
driver plug-in for the AudioDevice or kAudioHardwareNoError if the plug-in
1316
loaded successfully. This property only exists for IOAudio-based
1317
AudioDevices whose driver has specified a plug-in to load.
1318
@constant kAudioDevicePropertyConfigurationApplication
1319
A CFString that contains the bundle ID for an application that provides a
1320
GUI for configuring the AudioDevice. By default, the value of this property
1321
is the bundle ID for Audio MIDI Setup. The caller is responsible for
1322
releasing the returned CFObject.
1323
@constant kAudioDevicePropertyDeviceUID
1324
A CFString that contains a persistent identifier for the AudioDevice. An
1325
AudioDevice's UID is persistent across boots. The content of the UID string
1326
is a black box and may contain information that is unique to a particular
1327
instance of an AudioDevice's hardware or unique to the CPU. Therefore they
1328
are not suitable for passing between CPUs or for identifying similar models
1330
@constant kAudioDevicePropertyModelUID
1331
A CFString that contains a persistent identifier for the model of an
1332
AudioDevice. The identifier is unique such that the identifier from two
1333
AudioDevices are equal if and only if the two AudioDevices are the exact
1334
same model from the same manufacturer. Further, the identifier has to be the
1335
same no matter on what machine the AudioDevice appears.
1336
@constant kAudioDevicePropertyTransportType
1337
A UInt32 whose value indicates how the AudioDevice is connected to the CPU.
1338
Constants for some of the values for this property can be found in
1339
<IOKit/audio/IOAudioTypes.h>.
1340
@constant kAudioDevicePropertyRelatedDevices
1341
An array of AudioDeviceIDs for devices related to the AudioDevice. For
1342
IOAudio-based devices, a AudioDevices are related if they share the same
1343
IOAudioDevice object.
1344
@constant kAudioDevicePropertyClockDomain
1345
A UInt32 whose value indicates the clock domain to which this AudioDevice
1346
belongs. AudioDevices that have the same value for this property are able to
1347
be synchronized in hardware. However, a value of 0 indicates that the clock
1348
domain for the device is unspecified and should be assumed to be separate
1349
from every other device's clock domain, even if they have the value of 0 as
1350
their clock domain as well.
1351
@constant kAudioDevicePropertyDeviceIsAlive
1352
A UInt32 where a value of 1 means the device is ready and available and 0
1353
means the device is usable and will most likely go away shortly.
1354
@constant kAudioDevicePropertyDeviceHasChanged
1355
The type of this property is a UInt32, but it's value has no meaning. This
1356
property exists so that clients can listen to it and be told when the
1357
configuration of the AudioDevice has changed in ways that cannot otherwise
1358
be conveyed through other notifications. In response to this notification,
1359
clients should re-evaluate everything they need to know about the device,
1360
particularly the layout and values of the controls.
1361
@constant kAudioDevicePropertyDeviceIsRunning
1362
A UInt32 where a value of 0 means the AudioDevice is not performing IO and
1363
a value of 1 means that it is. Note that the device can be running even if
1364
there are no active IOProcs such as by calling AudioDeviceStart() and
1365
passing a NULL IOProc. Note that the notification for this property is
1366
usually sent from the AudioDevice's IO thread.
1367
@constant kAudioDevicePropertyDeviceIsRunningSomewhere
1368
A UInt32 where 1 means that the AudioDevice is running in at least one
1369
process on the system and 0 means that it isn't running at all.
1370
@constant kAudioDevicePropertyDeviceCanBeDefaultDevice
1371
A UInt32 where 1 means that the AudioDevice is a possible selection for
1372
kAudioHardwarePropertyDefaultInputDevice or
1373
kAudioHardwarePropertyDefaultOutputDevice depending on the scope.
1374
@constant kAudioDevicePropertyDeviceCanBeDefaultSystemDevice
1375
A UInt32 where 1 means that the AudioDevice is a possible selection for
1376
kAudioHardwarePropertyDefaultSystemOutputDevice.
1377
@constant kAudioDeviceProcessorOverload
1378
A UInt32 where the value has no meaning. This property exists so that
1379
clients can be notified when the AudioDevice detects that an IO cycle has
1380
run past it's deadline. Note that the notification for this property is
1381
usually sent from the AudioDevice's IO thread.
1382
@constant kAudioDevicePropertyHogMode
1383
A pid_t indicating the process that currently owns exclusive access to the
1384
AudioDevice or a value of -1 indicating that the device is currently
1385
available to all processes. If the AudioDevice is in a non-mixable mode,
1386
the HAL will automatically take hog mode on behalf of the first process to
1388
@constant kAudioDevicePropertyLatency
1389
A UInt32 containing the number of frames of latency in the AudioDevice. Note
1390
that input and output latency may differ. Further, the AudioDevice's
1391
AudioStreams may have additional latency so they should be queried as well.
1392
If both the device and the stream say they have latency, then the total
1393
latency for the stream is the device latency summed with the stream latency.
1394
@constant kAudioDevicePropertyBufferFrameSize
1395
A UInt32 whose value indicates the number of frames in the IO buffers.
1396
@constant kAudioDevicePropertyBufferFrameSizeRange
1397
An AudioValueRange indicating the minimum and maximum values, inclusive, for
1398
kAudioDevicePropertyBufferFrameSize.
1399
@constant kAudioDevicePropertyUsesVariableBufferFrameSizes
1400
A UInt32 that, if implemented by a device, indicates that the sizes of the
1401
buffers passed to an IOProc will vary by a small amount. The value of this
1402
property will indicate the largest buffer that will be passed and
1403
kAudioDevicePropertyBufferFrameSize will indicate the smallest buffer that
1404
will get passed to the IOProc. The usage of this property is narrowed to
1405
only allow for devices whose buffer sizes vary by small amounts greater than
1406
kAudioDevicePropertyBufferFrameSize. It is not intended to be a license for
1407
devices to be able to send buffers however they please. Rather, it is
1408
intended to allow for hardware whose natural rhythms lead to this necessity.
1409
@constant kAudioDevicePropertyStreams
1410
An array of AudioStreamIDs that represent the AudioStreams of the
1411
AudioDevice. Note that if a notification is received for this property, any
1412
cached AudioStreamIDs for the device become invalid and need to be
1414
@constant kAudioDevicePropertySafetyOffset
1415
A UInt32 whose value indicates the number for frames in ahead (for output)
1416
or behind (for input the current hardware position that is safe to do IO.
1417
@constant kAudioDevicePropertyIOCycleUsage
1418
A Float32 whose range is from 0 to 1. This value indicates how much of the
1419
client portion of the IO cycle the process will use. The client portion of
1420
the IO cycle is the portion of the cycle in which the device calls the
1421
IOProcs so this property does not the apply to the duration of the entire
1423
@constant kAudioDevicePropertyStreamConfiguration
1424
This property returns the stream configuration of the device in an
1425
AudioBufferList (with the buffer pointers set to NULL) which describes the
1426
list of streams and the number of channels in each stream. This corresponds
1427
to what will be passed into the IOProc.
1428
@constant kAudioDevicePropertyIOProcStreamUsage
1429
An AudioHardwareIOProcStreamUsage structure which details the stream usage
1430
of a given IO proc. If a stream is marked as not being used, the given
1431
IOProc will see a corresponding NULL buffer pointer in the AudioBufferList
1432
passed to it's IO proc. Note that the number of streams detailed in the
1433
AudioHardwareIOProcStreamUsage must include all the streams of that
1434
direction on the device. Also, when getting the value of the property, one
1435
must fill out the mIOProc field of the AudioHardwareIOProcStreamUsage with
1436
the address of the of the IOProc whose stream usage is to be retrieved.
1437
@constant kAudioDevicePropertyPreferredChannelsForStereo
1438
An array of two UInt32s, the first for the left channel, the second for the
1439
right channel, that indicate the channel numbers to use for stereo IO on the
1440
device. The value of this property can be different for input and output and
1441
there are no restrictions on the channel numbers that can be used.
1442
@constant kAudioDevicePropertyPreferredChannelLayout
1443
An AudioChannelLayout that indicates how each channel of the AudioDevice
1445
@constant kAudioDevicePropertyNominalSampleRate
1446
A Float64 that indicates the current nominal sample rate of the AudioDevice.
1447
@constant kAudioDevicePropertyAvailableNominalSampleRates
1448
An array of AudioValueRange structs that indicates the valid ranges for the
1449
nominal sample rate of the AudioDevice.
1450
@constant kAudioDevicePropertyActualSampleRate
1451
A Float64 that indicates the current actual sample rate of the AudioDevice
1452
as measured by it's time stamps.
1455
kAudioDevicePropertyPlugIn = $706C7567 (* 'plug' *);
1456
kAudioDevicePropertyConfigurationApplication = $63617070 (* 'capp' *);
1457
kAudioDevicePropertyDeviceUID = $75696420 (* 'uid ' *);
1458
kAudioDevicePropertyModelUID = $6D756964 (* 'muid' *);
1459
kAudioDevicePropertyTransportType = $7472616E (* 'tran' *);
1460
kAudioDevicePropertyRelatedDevices = $616B696E (* 'akin' *);
1461
kAudioDevicePropertyClockDomain = $636C6B64 (* 'clkd' *);
1462
kAudioDevicePropertyDeviceIsAlive = $6C69766E (* 'livn' *);
1463
kAudioDevicePropertyDeviceHasChanged = $64696666 (* 'diff' *);
1464
kAudioDevicePropertyDeviceIsRunning = $676F696E (* 'goin' *);
1465
kAudioDevicePropertyDeviceIsRunningSomewhere = $676F6E65 (* 'gone' *);
1466
kAudioDevicePropertyDeviceCanBeDefaultDevice = $64666C74 (* 'dflt' *);
1467
kAudioDevicePropertyDeviceCanBeDefaultSystemDevice = $73666C74 (* 'sflt' *);
1468
kAudioDeviceProcessorOverload = $6F766572 (* 'over' *);
1469
kAudioDevicePropertyHogMode = $6F696E6B (* 'oink' *);
1470
kAudioDevicePropertyLatency = $6C746E63 (* 'ltnc' *);
1471
kAudioDevicePropertyBufferFrameSize = $6673697A (* 'fsiz' *);
1472
kAudioDevicePropertyBufferFrameSizeRange = $66737A23 (* 'fsz#' *);
1473
kAudioDevicePropertyUsesVariableBufferFrameSizes = $7666737A (* 'vfsz' *);
1474
kAudioDevicePropertyStreams = $73746D23 (* 'stm#' *);
1475
kAudioDevicePropertySafetyOffset = $73616674 (* 'saft' *);
1476
kAudioDevicePropertyIOCycleUsage = $6E637963 (* 'ncyc' *);
1477
kAudioDevicePropertyStreamConfiguration = $736C6179 (* 'slay' *);
1478
kAudioDevicePropertyIOProcStreamUsage = $73757365 (* 'suse' *);
1479
kAudioDevicePropertyPreferredChannelsForStereo = $64636832 (* 'dch2' *);
1480
kAudioDevicePropertyPreferredChannelLayout = $73726E64 (* 'srnd' *);
1481
kAudioDevicePropertyNominalSampleRate = $6E737274 (* 'nsrt' *);
1482
kAudioDevicePropertyAvailableNominalSampleRates = $6E737223 (* 'nsr#' *);
1483
kAudioDevicePropertyActualSampleRate = $61737274 (* 'asrt' *);
1486
@enum AudioDevice Properties Implemented via AudioControl objects
1487
@abstract AudioObjectPropertySelector values for AudioDevice properties that are
1488
implemented by AudioControl objects.
1489
@discussion These properties are also accessible by locating the AudioControl object
1490
attached to the AudioDevice and using that object to access the properties of
1492
@constant kAudioDevicePropertyJackIsConnected
1493
A UInt32 where a value of 0 means that there isn't anything plugged into the
1494
jack associated withe given element and scope. This property is implemented
1495
by an AudioJackControl, a subclass of AudioBooleanControl.
1496
@constant kAudioDevicePropertyVolumeScalar
1497
A Float32 that represents the value of the volume control. The range is
1498
between 0.0 and 1.0 (inclusive). This property is implemented by an
1499
AudioControl object that is a subclass of AudioVolumeControl.
1500
@constant kAudioDevicePropertyVolumeDecibels
1501
A Float32 that represents the value of the volume control in dB. This
1502
property is implemented by an AudioControl object that is a subclass of
1504
@constant kAudioDevicePropertyVolumeRangeDecibels
1505
An AudioValueRange that contains the minimum and maximum dB values the
1506
control can have. This property is implemented by an AudioControl object
1507
that is a subclass of AudioVolumeControl.
1508
@constant kAudioDevicePropertyVolumeScalarToDecibels
1509
A Float32 that on input contains a scalar volume value for the and on exit
1510
contains the equivalent dB value. This property is implemented by an
1511
AudioControl object that is a subclass of AudioVolumeControl.
1512
@constant kAudioDevicePropertyVolumeDecibelsToScalar
1513
A Float32 that on input contains a dB volume value for the and on exit
1514
contains the equivalent scalar value. This property is implemented by an
1515
AudioControl object that is a subclass of AudioVolumeControl.
1516
@constant kAudioDevicePropertyStereoPan
1517
A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center. This
1518
property is implemented by an AudioControl object that is a subclass of
1519
AudioStereoPanControl.
1520
@constant kAudioDevicePropertyStereoPanChannels
1521
An array of two UInt32s that indicate which elements of the owning object
1522
the signal is being panned between. This property is implemented by an
1523
AudioControl object that is a subclass of AudioStereoPanControl.
1524
@constant kAudioDevicePropertyMute
1525
A UInt32 where a value of 1 means that mute is enabled making that element
1526
inaudible. The property is implemented by an AudioControl object that is a
1527
subclass of AudioMuteControl.
1528
@constant kAudioDevicePropertySolo
1529
A UInt32 where a value of 1 means that just that element is audible and the
1530
other elements are inaudible. The property is implemented by an AudioControl
1531
object that is a subclass of AudioSoloControl.
1532
@constant kAudioDevicePropertyDataSource
1533
A UInt32 whose value is the item ID for the currently selected data source.
1534
This property is implemented by an AudioControl object that is a subclass of
1535
AudioDataSourceControl.
1536
@constant kAudioDevicePropertyDataSources
1537
An array of UInt32s that are represent all the IDs of all the data sources
1538
currently available. This property is implemented by an AudioControl object
1539
that is a subclass of AudioDataSourceControl.
1540
@constant kAudioDevicePropertyDataSourceNameForIDCFString
1541
This property translates the given data source item ID into a human readable
1542
name using an AudioValueTranslation structure. The input data is the UInt32
1543
containing the item ID to translated and the output data is a CFString. The
1544
caller is responsible for releasing the returned CFObject. This property is
1545
implemented by an AudioControl object that is a subclass of
1546
AudioDataSourceControl.
1547
@constant kAudioDevicePropertyClockSource
1548
A UInt32 whose value is the item ID for the currently selected clock source.
1549
This property is implemented by an AudioControl object that is a subclass of
1551
@constant kAudioDevicePropertyClockSources
1552
An array of UInt32s that are represent all the IDs of all the clock sources
1553
currently available. This property is implemented by an AudioControl object
1554
that is a subclass of AudioClockControl.
1555
@constant kAudioDevicePropertyClockSourceNameForIDCFString
1556
This property translates the given clock source item ID into a human
1557
readable name using an AudioValueTranslation structure. The input data is
1558
the UInt32 containing the item ID to translated and the output data is a
1559
CFString. The caller is responsible for releasing the returned CFObject.
1560
This property is implemented by an AudioControl object that is a subclass of
1562
@constant kAudioDevicePropertyClockSourceKindForID
1563
This property returns a UInt32 that identifies the kind of clock source
1564
the item ID refers to using an AudioValueTranslation structure. The input
1565
data is the UInt32 containing the item ID and the output data is the UInt32.
1566
Values for this property are defined in <IOAudio/audio/IOAudioTypes.h>.
1567
@constant kAudioDevicePropertyPlayThru
1568
A UInt32 where a value of 0 means that play through is off and a value of 1
1569
means that it is on. This property is implemented by an AudioControl object
1570
that is a subclass of AudioMuteControl. Further, the control that implements
1571
this property is only available through
1572
kAudioDevicePropertyScopePlayThrough.
1573
@constant kAudioDevicePropertyPlayThruSolo
1574
A UInt32 where a value of 1 means that just that play through element is
1575
audible and the other elements are inaudible. The property is implemented by
1576
an AudioControl object that is a subclass of AudioSoloControl. Further, the
1577
control that implements this property is only available through
1578
kAudioDevicePropertyScopePlayThrough.
1579
@constant kAudioDevicePropertyPlayThruVolumeScalar
1580
A Float32 that represents the value of the volume control. The range is
1581
between 0.0 and 1.0 (inclusive). This property is implemented by an
1582
AudioControl object that is a subclass of AudioVolumeControl.Further, the
1583
control that implements this property is only available through
1584
kAudioDevicePropertyScopePlayThrough.
1585
@constant kAudioDevicePropertyPlayThruVolumeDecibels
1586
A Float32 that represents the value of the volume control in dB. This
1587
property is implemented by an AudioControl object that is a subclass of
1588
AudioVolumeControl. Further, the control that implements this property is
1589
only available through kAudioDevicePropertyScopePlayThrough.
1590
@constant kAudioDevicePropertyPlayThruVolumeRangeDecibels
1591
An AudioValueRange that contains the minimum and maximum dB values the
1592
control can have. This property is implemented by an AudioControl object
1593
that is a subclass of AudioVolumeControl. Further, the control that
1594
implements this property is only available through
1595
kAudioDevicePropertyScopePlayThrough.
1596
@constant kAudioDevicePropertyPlayThruVolumeScalarToDecibels
1597
A Float32 that on input contains a scalar volume value for the and on exit
1598
contains the equivalent dB value. This property is implemented by an
1599
AudioControl object that is a subclass of AudioVolumeControl. Further, the
1600
control that implements this property is only available through
1601
kAudioDevicePropertyScopePlayThrough.
1602
@constant kAudioDevicePropertyPlayThruVolumeDecibelsToScalar
1603
A Float32 that on input contains a dB volume value for the and on exit
1604
contains the equivalent scalar value. This property is implemented by an
1605
AudioControl object that is a subclass of AudioVolumeControl. Further, the
1606
control that implements this property is only available through
1607
kAudioDevicePropertyScopePlayThrough.
1608
@constant kAudioDevicePropertyPlayThruStereoPan
1609
A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center. This
1610
property is implemented by an AudioControl object that is a subclass of
1611
AudioStereoPanControl. Further, the control that implements this property is
1612
only available through kAudioDevicePropertyScopePlayThrough.
1613
@constant kAudioDevicePropertyPlayThruStereoPanChannels
1614
An array of two UInt32s that indicate which elements of the owning object
1615
the signal is being panned between. This property is implemented by an
1616
AudioControl object that is a subclass of AudioStereoPanControl. Further,
1617
the control that implements this property is only available through
1618
kAudioDevicePropertyScopePlayThrough.
1619
@constant kAudioDevicePropertyPlayThruDestination
1620
A UInt32 whose value is the item ID for the currently selected play through
1621
data destination. This property is implemented by an AudioControl object
1622
that is a subclass of AudioDataDestinationControl. Further, the control that
1623
implements this property is only available through
1624
kAudioDevicePropertyScopePlayThrough.
1625
@constant kAudioDevicePropertyPlayThruDestinations
1626
An array of UInt32s that are represent all the IDs of all the play through
1627
data destinations currently available. This property is implemented by an
1628
AudioControl object that is a subclass of AudioDataDestinationControl.
1629
Further, the control that implements this property is only available through
1630
kAudioDevicePropertyScopePlayThrough.
1631
@constant kAudioDevicePropertyPlayThruDestinationNameForIDCFString
1632
This property translates the given play through data destination item ID
1633
into a human readable name using an AudioValueTranslation structure. The
1634
input data is the UInt32 containing the item ID to translated and the output
1635
data is a CFString. The caller is responsible for releasing the returned
1636
CFObject. This property is implemented by an AudioControl object that is a
1637
subclass of AudioDataDestinationControl. Further, the control that
1638
implements this property is only available through
1639
kAudioDevicePropertyScopePlayThrough.
1640
@constant kAudioDevicePropertyChannelNominalLineLevel
1641
A UInt32 whose value is the item ID for the currently selected nominal line
1642
level. This property is implemented by an AudioControl object that is a
1643
subclass of AudioLineLevelControl.
1644
@constant kAudioDevicePropertyChannelNominalLineLevels
1645
An array of UInt32s that represent all the IDs of all the nominal line
1646
levels currently available. This property is implemented by an AudioControl
1647
object that is a subclass of AudioLineLevelControl.
1648
@constant kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString
1649
This property translates the given nominal line level item ID into a human
1650
readable name using an AudioValueTranslation structure. The input data is
1651
the UInt32 containing the item ID to be translated and the output data is a
1652
CFString. The caller is responsible for releasing the returned CFObject.
1653
This property is implemented by an AudioCOntrol object that is a subclass of
1654
AudioLineLevelControl.
1655
@constant kAudioDevicePropertyDriverShouldOwniSub
1656
A UInt32 where a value of 0 means that the AudioDevice should not claim
1657
ownership of any attached iSub and a value of 1 means that it should. Note
1658
that this property is only available for built-in devices and for USB Audio
1659
devices that use the standard class compliant driver. This property is
1660
implemented by an AudioControl object that is a subclass of
1661
AudioISubOwnerControl.
1662
@constant kAudioDevicePropertySubVolumeScalar
1663
A Float32 that represents the value of the LFE volume control. The range is
1664
between 0.0 and 1.0 (inclusive). This property is implemented by an
1665
AudioControl object that is a subclass of AudioLFEVolumeControl.
1666
@constant kAudioDevicePropertySubVolumeDecibels
1667
A Float32 that represents the value of the LFE volume control in dB. This
1668
property is implemented by an AudioControl object that is a subclass of
1669
AudioLFE VolumeControl.
1670
@constant kAudioDevicePropertySubVolumeRangeDecibels
1671
An AudioValueRange that contains the minimum and maximum dB values the
1672
control can have. This property is implemented by an AudioControl object
1673
that is a subclass of AudioLFEVolumeControl.
1674
@constant kAudioDevicePropertySubVolumeScalarToDecibels
1675
A Float32 that on input contains a scalar volume value for the and on exit
1676
contains the equivalent dB value. This property is implemented by an
1677
AudioControl object that is a subclass of AudioLFEVolumeControl.
1678
@constant kAudioDevicePropertySubVolumeDecibelsToScalar
1679
A Float32 that on input contains a dB volume value for the and on exit
1680
contains the equivalent scalar value. This property is implemented by an
1681
AudioControl object that is a subclass of AudioLFEVolumeControl.
1682
@constant kAudioDevicePropertySubMute
1683
A UInt32 where a value of 1 means that mute is enabled making the LFE on
1684
that element inaudible. The property is implemented by an AudioControl
1685
object that is a subclass of AudioLFEMuteControl.
1688
kAudioDevicePropertyJackIsConnected = $6A61636B (* 'jack' *);
1689
kAudioDevicePropertyVolumeScalar = $766F6C6D (* 'volm' *);
1690
kAudioDevicePropertyVolumeDecibels = $766F6C64 (* 'vold' *);
1691
kAudioDevicePropertyVolumeRangeDecibels = $76646223 (* 'vdb#' *);
1692
kAudioDevicePropertyVolumeScalarToDecibels = $76326462 (* 'v2db' *);
1693
kAudioDevicePropertyVolumeDecibelsToScalar = $64623276 (* 'db2v' *);
1694
kAudioDevicePropertyStereoPan = $7370616E (* 'span' *);
1695
kAudioDevicePropertyStereoPanChannels = $73706E23 (* 'spn#' *);
1696
kAudioDevicePropertyMute = $6D757465 (* 'mute' *);
1697
kAudioDevicePropertySolo = $736F6C6F (* 'solo' *);
1698
kAudioDevicePropertyDataSource = $73737263 (* 'ssrc' *);
1699
kAudioDevicePropertyDataSources = $73736323 (* 'ssc#' *);
1700
kAudioDevicePropertyDataSourceNameForIDCFString = $6C73636E (* 'lscn' *);
1701
kAudioDevicePropertyClockSource = $63737263 (* 'csrc' *);
1702
kAudioDevicePropertyClockSources = $63736323 (* 'csc#' *);
1703
kAudioDevicePropertyClockSourceNameForIDCFString = $6C63736E (* 'lcsn' *);
1704
kAudioDevicePropertyClockSourceKindForID = $6373636B (* 'csck' *);
1705
kAudioDevicePropertyPlayThru = $74687275 (* 'thru' *);
1706
kAudioDevicePropertyPlayThruSolo = $74687273 (* 'thrs' *);
1707
kAudioDevicePropertyPlayThruVolumeScalar = $6D767363 (* 'mvsc' *);
1708
kAudioDevicePropertyPlayThruVolumeDecibels = $6D766462 (* 'mvdb' *);
1709
kAudioDevicePropertyPlayThruVolumeRangeDecibels = $6D766423 (* 'mvd#' *);
1710
kAudioDevicePropertyPlayThruVolumeScalarToDecibels = $6D763264 (* 'mv2d' *);
1711
kAudioDevicePropertyPlayThruVolumeDecibelsToScalar = $6D763273 (* 'mv2s' *);
1712
kAudioDevicePropertyPlayThruStereoPan = $6D73706E (* 'mspn' *);
1713
kAudioDevicePropertyPlayThruStereoPanChannels = $6D737023 (* 'msp#' *);
1714
kAudioDevicePropertyPlayThruDestination = $6D646473 (* 'mdds' *);
1715
kAudioDevicePropertyPlayThruDestinations = $6D646423 (* 'mdd#' *);
1716
kAudioDevicePropertyPlayThruDestinationNameForIDCFString = $6D646463 (* 'mddc' *);
1717
kAudioDevicePropertyChannelNominalLineLevel = $6E6C766C (* 'nlvl' *);
1718
kAudioDevicePropertyChannelNominalLineLevels = $6E6C7623 (* 'nlv#' *);
1719
kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString = $6C636E6C (* 'lcnl' *);
1720
kAudioDevicePropertyDriverShouldOwniSub = $69737562 (* 'isub' *);
1721
kAudioDevicePropertySubVolumeScalar = $73766C6D (* 'svlm' *);
1722
kAudioDevicePropertySubVolumeDecibels = $73766C64 (* 'svld' *);
1723
kAudioDevicePropertySubVolumeRangeDecibels = $73766423 (* 'svd#' *);
1724
kAudioDevicePropertySubVolumeScalarToDecibels = $73763264 (* 'sv2d' *);
1725
kAudioDevicePropertySubVolumeDecibelsToScalar = $73643276 (* 'sd2v' *);
1726
kAudioDevicePropertySubMute = $736D7574 (* 'smut' *);
1729
@enum AudioDevice Properties That Ought To Some Day Be Deprecated
1730
@abstract AudioObjectPropertySelector values whose functionality is better provided by
1732
@discussion These selectors are still provided for backward compatibility. The description
1733
of the property will indicate in parentheses the better selectors to use and
1735
@constant kAudioDevicePropertyDeviceName
1736
A C-string that contains the human readable name of the AudioDevice.
1737
(kAudioObjectPropertyName: CFStrings are better for localization.)
1738
@constant kAudioDevicePropertyDeviceNameCFString
1739
A CFStringRef that contains the human readable name of the AudioDevice. The
1740
caller is responsible for releasing the returned CFObject.
1741
(kAudioObjectPropertyName: This is just another name for the inherited
1743
@constant kAudioDevicePropertyDeviceManufacturer
1744
A C-string that contains the human readable name of the manufacturer of the
1746
(kAudioObjectPropertyManufacturer: CFStrings are better for localization.)
1747
@constant kAudioDevicePropertyDeviceManufacturerCFString
1748
A CFString that contains the human readable name of the manufacturer of the
1749
AudioDevice. The caller is responsible for releasing the returned CFObject.
1750
(kAudioObjectPropertyManufacturer: This is just another name for the
1751
inherited selector.)
1752
@constant kAudioDevicePropertyRegisterBufferList
1753
This property allows clients to register a fully populated AudioBufferList
1754
that matches the topology described by
1755
kAudioDevicePropertyStreamConfiguration for doing input using
1756
AudioDeviceRead(). The AudioBufferList will be registered with the call the
1757
AudioDeviceSetProperty() and will be unregistered with the call to
1758
AudioDeviceGetProperty(). If this property isn't implemented by the
1759
AudioDevice, it implies that the AudioDevice also doesn't support
1761
(Aggregate devices make AudioDeviceRead() obsolete for the most part.)
1762
@constant kAudioDevicePropertyBufferSize
1763
A UInt32 containing the size in bytes of the IO buffer for the AudioStream
1764
containing the element.
1765
(kAudioDevicePropertyBufferFrameSize: with multiple AudioStreams and the
1766
requirement that all streams' buffers represent the same amount of time, it
1767
doesn't make sense to set the buffer size in bytes since it will be
1768
different for each stream.)
1769
@constant kAudioDevicePropertyBufferSizeRange
1770
An AudioValueRange specifying the minimum and maximum bytes size for the
1771
IO buffer for the AudioStream containing the given element.
1772
(kAudioDevicePropertyBufferFrameSizeRange: see
1773
kAudioDevicePropertyBufferSize.)
1774
@constant kAudioDevicePropertyChannelName
1775
A CFString that contains a human readable name for the given element in the
1776
given scope. The caller is responsible for releasing the returned CFObject.
1777
(kAudioObjectPropertyElementName: CFStrings are better for
1779
@constant kAudioDevicePropertyChannelNameCFString
1780
A CFString that contains a human readable name for the given element in the
1781
given scope. The caller is responsible for releasing the returned CFObject.
1782
(kAudioObjectPropertyElementName: This is just another name for the
1783
inherited selector.)
1784
@constant kAudioDevicePropertyChannelCategoryName
1785
A CFString that contains a human readable name for the category of the given
1786
element in the given scope. The caller is responsible for releasing the
1788
(kAudioObjectPropertyElementCategoryName: CFStrings are better for
1790
@constant kAudioDevicePropertyChannelCategoryNameCFString
1791
A CFString that contains a human readable name for the category of the given
1792
element in the given scope. The caller is responsible for releasing the
1794
(kAudioObjectPropertyElementCategoryName: This is just another name for the
1795
inherited selector.)
1796
@constant kAudioDevicePropertyChannelNumberName
1797
A CFString that contains a human readable name for the number of the given
1798
element in the given scope. The caller is responsible for releasing the
1800
(kAudioObjectPropertyElementNumberName: CFStrings are better for
1802
@constant kAudioDevicePropertyChannelNumberNameCFString
1803
A CFString that contains a human readable name for the number of the given
1804
element in the given scope. The caller is responsible for releasing the
1806
(kAudioObjectPropertyElementNumberName: This is just another name for the
1807
inherited selector.)
1808
@constant kAudioDevicePropertySupportsMixing
1809
A UInt32 where a value of 1 means the AudioDevice supports mixing and a
1810
value of 0 means that it doesn't and that all IO is performed in each
1811
AudioStream's current physical format. This property is changed indirectly
1812
by changing to a format that doesn't support mixing, such as AC-3. (The HAL
1813
now vends it's format information with a flag indicating the mixability in
1814
order to better support devices with streams that are both mixable and non-
1816
@constant kAudioDevicePropertyStreamFormat
1817
An AudioStreamBasicDescription that describes the current data format for
1818
the AudioStream that contains the channel referred to by the element number.
1819
(kAudioStreamPropertyVirtualFormat: Managing format information is
1820
inherently an operation on AudioStreams, rather than AudioDevices. It is
1821
confusing for the client to work with formats at the AudioDevice level and
1822
has been shown to lead to programming mistakes by clients when working with
1823
devices that have multiple streams.)
1824
@constant kAudioDevicePropertyStreamFormats
1825
An array of AudioStreamBasicDescriptions that describe the available data
1826
formats for the AudioStream that contains the channel referred to by the
1828
(kAudioStreamPropertyAvailableVirtualFormats: Managing format information is
1829
inherently an operation on AudioStreams, rather than AudioDevices. It is
1830
confusing for the client to work with formats at the AudioDevice level and
1831
has been shown to lead to programming mistakes by clients when working with
1832
devices that have multiple streams.)
1833
@constant kAudioDevicePropertyStreamFormatSupported
1834
An AudioStreamBasicDescription is passed in to query whether or not the
1835
format is supported. A kAudioDeviceUnsupportedFormatError will be returned
1836
if the format is not supported and kAudioHardwareNoError will be returned if
1837
it is supported. AudioStreamBasicDescription fields set to 0 will be ignored
1838
in the query, but otherwise values must match exactly.
1839
(kAudioStreamPropertyAvailableVirtualFormats: The proper and most robust way
1840
to find a format that the AudioStream can support is to get the list of
1841
available formats and look through that rather than using this property.)
1842
@constant kAudioDevicePropertyStreamFormatMatch
1843
An AudioStreamBasicDescription is passed in and the AudioStream will modify
1844
it to describe the best match, in the AudioDevice's opinion, for the given
1846
(kAudioStreamPropertyAvailableVirtualFormats: The proper and most robust way
1847
to find a format that the AudioStream can support is to get the list of
1848
available formats and look through that rather than using this property.)
1849
@constant kAudioDevicePropertyDataSourceNameForID
1850
This property translates the given data source item ID into a human readable
1851
name using an AudioValueTranslation structure. The input data is the UInt32
1852
holding the item ID to be translated and the output data is a buffer to hold
1853
the name as a null terminated c-string.
1854
(kAudioDevicePropertyDataSourceNameForIDCFString: CFStrings are better for
1856
@constant kAudioDevicePropertyClockSourceNameForID
1857
This property translates the given clock source item ID into a human
1858
readable name using an AudioValueTranslation structure. The input data is
1859
the UInt32 holding the item ID to be translated and the output data is a
1860
buffer to hold the name as a null terminated c-string.
1861
(kAudioDevicePropertyClockSourceNameForIDCFString: CFStrings are better for
1863
@constant kAudioDevicePropertyPlayThruDestinationNameForID
1864
This property translates the given play through destination item ID into a
1865
human readable name using an AudioValueTranslation structure. The input data
1866
is the UInt32 holding the item ID to be translated and the output data is a
1867
buffer to hold the name as a null terminated c-string.
1868
(kAudioDevicePropertyPlayThruDestinationNameForIDCFString: CFStrings are
1869
better for localization.)
1870
@constant kAudioDevicePropertyChannelNominalLineLevelNameForID
1871
This property translates the given nominal line level item ID into a human
1872
readable name using an AudioValueTranslation structure. The input data is
1873
the UInt32 holding the item ID to be translated and the output data is a
1874
buffer to hold the name as a null terminated c-string.
1875
(kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString: CFStrings are
1876
better for localization.)
1879
kAudioDevicePropertyDeviceName = $6E616D65 (* 'name' *);
1880
kAudioDevicePropertyDeviceNameCFString = kAudioObjectPropertyName;
1881
kAudioDevicePropertyDeviceManufacturer = $6D616B72 (* 'makr' *);
1882
kAudioDevicePropertyDeviceManufacturerCFString = kAudioObjectPropertyManufacturer;
1883
kAudioDevicePropertyRegisterBufferList = $72627566 (* 'rbuf' *);
1884
kAudioDevicePropertyBufferSize = $6273697A (* 'bsiz' *);
1885
kAudioDevicePropertyBufferSizeRange = $62737A23 (* 'bsz#' *);
1886
kAudioDevicePropertyChannelName = $63686E6D (* 'chnm' *);
1887
kAudioDevicePropertyChannelNameCFString = kAudioObjectPropertyElementName;
1888
kAudioDevicePropertyChannelCategoryName = $63636E6D (* 'ccnm' *);
1889
kAudioDevicePropertyChannelCategoryNameCFString = kAudioObjectPropertyElementCategoryName;
1890
kAudioDevicePropertyChannelNumberName = $636E6E6D (* 'cnnm' *);
1891
kAudioDevicePropertyChannelNumberNameCFString = kAudioObjectPropertyElementNumberName;
1892
kAudioDevicePropertySupportsMixing = $6D69783F (* 'mix?' *);
1893
kAudioDevicePropertyStreamFormat = $73666D74 (* 'sfmt' *);
1894
kAudioDevicePropertyStreamFormats = $73666D23 (* 'sfm#' *);
1895
kAudioDevicePropertyStreamFormatSupported = $73666D3F (* 'sfm?' *);
1896
kAudioDevicePropertyStreamFormatMatch = $73666D6D (* 'sfmm' *);
1897
kAudioDevicePropertyDataSourceNameForID = $7373636E (* 'sscn' *);
1898
kAudioDevicePropertyClockSourceNameForID = $6373636E (* 'cscn' *);
1899
kAudioDevicePropertyPlayThruDestinationNameForID = $6D64646E (* 'mddn' *);
1900
kAudioDevicePropertyChannelNominalLineLevelNameForID = $636E6C76 (* 'cnlv' *);
1902
//==================================================================================================
1903
//#pragma mark AudioDevice Functions
1906
@functiongroup AudioDevice
1910
@function AudioDeviceAddIOProc
1911
@abstract Registers the given AudioDeviceIOProc with the AudioDevice.
1912
@discussion A client may have multiple IOProcs for a given device, but the device is free to
1913
only accept as many as it can handle. Note that it is not recommended for
1914
clients to have more than a single IOProc registered at a time as this can be
1915
wasteful of system resources. Rather, it is recommended that the client do any
1916
necessary mixing itself so that only one IOProc is necessary.
1918
The AudioDevice to register the IOProc with.
1920
The AudioDeviceIOProc to register.
1922
A pointer to client data that is passed back to the IOProc when it is
1924
@result An OSStatus indicating success or failure.
1926
function AudioDeviceAddIOProc( inDevice: AudioDeviceID; inProc: AudioDeviceIOProc; inClientData: UnivPtr ): OSStatus; external name '_AudioDeviceAddIOProc';
1927
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1930
@function AudioDeviceRemoveIOProc
1931
@abstract Unregisters the given AudioDeviceIOProc from the AudioDevice.
1933
The AudioDevice to unregister the IOProc from.
1935
The AudioDeviceIOProc to unregister.
1936
@result An OSStatus indicating success or failure.
1938
function AudioDeviceRemoveIOProc( inDevice: AudioDeviceID; inProc: AudioDeviceIOProc ): OSStatus; external name '_AudioDeviceRemoveIOProc';
1939
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1942
@function AudioDeviceStart
1943
@abstract Starts IO for the given AudioDeviceIOProc.
1945
The AudioDevice to start the IOProc on.
1947
The AudioDeviceIOProc to start. Note that this can be NULL, which starts the
1948
hardware regardless of whether or not there are any IOProcs registered. This
1949
is necessary if any of the AudioDevice's timing services are to be used. A
1950
balancing call to AudioDeviceStop with a NULL IOProc is required to stop the
1952
@result An OSStatus indicating success or failure.
1954
function AudioDeviceStart( inDevice: AudioDeviceID; inProc: AudioDeviceIOProc ): OSStatus; external name '_AudioDeviceStart';
1955
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1958
@function AudioDeviceStartAtTime
1959
@abstract Starts IO for the given AudioDeviceIOProc and aligns the IO cycle of the
1960
AudioDevice with the given time.
1962
The AudioDevice to start the IOProc on.
1964
The AudioDeviceIOProc to start. Note that this can be NULL, which starts the
1965
hardware regardless of whether or not there are any IOProcs registered.
1966
@param ioRequestedStartTime
1967
A pointer to an AudioTimeStamp that, on entry, is the requested time to
1968
start the IOProc. On exit, it will be the actual time the IOProc will start.
1970
A UInt32 containing flags that modify how this function behaves.
1971
@result An OSStatus indicating success or failure.
1972
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
1973
not support starting at a specific time and inProc and ioRequestedStartTime are
1976
function AudioDeviceStartAtTime( inDevice: AudioDeviceID; inProc: AudioDeviceIOProc; ioRequestedStartTime: AudioTimeStampPtr; inFlags: UInt32 ): OSStatus; external name '_AudioDeviceStartAtTime';
1977
(* AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER *)
1980
@function AudioDeviceStop
1981
@abstract Stops IO for the given AudioDeviceIOProc.
1983
The AudioDevice to stop the IOProc on.
1985
The AudioDeviceIOProc to stop.
1986
@result An OSStatus indicating success or failure.
1988
function AudioDeviceStop( inDevice: AudioDeviceID; inProc: AudioDeviceIOProc ): OSStatus; external name '_AudioDeviceStop';
1989
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
1992
@function AudioDeviceRead
1993
@abstract Read some data from an AudioDevice starting at the given time.
1994
@discussion With the advent of aggregate devices, the need for AudioDeviceRead has gone
1995
away. Consequently, this function is a good candidate for deprecation some day.
1997
The AudioDevice to read from.
1999
An AudioTimeStamp indicating the time from which to read the data. In
2000
general, the valid range of time (in frames) is from the current time minus
2001
the maximum IO buffer size to the current time minus the safety offset.
2003
An AudioBufferList that must be the same size and shape as that returned by
2004
kAudioDevicePropertyStreamConfiguration. Further, the AudioBufferList must
2005
have been previously registered with the device via
2006
kAudioDevicePropertyRegisterBufferList. On exit, the mDataSize fields will
2007
be updated with the amount of data read.
2008
@result An OSStatus indicating success or failure.
2009
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
2010
not support direct reading.
2012
function AudioDeviceRead( inDevice: AudioDeviceID; const (*var*) inStartTime: AudioTimeStamp; var outData: AudioBufferList ): OSStatus; external name '_AudioDeviceRead';
2013
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2016
@function AudioDeviceGetCurrentTime
2017
@abstract Retrieves the current time from an AudioDevice. Note that the device has to be
2020
The AudioDevice to from which to get the time.
2022
An AudioTimeStamp into which the current time is put.
2023
@result An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
2024
returned if the AudioDevice isn't running.
2026
function AudioDeviceGetCurrentTime( inDevice: AudioDeviceID; var outTime: AudioTimeStamp ): OSStatus; external name '_AudioDeviceGetCurrentTime';
2027
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2030
@function AudioDeviceTranslateTime
2031
@abstract Translates the time in the AudioDevice's time base from one representation to
2032
another. Note that the device has to be running
2034
The AudioDevice whose time base governs the translation.
2036
An AudioTimeStamp containing the time to be translated.
2038
An AudioTimeStamp into which the translated time is put. On entry, the
2039
mFlags field specifies which representations to translate the input time
2040
into. Because not every device supports all time representations, on exit,
2041
the mFlags field will indicate which translations were actually done.
2042
@result An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
2043
returned if the AudioDevice isn't running.
2045
function AudioDeviceTranslateTime( inDevice: AudioDeviceID; const (*var*) inTime: AudioTimeStamp; var outTime: AudioTimeStamp ): OSStatus; external name '_AudioDeviceTranslateTime';
2046
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2049
@function AudioDeviceGetNearestStartTime
2050
@abstract Query an AudioDevice to get a time equal to or later than the given time that is
2051
the best time to start IO.
2052
@discussion The time that is returned is dictated by the constraints of the device and the
2053
system. For instance, the driver of a device that provides both audio and video
2054
data may only allow start times that coincide with the edge of a video frame.
2055
Also, if the device already has one or more active IOProcs, the start time will
2056
be shifted to the beginning of the next IO cycle so as not to cause
2057
discontinuities in the existing IOProcs. Another reason the start time may shift
2058
is to allow for aligning the buffer accesses in an optimal fashion. Note that
2059
the device must be running to use this function.
2061
The AudioDevice to query.
2062
@param ioRequestedStartTime
2063
A pointer to an AudioTimeStamp that, on entry, is the requested start time.
2064
On exit, it will have the a time equal to or later than the requested time,
2065
as dictated by the device's constraints.
2067
A UInt32 containing flags that modify how this function behaves.
2068
@result An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
2069
returned if the AudioDevice isn't running.
2070
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
2071
not support starting at a specific time.
2073
function AudioDeviceGetNearestStartTime( inDevice: AudioDeviceID; var ioRequestedStartTime: AudioTimeStamp; inFlags: UInt32 ): OSStatus; external name '_AudioDeviceGetNearestStartTime';
2074
(* AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER *)
2077
@function AudioDeviceGetPropertyInfo
2078
@abstract Retrieve information about the given property of an AudioDevice.
2079
@discussion Note that the same functionality is provided by the functions
2080
AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and
2081
AudioObjectGetPropertyDataSize().
2083
The AudioDevice to query.
2085
The channel of the property to query where 0 is the master channel.
2087
Which section of the AudioDevice to query.
2089
The AudioDevicePropertyID of the property to query.
2091
A pointer to a UInt32 that receives the size of the property data in bytes
2092
on exit. This can be NULL if the size information is not being requested.
2094
A pointer to a Boolean that receives indication of whether or not the given
2095
property can be set. This can be NULL if the writability is not being
2097
@result An OSStatus indicating success or failure.
2099
function AudioDeviceGetPropertyInfo( inDevice: AudioDeviceID; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; outSize: UInt32Ptr; outWritable: BooleanPtr ): OSStatus; external name '_AudioDeviceGetPropertyInfo';
2100
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2103
@function AudioDeviceGetProperty
2104
@abstract Queries an the AudioDevice object to get the data of the given property and
2105
places it in the provided buffer.
2106
@discussion Note that the same functionality is provided by the function
2107
AudioObjectGetPropertyData().
2109
The AudioDevice to query.
2111
The channel of the property to query where 0 is the master channel.
2113
Which section of the AudioDevice to query.
2115
The AudioDevicePropertyID of the property to query.
2116
@param ioPropertyDataSize
2117
A UInt32 which on entry indicates the size of the buffer pointed to by
2118
outData and on exit indicates how much of the buffer was used.
2119
@param outPropertyData
2120
The buffer into which the object will put the data for the given property.
2121
@result An OSStatus indicating success or failure.
2123
function AudioDeviceGetProperty( inDevice: AudioDeviceID; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; var ioPropertyDataSize: UInt32; outPropertyData: UnivPtr ): OSStatus; external name '_AudioDeviceGetProperty';
2124
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2127
@function AudioDeviceSetProperty
2128
@abstract Tells the AudioDevice object to change the value of the given property using the
2130
@discussion Note that the value of the property should not be considered changed until the
2131
HAL has called the listeners as many properties values are changed
2132
asynchronously. Also note that the same functionality is provided by the
2133
function AudioObjectGetPropertyData().
2135
The AudioDevice to change.
2137
A pointer to an AudioTimeStamp that says when to change the property's value
2138
relative to the device's time base. NULL means execute the change
2141
The channel of the property to change where 0 is the master channel.
2143
Which section of the AudioDevice to change.
2145
The AudioDevicePropertyID of the property to change.
2146
@param inPropertyDataSize
2147
A UInt32 indicating the size of the buffer pointed to by inData.
2148
@param inPropertyData
2149
The buffer containing the data to be used to change the property's value.
2150
@result An OSStatus indicating success or failure.
2152
function AudioDeviceSetProperty( inDevice: AudioDeviceID; inWhen: {const} AudioTimeStampPtr; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; inPropertyDataSize: UInt32; inPropertyData: {const} UnivPtr ): OSStatus; external name '_AudioDeviceSetProperty';
2153
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2156
@function AudioDeviceAddPropertyListener
2157
@abstract Registers the given AudioDevicePropertyListenerProc to receive notifications
2158
when the given property changes.
2159
@discussion Note that the same functionality is provided by AudioObjectAddPropertyListener
2160
in conjunction with AudioObjectPropertyListenerProc.
2162
The AudioDevice with whom to register the listener.
2164
The channel of the property to listen to.
2166
Which section of the AudioDevice to listen to.
2168
The AudioDevicePropertyID of the property to listen to.
2170
AudioDevicePropertyListenerProc to call.
2172
A pointer to client data that is passed to the listener when it is called.
2173
@result An OSStatus indicating success or failure.
2175
function AudioDeviceAddPropertyListener( inDevice: AudioDeviceID; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; inProc: AudioDevicePropertyListenerProc; inClientData: UnivPtr ): OSStatus; external name '_AudioDeviceAddPropertyListener';
2176
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2179
@function AudioDeviceRemovePropertyListener
2180
@abstract Unregisters the given AudioDevicePropertyListenerProc from receiving
2181
notifications when the given property changes.
2182
@discussion Note that the same functionality is provided by
2183
AudioObjectRemovePropertyListener in conjunction with
2184
AudioObjectPropertyListenerProc.
2186
The AudioDevice with whom to unregister the listener.
2188
The channel of the property to unregister from.
2190
Which section of the AudioDevice to unregister from.
2192
The AudioDevicePropertyID of the property to stop listening to.
2194
AudioDevicePropertyListenerProc to unregister.
2195
@result An OSStatus indicating success or failure.
2197
function AudioDeviceRemovePropertyListener( inDevice: AudioDeviceID; inChannel: UInt32; isInput: Boolean; inPropertyID: AudioDevicePropertyID; inProc: AudioDevicePropertyListenerProc ): OSStatus; external name '_AudioDeviceRemovePropertyListener';
2198
(* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER *)
2200
//==================================================================================================
2201
//#pragma mark AudioStream Types
2204
@typedef AudioStreamID
2205
@abstract AudioStream is the base class for all objects that represent a stream of data on
2207
@discussion AudioStream is a subclass of AudioObject and can contain AudioControls.
2210
AudioStreamID = AudioObjectID;
2213
@struct AudioStreamRangedDescription
2214
@abstract This structure allows a specific sample rate range to be associated with an
2215
AudioStreamBasicDescription that specifies it's sample rate as
2216
kAudioStreamAnyRate.
2217
@discussion Note that this structure is only used to desicribe the the available formats
2218
for a stream. It is not used for the current format.
2220
The AudioStreamBasicDescription that describes the format of the stream.
2221
Note that the mSampleRate field of the structure will be the same as the
2222
the values in mSampleRateRange when only a single sample rate is supported.
2223
It will be kAudioStreamAnyRate when there is a range with more elements.
2224
@field mSampleRateRange
2225
The AudioValueRange that describes the minimum and maximum sample rate for
2226
the stream. If the mSampleRate field of mFormat is kAudioStreamAnyRate the
2227
format supports the range of sample rates described by this structure.
2228
Otherwise, the minimum will be the same as the maximum which will be the
2229
same as the mSampleRate field of mFormat.
2232
AudioStreamRangedDescription = record
2233
mFormat: AudioStreamBasicDescription;
2234
mSampleRateRange: AudioValueRange;
2238
@typedef AudioStreamPropertyListenerProc
2239
@abstract Clients register an AudioStreamPropertyListenerProc with the AudioStream object
2240
in order to receive notifications when the properties of the object change.
2241
@discussion Note that the same functionality is provided by AudioObjectPropertyListenerProc.
2243
The AudioStream whose property has changed.
2245
The channel of the property that changed where 0 is the master channel.
2247
The AudioDevicePropertyID of the property that changed.
2249
A pointer to client data established when the listener proc was registered
2251
@result The return value is currently unused and should always be 0.
2254
AudioStreamPropertyListenerProc = function( inStream: AudioStreamID; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; inClientData: UnivPtr ): OSStatus;
2256
//==================================================================================================
2257
//#pragma mark AudioStream Constants
2260
@enum AudioStream Class Constants
2261
@abstract Various constants related to AudioStreams.
2262
@constant kAudioStreamClassID
2263
The AudioClassID that identifies the AudioStream class.
2264
@constant kAudioStreamUnknown
2265
The AudioObjectID for a nonexistent AudioObject.
2268
kAudioStreamClassID = $61737472 (* 'astr' *);
2269
kAudioStreamUnknown = kAudioObjectUnknown;
2271
//==================================================================================================
2272
//#pragma mark AudioStream Properties
2275
@enum AudioStream Properties
2276
@abstract AudioObjectPropertySelector values that apply to all AudioStreams.
2277
@discussion AudioStream is a subclass of AudioObject and has only the single scope,
2278
kAudioObjectPropertyScopeGlobal. They have a master element and an element for
2279
each channel in the stream numbered upward from 1. Note that AudioStream objects
2280
share AudioControl objects with their owning AudioDevice. Consequently, all the
2281
standard AudioControl related property selectors implemented by AudioDevices are
2282
also implemented by AudioStreams. The same constants are to be used for such
2284
@constant kAudioStreamPropertyDirection
2285
A UInt32 where a value of 0 means that this AudioStream is an output stream
2286
and a value of 1 means that it is an input stream.
2287
@constant kAudioStreamPropertyTerminalType
2288
A UInt32 whose value describes the general kind of functionality attached
2289
to the AudioStream. Constants that describe some of the values of this
2290
property are defined in <IOKit/audio/IOAudioTypes.h>
2291
@constant kAudioStreamPropertyStartingChannel
2292
A UInt32 that specifies the first element in the owning device that
2293
corresponds to element one of this stream.
2294
@constant kAudioStreamPropertyLatency
2295
A UInt32 containing the number of frames of latency in the AudioStream. Note
2296
that the owning AudioDevice may have additional latency so it should be
2297
queried as well. If both the device and the stream say they have latency,
2298
then the total latency for the stream is the device latency summed with the
2300
@constant kAudioStreamPropertyVirtualFormat
2301
An AudioStreamBasicDescription that describes the current data format for
2302
the AudioStream. The virtual format refers to the data format in which all
2303
IOProcs for the owning AudioDevice will perform IO transactions.
2304
@constant kAudioStreamPropertyAvailableVirtualFormats
2305
An array of AudioStreamRangedDescriptions that describe the available data
2306
formats for the AudioStream. The virtual format refers to the data format in
2307
which all IOProcs for the owning AudioDevice will perform IO transactions.
2308
@constant kAudioStreamPropertyPhysicalFormat
2309
An AudioStreamBasicDescription that describes the current data format for
2310
the AudioStream. The physical format refers to the data format in which the
2311
hardware for the owning AudioDevice performs it's IO transactions.
2312
@constant kAudioStreamPropertyAvailablePhysicalFormats
2313
An array of AudioStreamRangedDescriptions that describe the available data
2314
formats for the AudioStream. The physical format refers to the data format
2315
in which the hardware for the owning AudioDevice performs it's IO
2319
kAudioStreamPropertyDirection = $73646972 (* 'sdir' *);
2320
kAudioStreamPropertyTerminalType = $7465726D (* 'term' *);
2321
kAudioStreamPropertyStartingChannel = $7363686E (* 'schn' *);
2322
kAudioStreamPropertyLatency = kAudioDevicePropertyLatency;
2323
kAudioStreamPropertyVirtualFormat = $73666D74 (* 'sfmt' *);
2324
kAudioStreamPropertyAvailableVirtualFormats = $73666D61 (* 'sfma' *);
2325
kAudioStreamPropertyPhysicalFormat = $70667420 (* 'pft ' *);
2326
kAudioStreamPropertyAvailablePhysicalFormats = $70667461 (* 'pfta' *);
2330
@enum AudioStream Properties That Ought To Some Day Be Deprecated
2331
@abstract AudioObjectPropertySelector values whose functionality is better provided by
2333
@discussion These selectors are still provided for backward compatibility. The description
2334
of the property will indicate in parentheses the better selectors to use and
2336
@constant kAudioStreamPropertyOwningDevice
2337
The AudioObjectID of the AudioDevice of which this AudioStream is a part.
2338
(kAudioObjectPropertyOwner: This is just another name for the inherited
2340
@constant kAudioStreamPropertyPhysicalFormats
2341
An array of AudioStreamBasicDescriptions that describe the available data
2342
formats for the AudioStream. The physical format refers to the data format
2343
in which the hardware for the owning AudioDevice performs it's IO
2345
(kAudioStreamPropertyAvailablePhysicalFormats: The new name for this
2346
property is much clearer for readers of the API to see what is meant and the
2347
AudioStreamRangedDescription structure provides better information.)
2348
@constant kAudioStreamPropertyPhysicalFormatSupported
2349
An AudioStreamBasicDescription is passed in to query whether or not the
2350
format is supported. A kAudioDeviceUnsupportedFormatError will be returned
2351
if the format is not supported and kAudioHardwareNoError will be returned if
2352
it is supported. AudioStreamBasicDescription fields set to 0 will be ignored
2353
in the query, but otherwise values must match exactly. The physical format
2354
refers to the data format in which the hardware for the owning AudioDevice
2355
performs it's IO transactions.
2356
(kAudioStreamPropertyAvailablePhysicalFormats: The proper and most robust
2357
way to find a format that the AudioStream can support is to get the list of
2358
available formats and look through that rather than using this property.)
2359
@constant kAudioStreamPropertyPhysicalFormatMatch
2360
An AudioStreamBasicDescription is passed in and the AudioStream will modify
2361
it to describe the best match, in the AudioDevice's opinion, for the given
2362
format. The physical format refers to the data format in which the hardware
2363
for the owning AudioDevice performs it's IO transactions.
2364
(kAudioStreamPropertyAvailablePhysicalFormats: The proper and most robust
2365
way to find a format that the AudioStream can support is to get the list of
2366
available formats and look through that rather than using this property.)
2369
kAudioStreamPropertyOwningDevice = kAudioObjectPropertyOwner;
2370
kAudioStreamPropertyPhysicalFormats = $70667423 (* 'pft#' *);
2371
kAudioStreamPropertyPhysicalFormatSupported = $7066743F (* 'pft?' *);
2372
kAudioStreamPropertyPhysicalFormatMatch = $7066746D (* 'pftm' *);
2374
//==================================================================================================
2375
//#pragma mark AudioStream Functions
2378
@functiongroup AudioStream
2382
@function AudioStreamGetPropertyInfo
2383
@abstract Retrieve information about the given property of an AudioStream.
2385
The AudioStream to query.
2387
The channel of the property to query where 0 is the master channel.
2389
The AudioDevicePropertyID of the property to query.
2391
A pointer to a UInt32 that receives the size of the property data in bytes
2392
on exit. This can be NULL if the size information is not being requested.
2394
A pointer to a Boolean that receives indication of whether or not the given
2395
property can be set. This can be NULL if the writability is not being
2397
@result An OSStatus indicating success or failure.
2399
function AudioStreamGetPropertyInfo( inStream: AudioStreamID; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; var outSize: UInt32; var outWritable: Boolean ): OSStatus; external name '_AudioStreamGetPropertyInfo';
2400
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2403
@function AudioStreamGetProperty
2404
@abstract Queries an the AudioStream object to get the data of the given property and
2405
places it in the provided buffer.
2406
@discussion Note that the same functionality is provided by the function
2407
AudioObjectGetPropertyData().
2409
The AudioStream to query.
2411
The channel of the property to query where 0 is the master channel.
2413
The AudioDevicePropertyID of the property to query.
2414
@param ioPropertyDataSize
2415
A UInt32 which on entry indicates the size of the buffer pointed to by
2416
outData and on exit indicates how much of the buffer was used.
2417
@param outPropertyData
2418
The buffer into which the object will put the data for the given property.
2419
@result An OSStatus indicating success or failure.
2421
function AudioStreamGetProperty( inStream: AudioStreamID; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; var ioPropertyDataSize: UInt32; outPropertyData: UnivPtr ): OSStatus; external name '_AudioStreamGetProperty';
2422
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2425
@function AudioStreamSetProperty
2426
@abstract Tells the AudioStream object to change the value of the given property using the
2428
@discussion Note that the value of the property should not be considered changed until the
2429
HAL has called the listeners as many properties values are changed
2430
asynchronously. Also note that the same functionality is provided by the
2431
function AudioObjectGetPropertyData().
2433
The AudioStream to change.
2435
A pointer to an AudioTimeStamp that says when to change the property's value
2436
relative to the device's time base. NULL means execute the change
2439
The channel of the property to change where 0 is the master channel.
2441
The AudioDevicePropertyID of the property to change.
2442
@param inPropertyDataSize
2443
A UInt32 indicating the size of the buffer pointed to by inData.
2444
@param inPropertyData
2445
The buffer containing the data to be used to change the property's value.
2446
@result An OSStatus indicating success or failure.
2448
function AudioStreamSetProperty( inStream: AudioStreamID; inWhen: AudioTimeStampPtr; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; inPropertyDataSize: UInt32; inPropertyData: {const} UnivPtr ): OSStatus; external name '_AudioStreamSetProperty';
2449
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2452
@function AudioStreamAddPropertyListener
2453
@abstract Registers the given AudioStreamPropertyListenerProc to receive notifications
2454
when the given property changes.
2455
@discussion Note that the same functionality is provided by AudioObjectAddPropertyListener
2456
in conjunction with AudioObjectPropertyListenerProc.
2458
The AudioStream with whom to register the listener.
2460
The channel of the property to listen to.
2462
The AudioDevicePropertyID of the property to listen to.
2464
AudioStreamPropertyListenerProc to call.
2466
A pointer to client data that is passed to the listener when it is called.
2467
@result An OSStatus indicating success or failure.
2469
function AudioStreamAddPropertyListener( inStream: AudioStreamID; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; inProc: AudioStreamPropertyListenerProc; inClientData: UnivPtr ): OSStatus; external name '_AudioStreamAddPropertyListener';
2470
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2473
@function AudioStreamRemovePropertyListener
2474
@abstract Unregisters the given AudioStreamPropertyListenerProc from receiving
2475
notifications when the given property changes.
2476
@discussion Note that the same functionality is provided by
2477
AudioObjectRemovePropertyListener in conjunction with
2478
AudioObjectPropertyListenerProc.
2480
The AudioStream with whom to unregister the listener.
2482
The channel of the property to unregister from.
2484
The AudioDevicePropertyID of the property to stop listening to.
2486
AudioStreamPropertyListenerProc to unregister.
2487
@result An OSStatus indicating success or failure.
2489
function AudioStreamRemovePropertyListener( inStream: AudioStreamID; inChannel: UInt32; inPropertyID: AudioDevicePropertyID; inProc: AudioStreamPropertyListenerProc ): OSStatus; external name '_AudioStreamRemovePropertyListener';
2490
(* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER *)
2492
//==================================================================================================
2493
//#pragma mark AudioAggregateDevice Constants
2496
@enum AudioAggregateDevice Class Constants
2497
@abstract Various constants related to AudioAggregateDevices.
2498
@constant kAudioAggregateDeviceClassID
2499
The AudioClassID that identifies the AudioAggregateDevice class.
2500
@constant kAudioDeviceTransportTypeAggregate
2501
The transport type ID (see kAudioDevicePropertyTransportType) for aggregate
2503
@constant kAudioDeviceTransportTypeAutoAggregate
2504
The transport type ID (see kAudioDevicePropertyTransportType) for
2505
automatically generated aggregate devices.
2508
kAudioAggregateDeviceClassID = $61616767 (* 'aagg' *);
2509
kAudioDeviceTransportTypeAggregate = $67727570 (* 'grup' *);
2510
kAudioDeviceTransportTypeAutoAggregate = $66677270 (* 'fgrp' *);
2513
@defined kAudioAggregateDeviceUIDKey
2514
@discussion The key used in a CFDictionary that describes the composition of an
2515
AudioAggregateDevice. The value for this key is a CFString that contains the UID
2516
of the AudioAggregateDevice.
2519
kAudioAggregateDeviceUIDKey = 'uid';
2522
@defined kAudioAggregateDeviceNameKey
2523
@discussion The key used in a CFDictionary that describes the composition of an
2524
AudioAggregateDevice. The value for this key is a CFString that contains the
2525
human readable name of the AudioAggregateDevice.
2528
kAudioAggregateDeviceNameKey = 'name';
2531
@defined kAudioAggregateDeviceSubDeviceListKey
2532
@discussion The key used in a CFDictionary that describes the composition of an
2533
AudioAggregateDevice. The value for this key is a CFArray of CFDictionaries that
2534
describe each sub-device in the AudioAggregateDevice. The keys for this
2535
CFDictionary are defined in the AudioSubDevice section.
2538
kAudioAggregateDeviceSubDeviceListKey = 'subdevices';
2541
@defined kAudioAggregateDeviceMasterSubDeviceKey
2542
@discussion The key used in a CFDictionary that describes the composition of an
2543
AudioAggregateDevice. The value for this key is a CFString that contains the
2544
UID for the sub-device that is the master time source for the
2545
AudioAggregateDevice.
2548
kAudioAggregateDeviceMasterSubDeviceKey = 'master';
2551
@defined kAudioAggregateDeviceIsPrivateKey
2552
@discussion The key used in a CFDictionary that describes the composition of an
2553
AudioAggregateDevice. The value for this key is a CFNumber where a value of 0
2554
means that the AudioAggregateDevice is to be published to the entire system and
2555
a value of 1 means that the AudioAggregateDevice is private to the process that
2556
created it. Note that a private AudioAggregateDevice is not persistent across
2557
launches of the process that created it. Note that if this key is not present,
2558
it implies that the AudioAggregateDevice is published to the entire system.
2561
kAudioAggregateDeviceIsPrivateKey = 'private';
2563
//==================================================================================================
2564
//#pragma mark AudioAggregateDevice Properties
2567
@enum AudioAggregateDevice Properties
2568
@abstract AudioObjectPropertySelector values that apply to all AudioAggregateDevices.
2569
@discussion AudioAggregateDevice is a subclass of AudioDevice.
2570
@constant kAudioAggregateDevicePropertyFullSubDeviceList
2571
A CFArray of CFStrings that contain the UIDs of all the devices, active or
2572
inactive, contained in the AudioAggregateDevice. The order of the items in
2573
the array is significant and is used to determine the order of the streams
2574
of the AudioAggregateDevice. The caller is responsible for releasing the
2576
@constant kAudioAggregateDevicePropertyActiveSubDeviceList
2577
An array of AudioObjectIDs for all the active sub-devices in the aggregate
2579
@constant kAudioAggregateDevicePropertyComposition
2580
A CFDictionary that describes the composition of the AudioAggregateDevice.
2581
The keys for this CFDicitionary are defined in the AudioAggregateDevice
2585
kAudioAggregateDevicePropertyFullSubDeviceList = $67727570 (* 'grup' *);
2586
kAudioAggregateDevicePropertyActiveSubDeviceList = $61677270 (* 'agrp' *);
2587
kAudioAggregateDevicePropertyComposition = $61636F6D (* 'acom' *);
2590
@enum AudioAggregateDevice Properties Implemented via AudioControl objects
2591
@abstract AudioObjectPropertySelector values for AudioAggregateDevice properties that are
2592
implemented by AudioControl objects.
2593
@discussion These properties are also accessible by locating the AudioControl object
2594
attached to the AudioAggregateDevice and using that object to access the
2595
properties of the control.
2596
@constant kAudioAggregateDevicePropertyMasterSubDevice
2597
A CFString that contains the UID for the AudioDevice that is currently
2598
serving as the master time base of the aggregate device. This property is
2599
also implemented by the AudioClockSourceControl on the master element of the
2600
global scope of the AudioAggregateDevice.
2603
kAudioAggregateDevicePropertyMasterSubDevice = $616D7374 (* 'amst' *);
2605
//==================================================================================================
2606
//#pragma mark AudioSubDevice Constants
2609
@enum AudioSubDevice Class Constants
2610
@abstract Various constants related to AudioSubDevices.
2611
@constant kAudioSubDeviceClassID
2612
The AudioClassID that identifies the AudioSubDevice class.
2615
kAudioSubDeviceClassID = $61737562 (* 'asub' *);
2618
@enum AudioSubDevice Clock Drift Compensation Methods
2619
@abstract Constants that describe the range of values the property
2620
kAudioSubDevicePropertyDriftCompensation. It is a continuous range from
2621
kAudioSubDeviceDriftCompensationMinQuality to
2622
kAudioSubDeviceDriftCompensationMaxQuality, with some commonly used settings
2626
kAudioSubDeviceDriftCompensationMinQuality = 0;
2627
kAudioSubDeviceDriftCompensationLowQuality = $20;
2628
kAudioSubDeviceDriftCompensationMediumQuality = $40;
2629
kAudioSubDeviceDriftCompensationHighQuality = $60;
2630
kAudioSubDeviceDriftCompensationMaxQuality = $7F;
2633
@defined kAudioSubDeviceUIDKey
2634
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
2635
The value for this key is a CFString that contains the UID for the
2639
kAudioSubDeviceUIDKey = 'uid';
2641
//==================================================================================================
2642
//#pragma mark AudioSubDevice Properties
2645
@enum AudioSubDevice Properties
2646
@abstract AudioObjectPropertySelector values that apply to all AudioSubDevices.
2647
@discussion AudioSubDevice is a subclass of AudioDevice that is collected together with
2648
other sub-devices in an AudioAggregateDevice. AudioSubDevice objects do not
2649
implement an IO path nor any AudioDevice properties associated with the IO path.
2650
They also don't have any streams.
2651
@constant kAudioSubDevicePropertyExtraLatency
2652
A Float64 indicating the number of sample frames to add to or subtract from
2653
the latency compensation used for this AudioSubDevice.
2654
@constant kAudioSubDevicePropertyDriftCompensation
2655
A UInt32 where a value of 0 indicates that no drift compensation should be
2656
done for this AudioSubDevice and a value of 1 means that it should.
2657
@constant kAudioSubDevicePropertyDriftCompensationQuality
2658
A UInt32 that controls the trade-off between quality and CPU load in the
2659
drift compensation. The range of values is from 0 to 128, where the lower
2660
the number, the worse the quality but also the less CPU is used to do the
2664
kAudioSubDevicePropertyExtraLatency = $786C7463 (* 'xltc' *);
2665
kAudioSubDevicePropertyDriftCompensation = $64726674 (* 'drft' *);
2666
kAudioSubDevicePropertyDriftCompensationQuality = $64726671 (* 'drfq' *);
2668
//==================================================================================================