1/* 2 * Copyright (c) 1998-2014 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23/*! 24 * @header IOAudioEngine 25 */ 26 27#ifndef _IOKIT_IOAUDIOENGINE_H 28#define _IOKIT_IOAUDIOENGINE_H 29 30#include <IOKit/IOService.h> 31#include <AvailabilityMacros.h> 32 33#ifndef IOAUDIOFAMILY_SELF_BUILD 34#include <IOKit/audio/IOAudioTypes.h> 35#else 36#include "IOAudioTypes.h" 37#endif 38#include <IOKit/IOBufferMemoryDescriptor.h> 39 40class OSDictionary; 41class OSCollection; 42class OSOrderedSet; 43class IOAudioEngineUserClient; 44class IOAudioDevice; 45class IOAudioStream; 46class IOAudioControl; 47class IOCommandGate; 48 49#define IOAUDIOENGINE_DEFAULT_NUM_ERASES_PER_BUFFER 4 50 51/*! 52 * @typedef IOAudioEnginePosition 53 * @abstract Represents a position in an audio audio engine. 54 * @discussion This position is based on the sample frame within a 55 * loop around the sample buffer, and the loop count which starts at 0 when the audio engine 56 * begins playback. 57 * @field fSampleFrame The sample frame within the buffer - starts at 0. 58 * @field fLoopCount The number of times the ring buffer has looped. 59 */ 60typedef struct { 61 UInt32 fSampleFrame; 62 UInt32 fLoopCount; 63} IOAudioEnginePosition; 64 65#define CMP_IOAUDIOENGINEPOSITION(p1, p2) \ 66 (((p1)->fLoopCount > (p2)->fLoopCount) ? 1 : \ 67 ((p1)->fLoopCount == (p2)->fLoopCount) && ((p1)->fSampleFrame > (p2)->fSampleFrame) ? 1 : \ 68 ((p1)->fLoopCount == (p2)->fLoopCount) && ((p1)->fSampleFrame == (p2)->fSampleFrame) ? 0 : -1) 69 70#define IOAUDIOENGINEPOSITION_IS_ZERO(p1) (((p1)->fLoopCount == 0) && ((p1)->fSampleFrame == 0)) 71 72/*! 73 * @class IOAudioEngine 74 * @abstract Abstract base class for a single audio audio / I/O engine. 75 * @discussion An IOAudioEngine is defined by a single I/O engine to transfer data to 76 * or from one or more sample buffers. Each sample buffer is represented by a single IOAudioStream 77 * instance. A single IOAudioEngine must contain at least one IOAudioStream, but has no upper 78 * limit on the number of IOAudioStreams it may contain. An IOAudioEngine instance may contain 79 * both input and output IOAudioStreams. 80 * 81 * An audio driver must subclass IOAudioEngine in order to provide certain services. An 82 * IOAudioEngine subclass must start and stop the I/O engine when requested. The I/O 83 * engine should be continuously running and loop around from end to beginning. While the audio 84 * engine is running, it must take a timestamp as the sample buffer(s) wrap around and start at 85 * the beginning. The CoreAudio.framework uses the timestamp to calculate the exact position of 86 * the audio engine. An IOAudioEngine subclass must implement getCurrentSampleFrame() to provide 87 * a sample position on demand. Finally, an IOAudioEngine subclass must provide clipping and 88 * format conversion routines to go to/from the CoreAudio.framework's native float format. 89 * 90 * If multiple stream formats or sample rates are allowed, the IOAudioEngine 91 * subclass must provide support for changing the hardware when a format or sample rate is 92 * changed. 93 * 94 * There are several attributes associated with a single IOAudioEngine: 95 * 96 * The IOAudioEngine superclass provides a shared status buffer that contains all of the dynamic pieces 97 * of information about the audio engine (type IOAudioEngineStatus). It runs an erase process on 98 * all of the output streams. The erase head is used to zero out the mix and sample buffers after 99 * the samples have been played. Additionally, the IOAudioEngine superclass handles the 100 * communication with the CoreAudio.framework and makes the decision to start and stop the 101 * audio engine when it detects it is in use. 102 * 103 * In order for an audio device to play back or record sound, an IOAudioEngine subclass must be created. 104 * The subclass must initialize all of the necessary hardware resources to prepare for starting the 105 * audio I/O engine. It typically will perform these tasks in the initHardware() method. A subclass 106 * may also implement a stop() method which is called as the driver is being torn down. This is 107 * typically called in preparation of removing the device from the system for removable devices. 108 * 109 * In addition to initializing the necessary hardware, there are a number of other tasks an 110 * IOAudioEngine must do during initHardware(). It must create the necessary IOAudioStream objects 111 * to match the device capabilities. Each IOAudioStream must be added using addAudioStream(). It 112 * also should create the IOAudioControls needed to control the various attributes of the audio engine: 113 * output volume, mute, input gain, input selection, analog passthru. To do that, addDefaultAudioControl() 114 * should be called with each IOAudioControl to be attached to the IOAudioEngine. In order to provide 115 * for proper synchronization, the latency of the audio engine should be specified with setSampleLatency(). 116 * This value represents the latency between the timestamp taken at the beginning of the buffer and 117 * when the audio is actually played (or recorded) by the device. If a device is block based or if 118 * there is a need to keep the CoreAudio.framework a certain number of samples ahead of (or behind for 119 * input) the I/O head, that value should be specified using setSampleOffset(). If this is not specified 120 * the CoreAudio.framework may attempt to get as close to the I/O head as possible. 121 * 122 * The following fields in the shared IOAudioEngineStatus struct must be maintained by the subclass 123 * implementation: 124 * <pre> 125 * <t> fCurrentLoopCount - the number of times the sample buffer has wrapped around to the beginning 126 * <t> fLastLoopTime - timestamp of the most recent time that the I/O engine looped back to the 127 * beginning of the sample buffer 128 * </pre> 129 * It is critically important that the fLastLoopTime field be as accurate as possible. It is 130 * the basis for the entire timer and synchronization mechanism used by the audio system. 131 * 132 * At init time, the IOAudioEngine subclass must call setNumSampleFramesPerBuffer() to indicate how large 133 * each of the sample buffers are (measured in sample frames). Within a single IOAudioEngine, all sample 134 * buffers must be the same size and be running at the same sample rate. If different buffers/streams can 135 * be run at different rates, separate IOAudioEngines should be used. The IOAudioEngine subclass must 136 * also call setSampleRate() at init time to indicate the starting sample rate of the device. 137 * 138 */ 139 140#ifdef __MAC_OS_X_VERSION_MIN_REQUIRED 141 #if __MAC_OS_X_VERSION_MIN_REQUIRED >= 101000 142 #warning IOAudioEngine is deprecated use <CoreAudio/AudioServerPlugIn.h> instead. 143 #endif 144#endif 145 146class IOAudioEngine : public IOService 147{ 148 OSDeclareAbstractStructors(IOAudioEngine) 149 150 friend class IOAudioEngineUserClient; 151 friend class IOAudioDevice; 152 friend class IOAudioStream; 153 154public: 155 /*! @var gSampleRateWholeNumberKey */ 156 static const OSSymbol *gSampleRateWholeNumberKey; 157 /*! @var gSampleRateFractionKey */ 158 static const OSSymbol *gSampleRateFractionKey; 159 160 /*! @var numSampleFramesPerBuffer */ 161 UInt32 numSampleFramesPerBuffer; 162 163 /*! @var sampleRate 164 * The current sample rate of the audio engine in samples per second. */ 165 IOAudioSampleRate sampleRate; 166 167 /*! @var numErasesPerBuffer 168 * The number of times the erase head get scheduled to run for each 169 * cycle of the audio engine. */ 170 UInt32 numErasesPerBuffer; 171 /*! @var runEraseHead 172 * Set to true if the erase head is to run when the audio engine is running. This is the case if there are any output streams. */ 173 bool runEraseHead; 174 175 /*! @var audioEngineStopPosition 176 * When all clients have disconnected, this is set to one buffer length past the 177 * current audio engine position at the time. Then when the stop position is reached, the audio engine 178 * is stopped */ 179 IOAudioEnginePosition audioEngineStopPosition; 180 181 /*! @var isRegistered 182 * Internal state variable to keep track or whether registerService() has been called. */ 183 bool isRegistered; 184 /*! @var configurationChangeInProgress 185 * Set to true after beginConfigurationChange() and false upon a 186 * subsequent call to completeConfigurationChange() or cancelConfigurationChange(). */ 187 bool configurationChangeInProgress; 188 189 /*! @var state 190 * The current state of the IOAudioEngine - running, stopped, paused. */ 191 IOAudioEngineState state; 192 193 /*! @var status 194 * Status struct shared with the CoreAudio.framework. */ 195 IOAudioEngineStatus * status; 196 197 /*! @var audioDevice 198 * The IOAudioDevice instance to which the IOAudioEngine belongs. */ 199 IOAudioDevice * audioDevice; 200 201 /*! @var workLoop 202 * The IOWorkLoop for the audio driver - shared with the IOAudioDevice. */ 203 IOWorkLoop *workLoop; 204 /*! @var commandGate 205 * The IOCommandGate for this audio engine - attached to the driver's IOWorkLoop. */ 206 IOCommandGate *commandGate; 207 208 /*! @var inputStreams 209 * An OSSet of all of the input IOAudioStreams attached to this IOAudioEngine. */ 210 OSOrderedSet *inputStreams; 211 UInt32 maxNumInputChannels; 212 /*! @var outputStreams 213 * An OSSet of all of the output IOAudioStreams attached to this IOAudioEngine. */ 214 OSOrderedSet *outputStreams; 215 UInt32 maxNumOutputChannels; 216 /*! @var userClients 217 * An OSSet of all of the currently connected user clients. */ 218 OSSet *userClients; 219 /*! @var defaultAudioControls 220 * All of the IOAudioControls that affect this audio engine. */ 221 OSSet *defaultAudioControls; 222 223 /*! @var numActiveUserClients 224 * A total of the active user clients - those that are currently playing or 225 * recording audio. */ 226 UInt32 numActiveUserClients; 227 UInt32 sampleOffset; // used for input and output if inputSampleOffset is not set, if inputSampleOffset is set used as output only 228 229 UInt32 index; 230 bool duringStartup; 231 232protected: 233 234 /*! 235 * @var deviceStartedAudioEngine 236 * Used by the IOAudioDevice to determine responsibility for shutting 237 * the audio engine down when it is no longer needed. 238 */ 239 bool deviceStartedAudioEngine; 240 241protected: 242 struct ExpansionData { 243 UInt32 pauseCount; 244 IOBufferMemoryDescriptor *statusDescriptor; 245 IOBufferMemoryDescriptor *bytesInInputBufferArrayDescriptor; 246 IOBufferMemoryDescriptor *bytesInOutputBufferArrayDescriptor; 247 UInt32 mixClipOverhead; 248 OSArray *streams; 249 UInt32 inputSampleOffset; 250 UInt32 commandGateStatus; // <rdar://8518215> 251 SInt32 commandGateUsage; // <rdar://8518215> 252 }; 253 254 ExpansionData *reserved; 255 256// static UInt32 sInstanceCount; 257 258public: 259 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 0 ); 260 virtual IOReturn performFormatChange(IOAudioStream *audioStream, const IOAudioStreamFormat *newFormat, const IOAudioStreamFormatExtension *formatExtension, const IOAudioSampleRate *newSampleRate ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 261 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 1 ); 262 virtual IOBufferMemoryDescriptor * getStatusDescriptor( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 263 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 2 ); 264 virtual IOReturn getNearestStartTime(IOAudioStream *audioStream, IOAudioTimeStamp *ioTimeStamp, bool isInput ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 265 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 3); 266 virtual IOBufferMemoryDescriptor * getBytesInInputBufferArrayDescriptor( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 267 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 4); 268 virtual IOBufferMemoryDescriptor * getBytesInOutputBufferArrayDescriptor( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 269 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 5); 270 /*! 271 * @function eraseOutputSamples 272 * @abstract This function allows for the actual erasing of the mix and sample buffer to be overridden by 273 * a child class. 274 * @param mixBuf Pointer to the IOAudioFamily allocated mix buffer. 275 * @param sampleBuf Pointer to the child class' sample buffer. 276 * @param firstSampleFrame Index to the first sample frame to erase. 277 * @param numSampleFrames Number of sample frames to erase. 278 * @param streamFormat Format of the data to be erased. 279 * @param audioStream Pointer to stream object that corresponds to the sample buffer being erased. 280 * @result Must return kIOReturnSuccess if the samples have been erased. 281 */ 282 virtual IOReturn eraseOutputSamples(const void *mixBuf, void *sampleBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 283 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 6); 284 /*! 285 * @function setClockIsStable 286 * @abstract This function sets a flag that CoreAudio uses to select its sample rate tracking algorithm. Set 287 * this to TRUE unless that results in dropped audio. If the driver is experiencing unexplained dropouts 288 * setting this FALSE might help. 289 * @param clockIsStable TRUE tells CoreAudio to use an agressive PLL to quickly lock to the engine's sample rate 290 * while FALSE tells CoreAudio to adjust more slowly to perceived sample rate changes that might just be the 291 * result of an unstable clock. 292 */ 293 virtual void setClockIsStable(bool clockIsStable ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 294 295 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 7); 296 /*! 297 * @function setMixClipOverhead 298 * @abstract Used to tell IOAudioFamily when the watchdog timer must fire by. 299 * @discussion setMixClipOverhead allows an audio engine to tell IOAudioFamily how much time 300 * an engine will take to mix and clip its samples, in percent. 301 * The default value is 10, meaning 10%. This will cause IOAudioFamily to make 302 * the watchdog timer fire when there is just over 10% of the time to complete 303 * a buffer set left (e.g. 51 samples when the HAL is using a buffer size of 512 304 * samples). 305 * @param newMixClipOverhead How much time per buffer should be made available for the 306 * mix and clip routines to run. Valid values are 1 through 99, inclusive. 307 * @result return no error 308 */ 309 virtual void setMixClipOverhead(UInt32 newMixClipOverhead ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 310 311 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 8); 312 /*! 313 * @function setClockDomain 314 * @abstract Sets a property that CoreAudio uses to determine how devices are synchronized. If an audio device can tell that it is 315 * synchronized to another engine, it should set this value to that engine's clock domain. If an audio device can be a clock master, it may publish 316 * its own clock domain for other devices to use. 317 * @param clockDomain is the unique ID of another engine that this engine realizes it is synchronized to, use the default value kIOAudioNewClockDomain 318 * to have IOAudioEngine create a unique clock domain. 319 */ 320 virtual void setClockDomain(UInt32 clockDomain = kIOAudioNewClockDomain ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 321 322 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 9); 323 /*! 324 * @function convertInputSamplesVBR 325 * @abstract Override this method if you want to return a different number of sample frames than was requested. 326 */ 327 virtual IOReturn convertInputSamplesVBR(const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 &numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 328 329 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 10); 330 /*! 331 * @function setInputSampleOffset 332 * @abstract set the offset CoreAudio will read from off the current read pointer 333 * @param numSamples size of offset in sample 334 */ 335 virtual void setInputSampleOffset(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 336 337 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 11); 338 /*! 339 * @function setOutputSampleOffset 340 * @abstract set the offset CoreAudio will write at off the current write pointer 341 * @param numSamples size of offset in sample 342 */ 343 virtual void setOutputSampleOffset(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 344 345protected: 346 347 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 12); 348 virtual IOReturn createUserClient(task_t task, void *securityID, UInt32 type, IOAudioEngineUserClient **newUserClient, OSDictionary *properties ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 349 350public: 351 352 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 13); 353 /*! 354 * @function setAttributeForConnection 355 * @abstract Generic method to set some attribute of the audio engine, specific to one connection. 356 * @discussion IOAudioEngine subclasses may implement this method to allow arbitrary attribute/value pairs to be set, specific to one connection. 357 * @param attribute Defines the attribute to be set. 358 * @param value The new value for the attribute. 359 * @result an IOReturn code. 360 */ 361 362 virtual IOReturn setAttributeForConnection( SInt32 connectIndex, UInt32 attribute, uintptr_t value ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 363 364 // OSMetaClassDeclareReservedUsed(IOAudioEngine, 14); 365 /*! @function getAttributeForConnection 366 * @abstract Generic method to retrieve some attribute of the audio engine, specific to one connection. 367 * @discussion IOAudioEngine subclasses may implement this method to allow arbitrary attribute/value pairs to be returned, specific to one connection. 368 * @param attribute Defines the attribute to be returned. Some defined attributes are:<br> 369 * @param value Returns the value for the attribute. 370 * @result an IOReturn code. 371 */ 372 373 virtual IOReturn getAttributeForConnection( SInt32 connectIndex, UInt32 attribute, uintptr_t * value ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 374 375private: 376 OSMetaClassDeclareReservedUsed(IOAudioEngine, 0); 377 OSMetaClassDeclareReservedUsed(IOAudioEngine, 1); 378 OSMetaClassDeclareReservedUsed(IOAudioEngine, 2); 379 OSMetaClassDeclareReservedUsed(IOAudioEngine, 3); 380 OSMetaClassDeclareReservedUsed(IOAudioEngine, 4); 381 OSMetaClassDeclareReservedUsed(IOAudioEngine, 5); 382 OSMetaClassDeclareReservedUsed(IOAudioEngine, 6); 383 OSMetaClassDeclareReservedUsed(IOAudioEngine, 7); 384 OSMetaClassDeclareReservedUsed(IOAudioEngine, 8); 385 OSMetaClassDeclareReservedUsed(IOAudioEngine, 9); 386 OSMetaClassDeclareReservedUsed(IOAudioEngine, 10); 387 OSMetaClassDeclareReservedUsed(IOAudioEngine, 11); 388 OSMetaClassDeclareReservedUsed(IOAudioEngine, 12); 389 OSMetaClassDeclareReservedUsed(IOAudioEngine, 13); 390 OSMetaClassDeclareReservedUsed(IOAudioEngine, 14); 391 392 OSMetaClassDeclareReservedUnused(IOAudioEngine, 15); 393 OSMetaClassDeclareReservedUnused(IOAudioEngine, 16); 394 OSMetaClassDeclareReservedUnused(IOAudioEngine, 17); 395 OSMetaClassDeclareReservedUnused(IOAudioEngine, 18); 396 OSMetaClassDeclareReservedUnused(IOAudioEngine, 19); 397 OSMetaClassDeclareReservedUnused(IOAudioEngine, 20); 398 OSMetaClassDeclareReservedUnused(IOAudioEngine, 21); 399 OSMetaClassDeclareReservedUnused(IOAudioEngine, 22); 400 OSMetaClassDeclareReservedUnused(IOAudioEngine, 23); 401 OSMetaClassDeclareReservedUnused(IOAudioEngine, 24); 402 OSMetaClassDeclareReservedUnused(IOAudioEngine, 25); 403 OSMetaClassDeclareReservedUnused(IOAudioEngine, 26); 404 OSMetaClassDeclareReservedUnused(IOAudioEngine, 27); 405 OSMetaClassDeclareReservedUnused(IOAudioEngine, 28); 406 OSMetaClassDeclareReservedUnused(IOAudioEngine, 29); 407 OSMetaClassDeclareReservedUnused(IOAudioEngine, 30); 408 OSMetaClassDeclareReservedUnused(IOAudioEngine, 31); 409 OSMetaClassDeclareReservedUnused(IOAudioEngine, 32); 410 OSMetaClassDeclareReservedUnused(IOAudioEngine, 33); 411 OSMetaClassDeclareReservedUnused(IOAudioEngine, 34); 412 OSMetaClassDeclareReservedUnused(IOAudioEngine, 35); 413 OSMetaClassDeclareReservedUnused(IOAudioEngine, 36); 414 OSMetaClassDeclareReservedUnused(IOAudioEngine, 37); 415 OSMetaClassDeclareReservedUnused(IOAudioEngine, 38); 416 OSMetaClassDeclareReservedUnused(IOAudioEngine, 39); 417 OSMetaClassDeclareReservedUnused(IOAudioEngine, 40); 418 OSMetaClassDeclareReservedUnused(IOAudioEngine, 41); 419 OSMetaClassDeclareReservedUnused(IOAudioEngine, 42); 420 OSMetaClassDeclareReservedUnused(IOAudioEngine, 43); 421 OSMetaClassDeclareReservedUnused(IOAudioEngine, 44); 422 OSMetaClassDeclareReservedUnused(IOAudioEngine, 45); 423 OSMetaClassDeclareReservedUnused(IOAudioEngine, 46); 424 OSMetaClassDeclareReservedUnused(IOAudioEngine, 47); 425 426public: 427 /*! 428 * @function createDictionaryFromSampleRate 429 * @abstract Generates a dictionary matching the given sample rate. 430 * @discussion This is an internal routine used to generate a dictionary matching the given sample rate. It is used to generate a sample rate dictionary for the I/O Registry - used by the 431 * CoreAudio.framework. 432 * @result Returns the newly create OSDictionary. 433 */ 434 static OSDictionary *createDictionaryFromSampleRate(const IOAudioSampleRate *sampleRate, OSDictionary *rateDict = 0 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 435 436 /*! 437 * @function createSampleRateFromDictionary 438 * @abstract Generates a sample rate from an OSDictionary. 439 * @discussion This is an internal routine used to generate a sample rate from an OSDictionary. It is used to generate a sample rate give a new OSDictionary from the IORegistry - coming 440 * from the CoreAudio.framework. 441 * @result Returns the sample rate. 442 */ 443 static IOAudioSampleRate *createSampleRateFromDictionary(const OSDictionary *rateDict, IOAudioSampleRate *sampleRate = 0 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 444 445 /*! 446 * @function init 447 * @abstract Performs initialization of a newly allocated IOAudioEngine. 448 * @discussion This function is responsible for initialization of all of the general attributes of 449 * a new IOAudioEngine. It initializes instance variables to their default 450 * values and allocates the shared status buffer. Subclasses will likely want to override this method 451 * and do all of their common initialization in their implementation. They do need to be sure to call 452 * IOAudioEngine's implementation of init and pay attention to the return value. 453 * @param properties The default properties for the IOAudioEngine. 454 * @result Returns true if initialization was successful. 455 */ 456 virtual bool init(OSDictionary *properties ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 457 458 /*! 459 * @function free 460 * @abstract Frees all of the resources allocated by the IOAudioEngine. 461 * @discussion Do not call this directly. This is called automatically by the system when the instance's 462 * refcount goes to 0. To decrement the refcount, call release() on the object. 463 */ 464 virtual void free( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 465 466 /*! 467 * @function getWorkLoop 468 * @abstract Returns the IOWorkLoop for the driver. 469 */ 470 virtual IOWorkLoop *getWorkLoop() const; 471 472 /*! 473 * @function getCommandGate 474 * @abstract Returns the IOCommandGate for this IOAudioEngine. 475 */ 476 virtual IOCommandGate *getCommandGate() const; 477 478 /*! 479 * @function start 480 * @abstract A simple cover function for start(IOService *, IOAudioDevice *) that assumes the provider 481 * is the IOAudioDevice. 482 * @discussion Subclasses will want to override start(IOService *, IOAudioDevice *) rather than this 483 * one. 484 * @param provider The service provider for the IOAudioEngine (the IOAudioDevice in this case). 485 * @result Returns true if the IOAudioEngine was successfully started. 486 */ 487 virtual bool start(IOService *provider ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 488 489 /*! 490 * @function start 491 * @abstract Standard IOKit start() routine called to start an IOService. 492 * @discussion This function is called in order to prepare the IOAudioEngine for use. It does NOT 493 * mean that the audio I/O engine itself should be started. This implementation gets the IOWorkLoop 494 * from the IOAudioDevice and allocates an IOCommandGate. Finally it calls initHardware() in which 495 * all of the subclass-specific device initialization should be done. Upon return from initHardware() 496 * all IOAudioStreams should be created and added to the audio engine. Also, all IOAudioControls 497 * for this IOAudioEngine should be created and attached. 498 * @param provider The service provider for the IOAudioEngine. 499 * @param device The IOAudioDevice to which this IOAudioEngine belongs. 500 * @result Returns true if the service was successfully started. 501 */ 502 virtual bool start(IOService *provider, IOAudioDevice *device ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 503 504 /*! 505 * @function initHardware 506 * @abstract This function is called by start() to provide a convenient place for the subclass to 507 * perform its hardware initialization. 508 * @discussion Upon return from this function, all IOAudioStreams and IOAudioControls should be created 509 * and the audio engine should be ready to be started when a client requests that playback begin. 510 * @function provider The service provider numb for this audio engine - typically the IOAudioDevice. 511 * @result Returns true if the hardware was successfully initialized. 512 */ 513 virtual bool initHardware(IOService *provider ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 514 515 /*! 516 * @function stop 517 * @abstract Stops the service and prepares for the driver to be terminated. 518 * @discussion This function is called before the driver is terminated and usually means that the device 519 * has been removed from the system. 520 * @param provider The service provider for the IOAudioEngine. 521 */ 522 virtual void stop(IOService *provider ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 523 524 /*! 525 * @function registerService 526 * @abstract Called when this audio engine is ready to begin vending services. 527 * @discussion This function is called by IOAudioDevice::activateAudioEngine() once the audio engine 528 * has been fully initialized and is ready to begin audio playback. 529 * @param options 530 */ 531 virtual void registerService(IOOptionBits options = 0 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 532 533 virtual void setAudioDevice(IOAudioDevice *device ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 534 virtual void setIndex(UInt32 index ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 535 536 virtual void setDescription(const char *description ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 537 538 /*! 539 * @function newUserClient 540 * @abstract Requests a new user client object for this service. 541 * @discussion This function is called automatically by I/O Kit when a user process attempts 542 * to connect to this service. It allocates a new IOAudioEngineUserClient object and increments 543 * the number of connections for this audio engine. If this is the first user client for this IOAudioEngine, 544 * it calls startAudioEngine(). There is no need to call this function directly. 545 * A derived class that requires overriding of newUserClient should override the version with the properties 546 * parameter for Intel targets, and without the properties parameter for PPC targets. The #if __i386__ directive 547 * can be used to select between the two behaviors. 548 * @param task The task requesting the new user client. 549 * @param securityID Optional security paramater passed in by the client - ignored. 550 * @param type Optional user client type passed in by the client - ignored. 551 * @param handler The new IOUserClient * must be stored in this param on a successful completion. 552 * @param properties A dictionary of additional properties for the connection. 553 * @result Returns kIOReturnSuccess on success. May also result kIOReturnError or kIOReturnNoMemory. 554 */ 555 virtual IOReturn newUserClient(task_t task, void *securityID, UInt32 type, IOUserClient **handler ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 556 virtual IOReturn newUserClient(task_t task, void *securityID, UInt32 type, OSDictionary *properties, IOUserClient **handler ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 557 558 /*! 559 * @function addAudioStream 560 * @abstract Adds an IOAudioStream to the audio engine. 561 * @discussion This function is called by the driver to add an IOAudioStream to the audio engine. This must be called at least once to make sure the audio engine has at least one IOAudioStream. 562 * @param stream The IOAudioStream to be added. 563 * @result Returns kIOReturnSuccess if the stream was successfully added. 564 */ 565 virtual IOReturn addAudioStream(IOAudioStream *stream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 566 567 virtual IOAudioStream *getAudioStream(IOAudioStreamDirection direction, UInt32 channelID ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 568 569 virtual void lockAllStreams( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 570 virtual void unlockAllStreams( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 571 572 virtual void updateChannelNumbers( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 573 574 /*! 575 * @function resetStatusBuffer 576 * @abstract Resets the status buffer to its default values. 577 * @discussion This is called during startAudioEngine() and resumeAudioEngine() to clear out the status buffer 578 * in preparation of starting up the I/O engine. There is no need to call this directly. 579 */ 580 virtual void resetStatusBuffer( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 581 582 /*! 583 * @function clearAllSampleBuffers 584 * @abstract Zeros out all of the sample and mix buffers associated with the IOAudioEngine 585 * @discussion This is called during resumeAudioEngine() since the audio engine gets started back at the 586 * beginning of the sample buffer. 587 */ 588 virtual void clearAllSampleBuffers( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 589 590 /*! 591 * @function getCurrentSampleFrame 592 * @abstract Gets the current sample frame from the IOAudioEngine subclass. 593 * @result 594 */ 595 virtual UInt32 getCurrentSampleFrame() = 0; 596 597 /*! 598 * @function startAudioEngine 599 * @abstract Starts the audio I/O engine. 600 * @discussion This method is called automatically when the audio engine is placed into use the first time. 601 * This must be overridden by the subclass. No call to the superclass's implementation is 602 * necessary. The subclass's implementation must start up the audio I/O engine. This includes any audio 603 * engine that needs to be started as well as any interrupts that need to be enabled. Upon successfully 604 * starting the engine, the subclass's implementation must call setState(kIOAudioEngineRunning). If 605 * it has also checked the state using getState() earlier in the implementation, the stateLock must be 606 * acquired for the entire initialization process (using IORecursiveLockLock(stateLock) and 607 * IORecursiveLockUnlock(stateLock)) to ensure that the state remains consistent. See the general class 608 * comments for an example. 609 * @result Must return kIOReturnSuccess on a successful start of the engine. 610 */ 611 virtual IOReturn startAudioEngine( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 612 613 /*! 614 * @function stopAudioEngine 615 * @abstract Stops the audio I/O engine. 616 * @discussion This method is called automatically when the last client disconnects from this audio engine. 617 * It must be overridden by the subclass. No call to the superclass's implementation is necessary. 618 * The subclass's implementation must stop the audio I/O engine. The audio engine (if it exists) should 619 * be stopped and any interrupts disabled. Upon successfully stopping the engine, the subclass must call 620 * setState(kAudioEngineStopped). If it has also checked the state using getState() earlier in the 621 * implementation, the stateLock must be acquired for the entire initialization process (using 622 * IORecursiveLockLock(stateLock) and IORecursiveLockUnlock(stateLock)) to ensure that the state remains 623 * consistent. 624 * @result Must return kIOReturnSuccess on a successful stop of the engine. 625 */ 626 virtual IOReturn stopAudioEngine( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 627 virtual IOReturn pauseAudioEngine( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 628 virtual IOReturn resumeAudioEngine( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 629 630 /*! 631 * @function performAudioEngineStart 632 * @abstract Called to start the audio I/O engine 633 * @discussion This method is called by startAudioEngine(). This must be overridden by the subclass. 634 * No call to the superclass' implementation is necessary. The subclass' implementation must start up the 635 * audio I/O engine. This includes any audio engine that needs to be started as well as any interrupts 636 * that need to be enabled. 637 * @result Must return kIOReturnSuccess on a successful start of the engine. 638 */ 639 virtual IOReturn performAudioEngineStart( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 640 641 /*! 642 * @function performAudioEngineStop 643 * @abstract Called to stop the audio I/O engine 644 * @discussion This method is called by stopAudioEngine() and pauseAudioEngine. 645 * This must be overridden by the subclass. No call to the superclass' implementation is 646 * necessary. The subclass' implementation must stop the audio I/O engine. This includes any audio 647 * engine that needs to be stopped as well as any interrupts that need to be disabled. 648 * @result Must return kIOReturnSuccess on a successful stop of the engine. 649 */ 650 virtual IOReturn performAudioEngineStop( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 651 652 /*! 653 * @function getState 654 * @abstract Returns the current state of the IOAudioEngine. 655 * @discussion If this method is called in preparation for calling setState(), the stateLock must 656 * be acquired before the first call to getState() and held until after the last call to setState(). 657 * Be careful not to return from the code acquiring the lock while the lock is being held. That 658 * will cause a deadlock situation. 659 * @result The current state of the IOAudioEngine: kIOAudioEngineRunning, kIOAudioEngineStopped. 660 */ 661 virtual IOAudioEngineState getState( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 662 663 /*! 664 * @function getSampleRate 665 * @abstract Returns the sample rate of the IOAudioEngine in samples per second. 666 */ 667 virtual const IOAudioSampleRate *getSampleRate( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 668 669 virtual IOReturn hardwareSampleRateChanged(const IOAudioSampleRate *sampleRate ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 670 671 /*! 672 * @function getRunEraseHead 673 * @abstract Returns true if the audio engine will run the erase head when the audio engine is running. 674 */ 675 virtual bool getRunEraseHead( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 676 677 /*! 678 * @function getStatus 679 * @abstract Returns a pointer to the shared status buffer. 680 */ 681 virtual const IOAudioEngineStatus *getStatus( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 682 683 /*! 684 * @function timerCallback 685 * @abstract A static method used as a callback for the IOAudioDevice timer services. 686 * @discussion This method implements the IOAudioDevice::TimerEvent type. 687 * @param arg1 The IOAudioEngine that is the target of the event. 688 * @param device The IOAudioDevice that sent the timer event. 689 */ 690 static void timerCallback(OSObject *arg1, IOAudioDevice *device ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 691 692 /*! 693 * @function timerFired 694 * @abstract Indicates the timer has fired. 695 * @discussion This method is called by timerCallback to indicate the timer has fired. This method calls performErase() and performFlush() to do erase head processing and 696 * audio engine flushing each time the timer event fires. 697 */ 698 virtual void timerFired( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 699 700 /*! 701 * @function getTimerInterval 702 * @abstract Gets the timer interval for use by the timer event. 703 * @discussion This method is called each time the timer event is enabled through addTimer(). The default 704 * implementation is set to return a value such that the timer event runs n times each cycle of the audio 705 * engine through the sample buffer. The value n is stored as the instance variable: numErasesPerBuffer. 706 * The default value of numErasesPerBuffer is set to IOAUDIOENGINE_DEFAULT_NUM_ERASES_PER_BUFFER which is 4. 707 * A subclass may change the value of numErasesPerBuffer or override getTimerInterval. If it is overridden, 708 * the subclass should call the superclass's implementation, compare its interval with the superclass's and 709 * return the smaller of the two. 710 * @result Returns the interval for the timer event. 711 */ 712 virtual AbsoluteTime getTimerInterval( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 713 714 /*! 715 * @function performErase 716 * @abstract Performs erase head processing. 717 * @discussion This method is called automatically each time the timer event fires and erases the sample 718 * buffer and mix buffer from the previous location up to the current location of the audio engine. 719 */ 720 virtual void performErase( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 721 722 /*! 723 * @function performFlush 724 * @abstract Performs the flush operation. 725 * @discussion This method is called automatically each time the timer event fires. It stops the audio engine 726 * if there are no more clients and the audio engine is passed the latest flush ending position. 727 */ 728 virtual void performFlush( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 729 730 virtual void stopEngineAtPosition(IOAudioEnginePosition *endingPosition ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 731 732 virtual IOReturn mixOutputSamples(const void *sourceBuf, void *mixBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 733 virtual IOReturn clipOutputSamples(const void *mixBuf, void *sampleBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 734 virtual void resetClipPosition(IOAudioStream *audioStream, UInt32 clipSampleFrame ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 735 virtual IOReturn convertInputSamples(const void *sampleBuf, void *destBuf, UInt32 firstSampleFrame, UInt32 numSampleFrames, const IOAudioStreamFormat *streamFormat, IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 736 737 virtual void takeTimeStamp(bool incrementLoopCount = true, AbsoluteTime *timestamp = NULL ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 738 virtual IOReturn getLoopCountAndTimeStamp(UInt32 *loopCount, AbsoluteTime *timestamp ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 739 740 virtual IOReturn calculateSampleTimeout(AbsoluteTime *sampleInterval, UInt32 numSampleFrames, IOAudioEnginePosition *startingPosition, AbsoluteTime *wakeupTime ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 741 742 virtual IOReturn performFormatChange(IOAudioStream *audioStream, const IOAudioStreamFormat *newFormat, const IOAudioSampleRate *newSampleRate ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 743 744 virtual void beginConfigurationChange( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 745 virtual void completeConfigurationChange( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 746 virtual void cancelConfigurationChange( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 747 748 virtual IOReturn addDefaultAudioControl(IOAudioControl *defaultAudioControl ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 749 virtual IOReturn removeDefaultAudioControl(IOAudioControl *defaultAudioControl ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 750 virtual void removeAllDefaultAudioControls( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 751 752 virtual OSString *getGlobalUniqueID( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 753 virtual OSString *getLocalUniqueID( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 754 755protected: 756 757 /*! 758 * @function initKeys 759 * @abstract Generates the OSSymbols with the keys. 760 * @discussion Do not call this directly. This is an internal initialization routine. 761 */ 762 static void initKeys( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 763 764 virtual void setNumSampleFramesPerBuffer(UInt32 numSampleFrames ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 765 virtual UInt32 getNumSampleFramesPerBuffer( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 766 767 /*! 768 * @function setState 769 * @abstract Indicates that the audio engine is in the specified state. 770 * @discussion This method simply sets the internal state of the audio engine to the specified state. It does not 771 * affect a change to the state. It does however keep other internal state-related attributes consistent. 772 * For example, it enables or disables the timer as needed when the state changes to running or stopped. 773 * @param newState The state the audio engine is in. 774 * @result Returns the old state. 775 */ 776 virtual IOAudioEngineState setState(IOAudioEngineState newState ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 777 778 /*! 779 * @function setSampleRate 780 * @abstract Records the sample rate of the audio engine. 781 * @discussion This method must be called during initialization of a new audio engine to record the audio engine's 782 * initial sample rate. It also is intended to be used to record changes to the sample rate during use. 783 * Currently changing sample rates after the audio engine has been started is not supported. 784 * It may require that the sample buffers be re-sized. This will be available in an upcoming release. 785 * @param newSampleRate The sample rate of the audio engine in samples per second. 786 */ 787 virtual void setSampleRate(const IOAudioSampleRate *newSampleRate ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 788 789 /*! 790 * @function setSampleLatency 791 * @abstract Sets the sample latency for the audio engine. 792 * @discussion The sample latency represents the number of samples ahead of the playback head 793 * that it is safe to write into the sample buffer. The audio device API will never write 794 * closer to the playback head than the number of samples specified. For input audio engines 795 * the number of samples is behind the record head. 796 */ 797 virtual void setSampleLatency(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 798 virtual void setOutputSampleLatency(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 799 virtual void setInputSampleLatency(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 800 virtual void setSampleOffset(UInt32 numSamples ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 801 802 /*! 803 * @function setRunEraseHead 804 * @abstract Tells the audio engine whether or not to run the erase head. 805 * @discussion By default, output audio engines run the erase head and input audio engines do not. This method can 806 * be called after setDirection() is called in order to change the default behavior. 807 * @param runEraseHead The audio engine will run the erase head if this value is true. 808 */ 809 virtual void setRunEraseHead(bool runEraseHead ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 810 811 /*! 812 * @function clientClosed 813 * @abstract Called automatically when a user client closes its connection to the audio engine. 814 * @discussion This method decrements the number of connections to the audio engine and if they reach 815 * zero, the audio engine is called with a call to stopAudioEngine(). This method should not be called directly. 816 * @param client The user client that has disconnected. 817 */ 818 virtual void clientClosed(IOAudioEngineUserClient *client ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 819 820 /*! 821 * @function addTimer 822 * @abstract Enables the timer event for the audio engine. 823 * @discussion There is a timer event needed by the IOAudioEngine for processing the erase head 824 * and performing flushing operations. When the timer fires, the method timerFired() is ultimately 825 * called which in turn calls performErase() and performFlush(). This is called automatically 826 * to enable the timer event for this audio engine. It is called by setState() when the audio engine state 827 * is set to kIOAudioEngineRunning. When the timer is no longer needed, removeTimer() is called. 828 * There is no need to call this directly. 829 */ 830 virtual void addTimer( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 831 832 /*! 833 * @function removeTimer 834 * @abstract Disables the timer event for the audio engine. 835 * @discussion This method is called automatically to disable the timer event for this audio engine. 836 * There is need to call it directly. This method is called by setState() when the audio engine state 837 * is changed from kIOAudioEngineRunning to one of the stopped states. 838 */ 839 virtual void removeTimer( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 840 841 virtual void sendFormatChangeNotification(IOAudioStream *audioStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 842 virtual void sendNotification(UInt32 notificationType ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 843 844 virtual IOReturn createUserClient(task_t task, void *securityID, UInt32 type, IOAudioEngineUserClient **newUserClient ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 845 846 static IOReturn _addUserClientAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; // <rdar://7529580> 847 static IOReturn addUserClientAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 848 static IOReturn _removeUserClientAction(OSObject *target, void *arg0, void *arg1, void *arg2, void *arg3 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; // <rdar://7529580> 849 static IOReturn removeUserClientAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 850 static IOReturn detachUserClientsAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4 ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 851 852 virtual IOReturn addUserClient(IOAudioEngineUserClient *newUserClient ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 853 virtual IOReturn removeUserClient(IOAudioEngineUserClient *userClient ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 854 virtual IOReturn detachUserClients( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 855 856 virtual IOReturn startClient(IOAudioEngineUserClient *userClient ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 857 virtual IOReturn stopClient(IOAudioEngineUserClient *userClient ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 858 859 virtual IOReturn incrementActiveUserClients( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 860 virtual IOReturn decrementActiveUserClients( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 861 862 virtual void detachAudioStreams( ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 863 void setWorkLoopOnAllAudioControls(IOWorkLoop *wl ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 864 865 static inline void lockStreamForIO(IOAudioStream *stream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 866 static inline void unlockStreamForIO(IOAudioStream *stream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 867 868 // These aren't virtual by design 869 UInt32 getNextStreamID(IOAudioStream * newStream ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 870 IOAudioStream * getStreamForID(UInt32 streamID ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; 871 872 IOReturn waitForEngineResume ( void ); // <rdar://15485249> 873 874 static void setCommandGateUsage(IOAudioEngine *engine, bool increment ) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_10; // <rdar://8518215> 875 876}; 877 878#endif /* _IOKIT_IOAUDIOENGINE_H */ 879