1 {!
2 @file AudioComponent.h
3 @framework AudioToolbox.framework
4 @copyright (c) 2007-2015 Apple, Inc. All rights reserved.
5 @brief API's to locate, get information about, and open audio components.
6
7 @discussion
8
9 This file defines a collection of APIs to find, get information about, and open
10 audio components (such as audio units, audio codecs, and audio file components).
11
12 Originally, CoreServices' Component Manager was used for the registration, discovery, and
13 packaging of these loadable code modules. However, in order to provide an API that will be
14 supported going forward from Mac OS X 10.6 and iOS 2.0, it is advised that applications use the
15 Audio Component APIs to find and load (open) audio components such as audio units.
16
17 The type "AudioComponent" or "AudioComponentInstance" should be seen and used as a distinct type
18 from the Component Manager types of "Component" and "ComponentInstance". It is never safe to
19 assume a direct cast is compatible between this type and the other.
20
21 Beginning with Mac OS X 10.7, AudioComponents can be registered and used directly without
22 involving the Component Manager. The system scans certain directories for bundles with names
23 ending in ".audiocomp" or ".component" (the latter permits registering plug-ins in a single
24 bundle with both the Component Manager and the Audio Component system). These directories are
25 scanned non-recursively:
26
27 ~/Library/Audio/Plug-Ins/Components
28 /Library/Audio/Plug-Ins/Components
29 /System/Library/Components
30
31 Bundles' Info.plist dictionaries should contain an "AudioComponents" item whose value
32 is an array of dictionaries, e.g.
33
34 @textblock
35 <key>AudioComponents</key>
36 <array>
37 <dict>
38 <key>type</key>
39 <string>aufx</string>
40 <key>subtype</key>
41 <string>XMPL</string>
42 <key>manufacturer</key>
43 <string>ACME</string>
44 <key>name</key>
45 <string>AUExample</string>
46 <key>version</key>
47 <integer>12345</integer>
48 <key>factoryFunction</key>
49 <string>AUExampleFactory</string>
50
51 <!-- An AudioComponent is sandbox safe -->
52
53 <key>sandboxSafe</key>
54 <true/>
55
56 <!-- or it can describe its resource usage -->
57
58 <key>resourceUsage</key>
59 <dict>
60 <key>iokit.user-client</key>
61 <array>
62 <string>CustomUserClient1</string>
63 <string>CustomUserClient2</string>
64 </array>
65 <key>mach-lookup.global-name</key>
66 <array>
67 <string>MachServiceName1</string>
68 <string>MachServiceName2</string>
69 </array>
70 <key>network.client</key>
71 <true/>
72 <key>temporary-exception.files.all.read-write</key>
73 </true>
74 </dict>
75
76 <!-- An AudioComponent can define its tags -->
77
78 <key>tags</key>
79 <array>
80 <string>Effect</string>
81 <string>Equalizer</string>
82 </array>
83 </dict>
84 </array>
85 @/textblock
86
87 The type, subtype and manufacturer keys correspond to the OSType fields of the
88 AudioComponentDescription structure. They can be strings if they are 4 ASCII characters;
89 otherwise they must be 32-bit integers.
90
91 The "factoryFunction" is the name of a AudioComponentFactoryFunction in the bundle's binary.
92
93
94 SANDBOX-SAFETY
95
96 The "sandboxSafe" key is used to indicate whether or not an AudioComponent can be loaded
97 directly into a sandboxed process. This key is reflected in the componentFlags field of the the
98 AudioComponentDescription for the AudioComponent with the constant,
99 kAudioComponentFlag_SandboxSafe. Note that if this key is not present, it is assumed that the
100 AudioComponent is not sandbox safe.
101
102 The "resourceUsage" key describes the system resources used by an AudioComponent that is not
103 sandbox safe. The keys for this dictionary are described below. If the "sandboxSafe" key is
104 true, this dictionary should not be included.
105
106 The "iokit.user-client" key is a "resourceUsage" key that describes the IOKit user-client
107 objects the AudioComponent will open. It is an array of the user-clients' class names.
108
109 The "mach-lookup.global-name" key is a "resourceUsage" key that describes the mach services the
110 AudioComponent needs to connect to. It is an array of the names of the services. Note that these
111 services can be direct mach services found via bootstrap_look_up() or XPC services found via
112 xpc_connection_create_mach_service().
113
114 The "network.client" key is a "resourceUsage" key that indicates that the AudioComponent will
115 receive data from the network.
116
117 The "temporary-exception.files.all.read-write" key is a "resourceUsage" key that indicates that
118 the AudioComponent needs arbitrary access to the file system. This is for backward compatibility
119 for AudioComponents that have not yet adopted the usage of security scope bookmarks and/or the
120 usage of the standard file dialog for discovering, accessing and storing persistent references
121 to files on the file system. In a future OS release, this key will not be supported.
122
123 Note that a sandbox-safe AudioComponent can function correctly in even the most severely
124 sandboxed process. This means that the process will have curtailed or no access to common system
125 resources like the file system, device drivers, the network, and communication with other
126 processes.
127
128 When instantiating a sandbox unsafe AudioComponent in a sandboxed process, the system evaluates
129 the "resourceUsage" information against the restrictions the process is under. If the
130 "resourceUsage" will not violate those restrictions, the AudioComponent will be instantiated and
131 can be used as normal. Note that the system will set kAudioComponentFlag_SandboxSafe in the
132 AudioComponentDescription in this case.
133
134 If the "resourceUsage" information includes things that can't be accessed from the process and
135 the process has the entitlement, "com.apple.security.temporary-exception.audio-unit-host", the
136 system will ask the user whether or not it is acceptable for the process to open the unsafe
137 AudioComponent. If the user says yes, the system will suspend the process's sandbox and allow
138 the unsafe AudioComponent to be opened and used.
139
140
141 TAGS
142
143 The "tags" key is an array of tags associated with the defined AudioComponent. The following are
144 the set of predefined standard tags that are localized and can be used in the audio unit
145 definition. "Equalizer", "Dynamics", "Distortion", "Synthesizer", "Effects", "Filter", "Dynamics
146 Processor", "Delay", "Reverb", "Pitch", "Panner", "Imaging", "Sampler", "Mixer", "Format
147 Converter", "Time Effect", "Output", "Offline Effect", "Drums", "Guitar", "Vocal", "Bass",
148 "MIDI".
149
150 These standard tags should not be localized in the audio unit.
151
152 Localizing the tags is similar to localizing AudioUnit parameter strings. Create a strings
153 resource file and name it "AudioUnitTags.strings".
154 For more information on strings resource file please check
155 https://developer.apple.com/library/mac/documentation/macosx/conceptual/bpinternational/Articles/StringsFiles.html
156 }
157 { Pascal Translation: Gorazd Krosl <gorazd_1957@yahoo.ca>, October 2009 }
158 { Pascal Translation Update: Jonas Maebe <jonas@freepascal.org>, October 2012 }
159 { Pascal Translation Update: Jonas Maebe <jonas@freepascal.org>, July 2019 }
160
161 {
162 Modified for use with Free Pascal
163 Version 308
164 Please report any bugs to <gpc@microbizz.nl>
165 }
166
167 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
168 {$mode macpas}
169 {$modeswitch cblocks}
170 {$packenum 1}
171 {$macro on}
172 {$inline on}
173 {$calling mwpascal}
174
175 unit AudioComponents;
176 interface
177 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
178 {$setc GAP_INTERFACES_VERSION := $0308}
179
180 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
181 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
182 {$endc}
183
184 {$ifc defined CPUPOWERPC and defined CPUI386}
185 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
186 {$endc}
187 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
188 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
189 {$endc}
190
191 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
192 {$setc __ppc__ := 1}
193 {$elsec}
194 {$setc __ppc__ := 0}
195 {$endc}
196 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
197 {$setc __ppc64__ := 1}
198 {$elsec}
199 {$setc __ppc64__ := 0}
200 {$endc}
201 {$ifc not defined __i386__ and defined CPUI386}
202 {$setc __i386__ := 1}
203 {$elsec}
204 {$setc __i386__ := 0}
205 {$endc}
206 {$ifc not defined __x86_64__ and defined CPUX86_64}
207 {$setc __x86_64__ := 1}
208 {$elsec}
209 {$setc __x86_64__ := 0}
210 {$endc}
211 {$ifc not defined __arm__ and defined CPUARM}
212 {$setc __arm__ := 1}
213 {$elsec}
214 {$setc __arm__ := 0}
215 {$endc}
216 {$ifc not defined __arm64__ and defined CPUAARCH64}
217 {$setc __arm64__ := 1}
218 {$elsec}
219 {$setc __arm64__ := 0}
220 {$endc}
221
222 {$ifc defined cpu64}
223 {$setc __LP64__ := 1}
224 {$elsec}
225 {$setc __LP64__ := 0}
226 {$endc}
227
228
229 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
230 {$error Conflicting definitions for __ppc__ and __i386__}
231 {$endc}
232
233 {$ifc defined __ppc__ and __ppc__}
234 {$setc TARGET_CPU_PPC := TRUE}
235 {$setc TARGET_CPU_PPC64 := FALSE}
236 {$setc TARGET_CPU_X86 := FALSE}
237 {$setc TARGET_CPU_X86_64 := FALSE}
238 {$setc TARGET_CPU_ARM := FALSE}
239 {$setc TARGET_CPU_ARM64 := FALSE}
240 {$setc TARGET_OS_MAC := TRUE}
241 {$setc TARGET_OS_IPHONE := FALSE}
242 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
243 {$setc TARGET_OS_EMBEDDED := FALSE}
244 {$elifc defined __ppc64__ and __ppc64__}
245 {$setc TARGET_CPU_PPC := FALSE}
246 {$setc TARGET_CPU_PPC64 := TRUE}
247 {$setc TARGET_CPU_X86 := FALSE}
248 {$setc TARGET_CPU_X86_64 := FALSE}
249 {$setc TARGET_CPU_ARM := FALSE}
250 {$setc TARGET_CPU_ARM64 := FALSE}
251 {$setc TARGET_OS_MAC := TRUE}
252 {$setc TARGET_OS_IPHONE := FALSE}
253 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
254 {$setc TARGET_OS_EMBEDDED := FALSE}
255 {$elifc defined __i386__ and __i386__}
256 {$setc TARGET_CPU_PPC := FALSE}
257 {$setc TARGET_CPU_PPC64 := FALSE}
258 {$setc TARGET_CPU_X86 := TRUE}
259 {$setc TARGET_CPU_X86_64 := FALSE}
260 {$setc TARGET_CPU_ARM := FALSE}
261 {$setc TARGET_CPU_ARM64 := FALSE}
262 {$ifc defined iphonesim}
263 {$setc TARGET_OS_MAC := FALSE}
264 {$setc TARGET_OS_IPHONE := TRUE}
265 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
266 {$elsec}
267 {$setc TARGET_OS_MAC := TRUE}
268 {$setc TARGET_OS_IPHONE := FALSE}
269 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
270 {$endc}
271 {$setc TARGET_OS_EMBEDDED := FALSE}
272 {$elifc defined __x86_64__ and __x86_64__}
273 {$setc TARGET_CPU_PPC := FALSE}
274 {$setc TARGET_CPU_PPC64 := FALSE}
275 {$setc TARGET_CPU_X86 := FALSE}
276 {$setc TARGET_CPU_X86_64 := TRUE}
277 {$setc TARGET_CPU_ARM := FALSE}
278 {$setc TARGET_CPU_ARM64 := FALSE}
279 {$ifc defined iphonesim}
280 {$setc TARGET_OS_MAC := FALSE}
281 {$setc TARGET_OS_IPHONE := TRUE}
282 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
283 {$elsec}
284 {$setc TARGET_OS_MAC := TRUE}
285 {$setc TARGET_OS_IPHONE := FALSE}
286 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
287 {$endc}
288 {$setc TARGET_OS_EMBEDDED := FALSE}
289 {$elifc defined __arm__ and __arm__}
290 {$setc TARGET_CPU_PPC := FALSE}
291 {$setc TARGET_CPU_PPC64 := FALSE}
292 {$setc TARGET_CPU_X86 := FALSE}
293 {$setc TARGET_CPU_X86_64 := FALSE}
294 {$setc TARGET_CPU_ARM := TRUE}
295 {$setc TARGET_CPU_ARM64 := FALSE}
296 {$setc TARGET_OS_MAC := FALSE}
297 {$setc TARGET_OS_IPHONE := TRUE}
298 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
299 {$setc TARGET_OS_EMBEDDED := TRUE}
300 {$elifc defined __arm64__ and __arm64__}
301 {$setc TARGET_CPU_PPC := FALSE}
302 {$setc TARGET_CPU_PPC64 := FALSE}
303 {$setc TARGET_CPU_X86 := FALSE}
304 {$setc TARGET_CPU_X86_64 := FALSE}
305 {$setc TARGET_CPU_ARM := FALSE}
306 {$setc TARGET_CPU_ARM64 := TRUE}
307 {$ifc defined ios}
308 {$setc TARGET_OS_MAC := FALSE}
309 {$setc TARGET_OS_IPHONE := TRUE}
310 {$setc TARGET_OS_EMBEDDED := TRUE}
311 {$elsec}
312 {$setc TARGET_OS_MAC := TRUE}
313 {$setc TARGET_OS_IPHONE := FALSE}
314 {$setc TARGET_OS_EMBEDDED := FALSE}
315 {$endc}
316 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
317 {$elsec}
318 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
319 {$endc}
320
321 {$ifc defined __LP64__ and __LP64__ }
322 {$setc TARGET_CPU_64 := TRUE}
323 {$elsec}
324 {$setc TARGET_CPU_64 := FALSE}
325 {$endc}
326
327 {$ifc defined FPC_BIG_ENDIAN}
328 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
329 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
330 {$elifc defined FPC_LITTLE_ENDIAN}
331 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
332 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
333 {$elsec}
334 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
335 {$endc}
336 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
337 {$setc CALL_NOT_IN_CARBON := FALSE}
338 {$setc OLDROUTINENAMES := FALSE}
339 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
340 {$setc OPAQUE_UPP_TYPES := TRUE}
341 {$setc OTCARBONAPPLICATION := TRUE}
342 {$setc OTKERNEL := FALSE}
343 {$setc PM_USE_SESSION_APIS := TRUE}
344 {$setc TARGET_API_MAC_CARBON := TRUE}
345 {$setc TARGET_API_MAC_OS8 := FALSE}
346 {$setc TARGET_API_MAC_OSX := TRUE}
347 {$setc TARGET_CARBON := TRUE}
348 {$setc TARGET_CPU_68K := FALSE}
349 {$setc TARGET_CPU_MIPS := FALSE}
350 {$setc TARGET_CPU_SPARC := FALSE}
351 {$setc TARGET_OS_UNIX := FALSE}
352 {$setc TARGET_OS_WIN32 := FALSE}
353 {$setc TARGET_RT_MAC_68881 := FALSE}
354 {$setc TARGET_RT_MAC_CFM := FALSE}
355 {$setc TARGET_RT_MAC_MACHO := TRUE}
356 {$setc TYPED_FUNCTION_POINTERS := TRUE}
357 {$setc TYPE_BOOL := FALSE}
358 {$setc TYPE_EXTENDED := FALSE}
359 {$setc TYPE_LONGLONG := TRUE}
360 uses MacTypes,CoreAudioTypes,Components,CFBase,CFDictionary;
361 {$endc} {not MACOSALLINCLUDE}
362
363 {$ALIGN POWER}
364
365
366 //=====================================================================================================================
367 //#pragma mark Overview
368
369
370 //CF_ASSUME_NONNULL_BEGIN
371
372 //=====================================================================================================================
373 //#pragma mark Constants
374
375 {!
376 @constant kAudioComponentFlag_Unsearchable
377
378 When this bit in AudioComponentDescription's componentFlags is set, AudioComponentFindNext
379 will only return this component when performing a specific, non-wildcard search for the
380 component, i.e. with non-zero values of componentType, componentSubType, and
381 componentManufacturer. This can be useful when privately registering a component.
382
383 @constant kAudioComponentFlag_SandboxSafe
384
385 An AudioComponent sets this bit in its componentFlags to indicate to the system that the
386 AudioComponent is safe to open in a sandboxed process.
387
388 @constant kAudioComponentFlag_IsV3AudioUnit
389
390 The system sets this flag automatically when registering components which implement a version 3
391 Audio Unit.
392
393 @constant kAudioComponentFlag_RequiresAsyncInstantiation
394
395 The system sets this flag automatically when registering components which require asynchronous
396 instantiation via AudioComponentInstantiate (v3 audio units with views).
397
398 @constant kAudioComponentFlag_CanLoadInProcess
399
400 The system sets this flag automatically when registering components which can be loaded into
401 the current process. This is always true for V2 audio units; it depends on the packaging
402 in the case of a V3 audio unit.
403 }
404 type
405 AudioComponentFlags = UInt32;
406 const
407 kAudioComponentFlag_Unsearchable = 1; (* CF_ENUM_AVAILABLE(10_7, 5_0) *)
408 kAudioComponentFlag_SandboxSafe = 2; (* CF_ENUM_AVAILABLE(10_8, 6_0) *)
409 kAudioComponentFlag_IsV3AudioUnit = 4; (* CF_ENUM_AVAILABLE(10_11, 9_0) *)
410 kAudioComponentFlag_RequiresAsyncInstantiation = 8; (* CF_ENUM_AVAILABLE(10_11, 9_0) *)
411 kAudioComponentFlag_CanLoadInProcess = $10; (* CF_ENUM_AVAILABLE(10_11, 9_0) *)
412
413 {! @enum AudioComponentInstantiationOptions
414 @brief Options controlling component instantiation.
415 @discussion
416 Most component instances are loaded into the calling process.
417
418 A version 3 audio unit, however, can be loaded into a separate extension service process,
419 and this is the default behavior for these components. To be able to load one in-process
420 requires that the developer package the audio unit in a bundle separate from the application
421 extension, since an extension's main binary cannot be dynamically loaded into another
422 process.
423
424 An OS X host may request in-process loading of such audio units using
425 kAudioComponentInstantiation_LoadInProcess.
426
427 kAudioComponentFlag_IsV3AudioUnit specifies whether an audio unit is implemented using API
428 version 3.
429
430 These options are just requests to the implementation. It may fail and fall back to the
431 default.
432 @constant kAudioComponentInstantiation_LoadOutOfProcess
433 Attempt to load the component into a separate extension process.
434 @constant kAudioComponentInstantiation_LoadInProcess
435 Attempt to load the component into the current process. Only available on OS X.
436 }
437 type
438 AudioComponentInstantiationOptions = UInt32;
439 const
440 kAudioComponentInstantiation_LoadOutOfProcess = 1; (* CF_ENUM_AVAILABLE(10_11, 9_0) *)
441 kAudioComponentInstantiation_LoadInProcess = 2; (* CF_ENUM_AVAILABLE(10_11, NA) *)
442
443
444 //=====================================================================================================================
445 //#pragma mark Data Types
446
447 {!
448 @struct AudioComponentDescription
449 @discussion A structure used to describe the unique and identifying IDs of an audio component
450 @field componentType
451 A unique 4-byte code identifying the generic type of an audio component
452 @field componentSubType
453 the particular flavor of this instance
454 @field componentManufacturer
455 vendor identification
456 @field componentFlags
457 must be set to zero unless a known specific value is requested
458 @field componentFlagsMask
459 must be set to zero unless a known specific value is requested
460 }
461 {$packrecords 4}
462
463 type
464 AudioComponentDescription = record
465 componentType: OSType;
466 componentSubType: OSType;
467 componentManufacturer: OSType;
468 componentFlags: UInt32;
469 componentFlagsMask: UInt32;
470 end;
471 AudioComponentDescriptionPtr = ^AudioComponentDescription;
472 {$packrecords c}
473
474 {!
475 @typedef AudioComponent
476 @abstract The type used to represent a class of particular audio components
477 @discussion An audio component is usually found through a search and is then uniquely
478 identified by the triple of an audio component's type, subtype and
479 manufacturer.
480
481 It can have properties associated with it (such as a name, a version).
482
483 It is then used as a factory (like a class in an object-oriented programming
484 language) from which to create instances. The instances are used to do the
485 actual work.
486
487 For example: the AudioComponentDescription 'aufx'/'dely'/'appl' describes the
488 delay audio unit effect from Apple, Inc. You can find this component by
489 searching explicitly for the audio component that matches this pattern (this is
490 an unique identifier - there is only one match to this triple ID). Then once
491 found, instances of the Apple delay effect audio unit can be created from its
492 audio component and used to apply that effect to an audio signal. A single
493 component can create any number of component instances.
494 }
495 type
496 AudioComponent = ^OpaqueAudioComponent; { an opaque type }
497 OpaqueAudioComponent = record end;
498
499 {!
500 @typedef AudioComponentInstance
501 @abstract The type used to represent an instance of a particular audio component
502 @discussion An audio component instance is created from its factory/producer audio
503 component. It is the body of code that does the work.
504
505 A special note: While on the desktop this is typedef'd to a
506 ComponentInstanceRecord *, you should not assume that this will always be
507 compatible and usable with Component Manager calls.
508 }
509 type
510 AudioComponentInstance = ^OpaqueAudioComponentInstance; { an opaque type }
511 OpaqueAudioComponentInstance = record end;
512
513 {!
514 @typedef AudioComponentMethod
515 @abstract The broad prototype for an audio plugin method
516 @discussion Every audio plugin will implement a collection of methods that match a particular
517 selector. For example, the AudioUnitInitialize API call is implemented by a
518 plugin implementing the kAudioUnitInitializeSelect selector. Any function implementing
519 an audio plugin selector conforms to the basic pattern where the first argument
520 is a pointer to the plugin instance structure, has 0 or more specific arguments,
521 and returns an OSStatus.
522 }
523 type
selfnull524 AudioComponentMethod = function( self: UnivPtr; ... ): OSStatus;
525
526 {!
527 @struct AudioComponentPlugInInterface
528 @discussion A structure used to represent an audio plugin's routines
529 @field Open
530 the function used to open (or create) an audio plugin instance
531 @field Close
532 the function used to close (or dispose) an audio plugin instance
533 @field Lookup
534 this is used to return a function pointer for a given selector,
535 or NULL if that selector is not implemented
536 @field reserved
537 must be NULL
538 }
539 type
540 AudioComponentPlugInInterface = record
541 Open: function (self: UnivPtr; mInstance: AudioComponentInstance): OSStatus;
542 Close: function (self: UnivPtr): OSStatus;
543 Lookup: function (selector: SInt16): AudioComponentMethod;
544 reserved: UnivPtr; // set to NULL
545 end;
546 AudioComponentPlugInInterfacePtr = ^AudioComponentPlugInInterface;
547
548 {!
549 @typedef AudioComponentFactoryFunction
550 @abstract A function that creates AudioComponentInstances.
551 @discussion
552 Authors of AudioComponents may register them from bundles as described
553 above in the discussion of this header file, or dynamically within a single
554 process, using AudioComponentRegister.
555
556 @param inDesc
557 The AudioComponentDescription specifying the component to be instantiated.
558 @result A pointer to a AudioComponentPlugInInterface structure.
559 }
560 type
561 AudioComponentFactoryFunction = function( const (*var*) inDesc: AudioComponentDescription ): AudioComponentPlugInInterfacePtr;
562
563 //=====================================================================================================================
564 //#pragma mark Functions
565
566
567 {!
568 @function AudioComponentFindNext
569 @abstract Finds an audio component.
570 @discussion This function is used to find an audio component that is the closest match
571 to the provided values. Note that the list of available components may change
572 dynamically in situations involving inter-app audio on iOS, or version 3
573 audio unit extensions. See kAudioComponentRegistrationsChangedNotification.
574
575 @param inComponent
576 If NULL, then the search starts from the beginning until an audio
577 component is found that matches the description provided by inDesc.
578 If non-NULL, then the search starts (continues) from the previously
579 found audio component specified by inComponent, and will return the next
580 found audio component.
581 @param inDesc
582 The type, subtype and manufacturer fields are used to specify the audio
583 component to search for. A value of 0 (zero) for any of these fields is
584 a wildcard, so the first match found is returned.
585 @result An audio component that matches the search parameters, or NULL if none found.
586 }
AudioComponentFindNextnull587 function AudioComponentFindNext( inComponent: AudioComponent; const (*var*) inDesc: AudioComponentDescription ): AudioComponent; external name '_AudioComponentFindNext';
588 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
589
590 {!
591 @function AudioComponentCount
592 @abstract Counts audio components.
593 @discussion Returns the number of AudioComponents that match the specified
594 AudioComponentDescription.
595 @param inDesc
596 The type, subtype and manufacturer fields are used to specify the audio
597 components to count A value of 0 (zero) for any of these fields is a
598 wildcard, so will match any value for this field
599 @result a UInt32. 0 (zero) means no audio components were found that matched the
600 search parameters.
601 }
AudioComponentCountnull602 function AudioComponentCount( const (*var*) inDesc: AudioComponentDescription ): UInt32; external name '_AudioComponentCount';
603 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
604
605 {!
606 @function AudioComponentCopyName
607 @abstract Retrieves the name of an audio component.
608 @discussion the name of an audio component
609 @param inComponent
610 the audio component (must not be NULL)
611 @param outName
612 a CFString that is the name of the audio component. This string should
613 be released by the caller.
614 @result an OSStatus result code.
615 }
AudioComponentCopyNamenull616 function AudioComponentCopyName( inComponent: AudioComponent; var outName: CFStringRef ): OSStatus; external name '_AudioComponentCopyName';
617 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
618
619 {!
620 @function AudioComponentGetDescription
621 @abstract Retrieve an audio component's description.
622 @discussion This will return the fully specified audio component description for the
623 provided audio component.
624 @param inComponent
625 the audio component (must not be NULL)
626 @param outDesc
627 the audio component description for the specified audio component
628 @result an OSStatus result code.
629 }
AudioComponentGetDescriptionnull630 function AudioComponentGetDescription( inComponent: AudioComponent; var outDesc: AudioComponentDescription ): OSStatus; external name '_AudioComponentGetDescription';
631 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
632
633 {!
634 @function AudioComponentGetVersion
635 @abstract Retrieve an audio component's version.
636 @discussion
637 @param inComponent
638 the audio component (must not be NULL)
639 @param outVersion
640 the audio component's version in the form of 0xMMMMmmDD (Major, Minor, Dot)
641 @result an OSStatus result code.
642 }
AudioComponentGetVersionnull643 function AudioComponentGetVersion( inComponent: AudioComponent; var outVersion: UInt32 ): OSStatus; external name '_AudioComponentGetVersion';
644 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
645
646 (*
647 Needs to be added to CocoaInt
648
649 #if defined(__OBJC__) && !TARGET_OS_IPHONE
650 @class NSImage;
651
652 {!
653 @function AudioComponentGetIcon
654 @abstract Fetches an icon representing the component.
655 @param comp
656 The component whose icon is to be retrieved.
657 @result
658 An autoreleased NSImage object.
659 @discussion
660 For a component originating in an app extension, the returned icon will be that of the
661 application containing the extension.
662
663 For components loaded from bundles, the icon will be that of the bundle.
664 }
665 extern NSImage * __nullable
666 AudioComponentGetIcon(AudioComponent comp)
667 API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
668 #endif
669 *)
670
671 {!
672 @function AudioComponentInstanceNew
673 @abstract Creates an audio component instance.
674 @discussion This function creates an instance of a given audio component. The audio
675 component instance is the object that does all of the work, whereas the
676 audio component is the way an application finds and then creates this object
677 to do this work. For example, an audio unit is a type of audio component
678 instance, so to use an audio unit, one finds its audio component, and then
679 creates a new instance of that component. This instance is then used to
680 perform the audio tasks for which it was designed (process, mix, synthesise,
681 etc.).
682 @param inComponent
683 the audio component (must not be NULL)
684 @param outInstance
685 the audio component instance
686 @result an OSStatus result code.
687 }
AudioComponentInstanceNewnull688 function AudioComponentInstanceNew( inComponent: AudioComponent; var outInstance: AudioComponentInstance ): OSStatus; external name '_AudioComponentInstanceNew';
689 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
690 {!
691 @function AudioComponentInstantiate
692 @abstract Creates an audio component instance, asynchronously.
693 @discussion This is an asynchronous version of AudioComponentInstanceNew(). It must be
694 used to instantiate any component with kAudioComponentFlag_RequiresAsyncInstantiation
695 set in its component flags. It may be used for other components as well.
696
697 Note: Do not block the main thread while waiting for the completion handler
698 to be called; this can deadlock.
699 @param inComponent
700 the audio component
701 @param inOptions
702 see AudioComponentInstantiationOptions
703 @param inCompletionHandler
704 called in an arbitrary thread context when instantiation is complete.
705 }
706 type
707 TAudioComponentinstantiateCompletionHandler = reference to procedure(instance: AudioComponentInstance; status: OSStatus); cblock;
708 procedure AudioComponentInstantiate( inComponent: AudioComponent; inOptions: AudioComponentInstantiationOptions; inCompletionHandler: TAudioComponentinstantiateCompletionHandler); external name '_AudioComponentInstantiate';
709 (* API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) *)
710
711 {!
712 @function AudioComponentInstanceDispose
713 @abstract Disposes of an audio component instance.
714 @discussion This function will dispose the audio component instance that was created
715 with the New call. It will deallocate any resources that the instance was using.
716 @param inInstance
717 the audio component instance to dispose (must not be NULL)
718 @result an OSStatus result code.
719 }
AudioComponentInstanceDisposenull720 function AudioComponentInstanceDispose( inInstance: AudioComponentInstance ): OSStatus; external name '_AudioComponentInstanceDispose';
721 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
722
723 // retrieves the class object associated with the instance
724 {!
725 @function AudioComponentInstanceGetComponent
726 @abstract Retrieve the audio component from its instance
727 @discussion Allows the application at any time to retrieve the audio component that is
728 the factory object of a given instance (i.e., the audio component that was
729 used to create the instance in the first place). This allows the application
730 to retrieve general information about a particular audio component (its
731 name, version, etc) when one just has an audio component instance to work
732 with
733 @param inInstance
734 the audio component instance (must not be NULL, and instance must be valid - that is, not disposed)
735 @result a valid audio component or NULL if no component was found.
736 }
AudioComponentInstanceGetComponentnull737 function AudioComponentInstanceGetComponent( inInstance: AudioComponentInstance ): AudioComponent; external name '_AudioComponentInstanceGetComponent';
738 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
739
740 {!
741 @function AudioComponentInstanceCanDo
742 @discussion Determines if an audio component instance implements a particular component
743 API call as signified by the specified selector identifier token.
744 @param inInstance
745 the audio component instance
746 @param inSelectorID
747 a number to signify the audio component API (component selector) as appropriate for the instance's component type.
748 @result a boolean
749 }
AudioComponentInstanceCanDonull750 function AudioComponentInstanceCanDo( inInstance: AudioComponentInstance; inSelectorID: SInt16 ): Boolean; external name '_AudioComponentInstanceCanDo';
751 (* API_AVAILABLE(macos(10.6), ios(3.0), watchos(2.0), tvos(9.0)) *)
752
753 {!
754 @function AudioComponentRegister
755 @abstract Dynamically registers an AudioComponent within the current process
756 @discussion
757 AudioComponents are registered either when found in appropriate bundles in the filesystem,
758 or via this call. AudioComponents registered via this call are available only within
759 the current process.
760
761 @param inDesc
762 The AudioComponentDescription that describes the AudioComponent. Note that
763 the registrar needs to be sure to set the flag kAudioComponentFlag_SandboxSafe
764 in the componentFlags field of the AudioComponentDescription to indicate that
765 the AudioComponent can be loaded directly into a sandboxed process.
766 @param inName
767 the AudioComponent's name
768 @param inVersion
769 the AudioComponent's version
770 @param inFactory
771 an AudioComponentFactoryFunction which will create instances of your
772 AudioComponent
773 @result an AudioComponent object
774 }
AudioComponentRegisternull775 function AudioComponentRegister( const (*var*) inDesc: AudioComponentDescription; inName: CFStringRef; inVersion: UInt32; inFactory: AudioComponentFactoryFunction ): AudioComponent; external name '_AudioComponentRegister';
776 (* API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) *)
777
778 {$ifc TARGET_OS_MAC}
779 {!
780 @function AudioComponentCopyConfigurationInfo
781 @abstract Fetches the basic configuration info about a given AudioComponent
782 @discussion Currently, only AudioUnits can supply this information.
783 @param inComponent
784 The AudioComponent whose info is being fetched.
785 @param outConfigurationInfo
786 On exit, this is CFDictionaryRef that contains information describing the
787 capabilities of the AudioComponent. The specific information depends on the
788 type of AudioComponent. The keys for the dictionary are defined in
789 AudioUnitProperties.h (or other headers as appropriate for the component type).
790 @result An OSStatus indicating success or failure.
791 }
AudioComponentCopyConfigurationInfonull792 function AudioComponentCopyConfigurationInfo( inComponent: AudioComponent; var outConfigurationInfo: CFDictionaryRef ): OSStatus; external name '_AudioComponentCopyConfigurationInfo';
793 (* __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA) *)
794
795 {!
796 @enum AudioComponentValidationResult
797 @abstract Constants for describing the result of validating an AudioComponent
798 @constant kAudioComponentValidationResult_Passed
799 The AudioComponent passed validation.
800 @constant kAudioComponentValidationResult_Failed
801 The AudioComponent failed validation.
802 @constant kAudioComponentValidationResult_TimedOut
803 The validation operation timed out before completing.
804 @constant kAudioComponentValidationResult_UnauthorizedError_Open
805 The AudioComponent failed validation during open operation as it is not authorized.
806 @constant kAudioComponentValidationResult_UnauthorizedError_Init
807 The AudioComponent failed validation during initialization as it is not authorized.
808 }
809 type
810 AudioComponentValidationResult = UInt32;
811 const
812 kAudioComponentValidationResult_Unknown = 0;
813 kAudioComponentValidationResult_Passed = 1;
814 kAudioComponentValidationResult_Failed = 2;
815 kAudioComponentValidationResult_TimedOut = 3;
816 kAudioComponentValidationResult_UnauthorizedError_Open = 4;
817 kAudioComponentValidationResult_UnauthorizedError_Init = 5;
818
819 {!
820 @define kAudioComponentConfigurationInfo_ValidationResult
821 @abstract Dictionary that contains the AudioComponentValidationResult for the component.
822 @discussion
823 The keys in this dictionary are the CPU architectures (e.g. "i386") that generated each result.
824 }
825 const
826 kAudioComponentConfigurationInfo_ValidationResult = 'ValidationResult';
827
828 {!
829 @function AudioComponentValidate
830 @abstract Tests a specified AudioComponent for API and behavioral conformance.
831 @discussion Currently, only AudioUnits can can be validated.
832 @param inComponent
833 The AudioComponent to validate.
834 @param inValidationParameters
835 A CFDictionaryRef that contains parameters for the validation operation.
836 Passing NULL for this argument tells the system to use the default
837 parameters.
838 @param outValidationResult
839 On exit, this is an AudioComponentValidationResult.
840 @result an OSStatus result code.
841 }
AudioComponentValidatenull842 function AudioComponentValidate( inComponent: AudioComponent; inValidationParameters: CFDictionaryRef; var outValidationResult: AudioComponentValidationResult): OSStatus; external name '_AudioComponentValidate';
843 (* API_AVAILABLE(macos(10.7)) *)
844
845 {!
846 @define kAudioComponentValidationParameter_TimeOut
847 @discussion This is a number that indicates the time in seconds to wait for a validation
848 operation to complete. Note that if a validation operation times out, it will return
849 kAudioComponentValidationResult_TimedOut as its result.
850 }
851 const
852 kAudioComponentValidationParameter_TimeOut = 'TimeOut';
853
854 {!
855 @define kAudioComponentValidationParameter_ForceValidation
856 @discussion
857 This is a bool that indicates to ignore the cached value and run validation on the specified
858 audio unit and update the cache.
859 }
860 const
861 kAudioComponentValidationParameter_ForceValidation = 'ForceValidation';
862 {$endc}
863
864 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
865
866 end.
867 {$endc} {not MACOSALLINCLUDE}
868