pa_hostapi.h (13319B)
1 #ifndef PA_HOSTAPI_H 2 #define PA_HOSTAPI_H 3 /* 4 * $Id$ 5 * Portable Audio I/O Library 6 * host api representation 7 * 8 * Based on the Open Source API proposed by Ross Bencina 9 * Copyright (c) 1999-2008 Ross Bencina, Phil Burk 10 * 11 * Permission is hereby granted, free of charge, to any person obtaining 12 * a copy of this software and associated documentation files 13 * (the "Software"), to deal in the Software without restriction, 14 * including without limitation the rights to use, copy, modify, merge, 15 * publish, distribute, sublicense, and/or sell copies of the Software, 16 * and to permit persons to whom the Software is furnished to do so, 17 * subject to the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be 20 * included in all copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 23 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 24 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 25 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 26 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 27 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 28 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 29 */ 30 31 /* 32 * The text above constitutes the entire PortAudio license; however, 33 * the PortAudio community also makes the following non-binding requests: 34 * 35 * Any person wishing to distribute modifications to the Software is 36 * requested to send the modifications to the original developer so that 37 * they can be incorporated into the canonical version. It is also 38 * requested that these non-binding requests be included along with the 39 * license above. 40 */ 41 42 /** @file 43 @ingroup common_src 44 45 @brief Interfaces and representation structures used by pa_front.c 46 to manage and communicate with host API implementations. 47 */ 48 49 #include "portaudio.h" 50 51 /** 52 The PA_NO_* host API macros are now deprecated in favor of PA_USE_* macros. 53 PA_USE_* indicates whether a particular host API will be initialized by PortAudio. 54 An undefined or 0 value indicates that the host API will not be used. A value of 1 55 indicates that the host API will be used. PA_USE_* macros should be left undefined 56 or defined to either 0 or 1. 57 58 The code below ensures that PA_USE_* macros are always defined and have value 59 0 or 1. Undefined symbols are defaulted to 0. Symbols that are neither 0 nor 1 60 are defaulted to 1. 61 */ 62 63 #ifndef PA_USE_SKELETON 64 #define PA_USE_SKELETON 0 65 #elif (PA_USE_SKELETON != 0) && (PA_USE_SKELETON != 1) 66 #undef PA_USE_SKELETON 67 #define PA_USE_SKELETON 1 68 #endif 69 70 #if defined(PA_NO_ASIO) || defined(PA_NO_DS) || defined(PA_NO_WMME) || defined(PA_NO_WASAPI) || defined(PA_NO_WDMKS) 71 #error "Portaudio: PA_NO_<APINAME> is no longer supported, please remove definition and use PA_USE_<APINAME> instead" 72 #endif 73 74 #ifndef PA_USE_ASIO 75 #define PA_USE_ASIO 0 76 #elif (PA_USE_ASIO != 0) && (PA_USE_ASIO != 1) 77 #undef PA_USE_ASIO 78 #define PA_USE_ASIO 1 79 #endif 80 81 #ifndef PA_USE_DS 82 #define PA_USE_DS 0 83 #elif (PA_USE_DS != 0) && (PA_USE_DS != 1) 84 #undef PA_USE_DS 85 #define PA_USE_DS 1 86 #endif 87 88 #ifndef PA_USE_WMME 89 #define PA_USE_WMME 0 90 #elif (PA_USE_WMME != 0) && (PA_USE_WMME != 1) 91 #undef PA_USE_WMME 92 #define PA_USE_WMME 1 93 #endif 94 95 #ifndef PA_USE_WASAPI 96 #define PA_USE_WASAPI 0 97 #elif (PA_USE_WASAPI != 0) && (PA_USE_WASAPI != 1) 98 #undef PA_USE_WASAPI 99 #define PA_USE_WASAPI 1 100 #endif 101 102 #ifndef PA_USE_WDMKS 103 #define PA_USE_WDMKS 0 104 #elif (PA_USE_WDMKS != 0) && (PA_USE_WDMKS != 1) 105 #undef PA_USE_WDMKS 106 #define PA_USE_WDMKS 1 107 #endif 108 109 /* Set default values for Unix based APIs. */ 110 #if defined(PA_NO_OSS) || defined(PA_NO_ALSA) || defined(PA_NO_JACK) || defined(PA_NO_COREAUDIO) || defined(PA_NO_SGI) || defined(PA_NO_ASIHPI) 111 #error "Portaudio: PA_NO_<APINAME> is no longer supported, please remove definition and use PA_USE_<APINAME> instead" 112 #endif 113 114 #ifndef PA_USE_OSS 115 #define PA_USE_OSS 0 116 #elif (PA_USE_OSS != 0) && (PA_USE_OSS != 1) 117 #undef PA_USE_OSS 118 #define PA_USE_OSS 1 119 #endif 120 121 #ifndef PA_USE_ALSA 122 #define PA_USE_ALSA 0 123 #elif (PA_USE_ALSA != 0) && (PA_USE_ALSA != 1) 124 #undef PA_USE_ALSA 125 #define PA_USE_ALSA 1 126 #endif 127 128 #ifndef PA_USE_JACK 129 #define PA_USE_JACK 0 130 #elif (PA_USE_JACK != 0) && (PA_USE_JACK != 1) 131 #undef PA_USE_JACK 132 #define PA_USE_JACK 1 133 #endif 134 135 #ifndef PA_USE_SGI 136 #define PA_USE_SGI 0 137 #elif (PA_USE_SGI != 0) && (PA_USE_SGI != 1) 138 #undef PA_USE_SGI 139 #define PA_USE_SGI 1 140 #endif 141 142 #ifndef PA_USE_COREAUDIO 143 #define PA_USE_COREAUDIO 0 144 #elif (PA_USE_COREAUDIO != 0) && (PA_USE_COREAUDIO != 1) 145 #undef PA_USE_COREAUDIO 146 #define PA_USE_COREAUDIO 1 147 #endif 148 149 #ifndef PA_USE_ASIHPI 150 #define PA_USE_ASIHPI 0 151 #elif (PA_USE_ASIHPI != 0) && (PA_USE_ASIHPI != 1) 152 #undef PA_USE_ASIHPI 153 #define PA_USE_ASIHPI 1 154 #endif 155 156 #ifdef __cplusplus 157 extern "C" 158 { 159 #endif /* __cplusplus */ 160 161 162 /** **FOR THE USE OF pa_front.c ONLY** 163 Do NOT use fields in this structure, they my change at any time. 164 Use functions defined in pa_util.h if you think you need functionality 165 which can be derived from here. 166 */ 167 typedef struct PaUtilPrivatePaFrontHostApiInfo { 168 169 170 unsigned long baseDeviceIndex; 171 }PaUtilPrivatePaFrontHostApiInfo; 172 173 174 /** The common header for all data structures whose pointers are passed through 175 the hostApiSpecificStreamInfo field of the PaStreamParameters structure. 176 Note that in order to keep the public PortAudio interface clean, this structure 177 is not used explicitly when declaring hostApiSpecificStreamInfo data structures. 178 However, some code in pa_front depends on the first 3 members being equivalent 179 with this structure. 180 @see PaStreamParameters 181 */ 182 typedef struct PaUtilHostApiSpecificStreamInfoHeader 183 { 184 unsigned long size; /**< size of whole structure including this header */ 185 PaHostApiTypeId hostApiType; /**< host API for which this data is intended */ 186 unsigned long version; /**< structure version */ 187 } PaUtilHostApiSpecificStreamInfoHeader; 188 189 190 191 /** A structure representing the interface to a host API. Contains both 192 concrete data and pointers to functions which implement the interface. 193 */ 194 typedef struct PaUtilHostApiRepresentation { 195 PaUtilPrivatePaFrontHostApiInfo privatePaFrontInfo; 196 197 /** The host api implementation should populate the info field. In the 198 case of info.defaultInputDevice and info.defaultOutputDevice the 199 values stored should be 0 based indices within the host api's own 200 device index range (0 to deviceCount). These values will be converted 201 to global device indices by pa_front after PaUtilHostApiInitializer() 202 returns. 203 */ 204 PaHostApiInfo info; 205 206 PaDeviceInfo** deviceInfos; 207 208 /** 209 (*Terminate)() is guaranteed to be called with a valid <hostApi> 210 parameter, which was previously returned from the same implementation's 211 initializer. 212 */ 213 void (*Terminate)( struct PaUtilHostApiRepresentation *hostApi ); 214 215 /** 216 The inputParameters and outputParameters pointers should not be saved 217 as they will not remain valid after OpenStream is called. 218 219 220 The following guarantees are made about parameters to (*OpenStream)(): 221 222 [NOTE: the following list up to *END PA FRONT VALIDATIONS* should be 223 kept in sync with the one for ValidateOpenStreamParameters and 224 Pa_OpenStream in pa_front.c] 225 226 PaHostApiRepresentation *hostApi 227 - is valid for this implementation 228 229 PaStream** stream 230 - is non-null 231 232 - at least one of inputParameters & outputParmeters is valid (not NULL) 233 234 - if inputParameters & outputParmeters are both valid, that 235 inputParameters->device & outputParmeters->device both use the same host api 236 237 PaDeviceIndex inputParameters->device 238 - is within range (0 to Pa_CountDevices-1) Or: 239 - is paUseHostApiSpecificDeviceSpecification and 240 inputParameters->hostApiSpecificStreamInfo is non-NULL and refers 241 to a valid host api 242 243 int inputParameters->numChannels 244 - if inputParameters->device is not paUseHostApiSpecificDeviceSpecification, numInputChannels is > 0 245 - upper bound is NOT validated against device capabilities 246 247 PaSampleFormat inputParameters->sampleFormat 248 - is one of the sample formats defined in portaudio.h 249 250 void *inputParameters->hostApiSpecificStreamInfo 251 - if supplied its hostApi field matches the input device's host Api 252 253 PaDeviceIndex outputParmeters->device 254 - is within range (0 to Pa_CountDevices-1) 255 256 int outputParmeters->numChannels 257 - if inputDevice is valid, numInputChannels is > 0 258 - upper bound is NOT validated against device capabilities 259 260 PaSampleFormat outputParmeters->sampleFormat 261 - is one of the sample formats defined in portaudio.h 262 263 void *outputParmeters->hostApiSpecificStreamInfo 264 - if supplied its hostApi field matches the output device's host Api 265 266 double sampleRate 267 - is not an 'absurd' rate (less than 1000. or greater than 384000.) 268 - sampleRate is NOT validated against device capabilities 269 270 PaStreamFlags streamFlags 271 - unused platform neutral flags are zero 272 - paNeverDropInput is only used for full-duplex callback streams 273 with variable buffer size (paFramesPerBufferUnspecified) 274 275 [*END PA FRONT VALIDATIONS*] 276 277 278 The following validations MUST be performed by (*OpenStream)(): 279 280 - check that input device can support numInputChannels 281 282 - check that input device can support inputSampleFormat, or that 283 we have the capability to convert from outputSampleFormat to 284 a native format 285 286 - if inputStreamInfo is supplied, validate its contents, 287 or return an error if no inputStreamInfo is expected 288 289 - check that output device can support numOutputChannels 290 291 - check that output device can support outputSampleFormat, or that 292 we have the capability to convert from outputSampleFormat to 293 a native format 294 295 - if outputStreamInfo is supplied, validate its contents, 296 or return an error if no outputStreamInfo is expected 297 298 - if a full duplex stream is requested, check that the combination 299 of input and output parameters is supported 300 301 - check that the device supports sampleRate 302 303 - alter sampleRate to a close allowable rate if necessary 304 305 - validate inputLatency and outputLatency 306 307 - validate any platform specific flags, if flags are supplied they 308 must be valid. 309 */ 310 PaError (*OpenStream)( struct PaUtilHostApiRepresentation *hostApi, 311 PaStream** stream, 312 const PaStreamParameters *inputParameters, 313 const PaStreamParameters *outputParameters, 314 double sampleRate, 315 unsigned long framesPerCallback, 316 PaStreamFlags streamFlags, 317 PaStreamCallback *streamCallback, 318 void *userData ); 319 320 321 PaError (*IsFormatSupported)( struct PaUtilHostApiRepresentation *hostApi, 322 const PaStreamParameters *inputParameters, 323 const PaStreamParameters *outputParameters, 324 double sampleRate ); 325 } PaUtilHostApiRepresentation; 326 327 328 /** Prototype for the initialization function which must be implemented by every 329 host API. 330 331 This function should only return an error other than paNoError if it encounters 332 an unexpected and fatal error (memory allocation error for example). In general, 333 there may be conditions under which it returns a NULL interface pointer and also 334 returns paNoError. For example, if the ASIO implementation detects that ASIO is 335 not installed, it should return a NULL interface, and paNoError. 336 337 @see paHostApiInitializers 338 */ 339 typedef PaError PaUtilHostApiInitializer( PaUtilHostApiRepresentation**, PaHostApiIndex ); 340 341 342 /** paHostApiInitializers is a NULL-terminated array of host API initialization 343 functions. These functions are called by pa_front.c to initialize the host APIs 344 when the client calls Pa_Initialize(). 345 346 The initialization functions are invoked in order. 347 348 The first successfully initialized host API that has a default input *or* output 349 device is used as the default PortAudio host API. This is based on the logic that 350 there is only one default host API, and it must contain the default input and output 351 devices (if defined). 352 353 There is a platform specific file that defines paHostApiInitializers for that 354 platform, pa_win/pa_win_hostapis.c contains the Win32 definitions for example. 355 */ 356 extern PaUtilHostApiInitializer *paHostApiInitializers[]; 357 358 359 #ifdef __cplusplus 360 } 361 #endif /* __cplusplus */ 362 #endif /* PA_HOSTAPI_H */