pa_util.h (5476B)
1 #ifndef PA_UTIL_H 2 #define PA_UTIL_H 3 /* 4 * $Id$ 5 * Portable Audio I/O Library implementation utilities header 6 * common implementation utilities and interfaces 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 Prototypes for utility functions used by PortAudio implementations. 46 47 Some functions declared here are defined in pa_front.c while others 48 are implemented separately for each platform. 49 */ 50 51 52 #include "portaudio.h" 53 54 #ifdef __cplusplus 55 extern "C" 56 { 57 #endif /* __cplusplus */ 58 59 60 struct PaUtilHostApiRepresentation; 61 62 63 /** Retrieve a specific host API representation. This function can be used 64 by implementations to retrieve a pointer to their representation in 65 host api specific extension functions which aren't passed a rep pointer 66 by pa_front.c. 67 68 @param hostApi A pointer to a host API represenation pointer. Apon success 69 this will receive the requested representation pointer. 70 71 @param type A valid host API type identifier. 72 73 @returns An error code. If the result is PaNoError then a pointer to the 74 requested host API representation will be stored in *hostApi. If the host API 75 specified by type is not found, this function returns paHostApiNotFound. 76 */ 77 PaError PaUtil_GetHostApiRepresentation( struct PaUtilHostApiRepresentation **hostApi, 78 PaHostApiTypeId type ); 79 80 81 /** Convert a PortAudio device index into a host API specific device index. 82 @param hostApiDevice Pointer to a device index, on success this will recieve the 83 converted device index value. 84 @param device The PortAudio device index to convert. 85 @param hostApi The host api which the index should be converted for. 86 87 @returns On success returns PaNoError and places the converted index in the 88 hostApiDevice parameter. 89 */ 90 PaError PaUtil_DeviceIndexToHostApiDeviceIndex( 91 PaDeviceIndex *hostApiDevice, PaDeviceIndex device, 92 struct PaUtilHostApiRepresentation *hostApi ); 93 94 95 /** Set the host error information returned by Pa_GetLastHostErrorInfo. This 96 function and the paUnanticipatedHostError error code should be used as a 97 last resort. Implementors should use existing PA error codes where possible, 98 or nominate new ones. Note that at it is always better to use 99 PaUtil_SetLastHostErrorInfo() and paUnanticipatedHostError than to return an 100 ambiguous or inaccurate PaError code. 101 102 @param hostApiType The host API which encountered the error (ie of the caller) 103 104 @param errorCode The error code returned by the native API function. 105 106 @param errorText A string describing the error. PaUtil_SetLastHostErrorInfo 107 makes a copy of the string, so it is not necessary for the pointer to remain 108 valid after the call to PaUtil_SetLastHostErrorInfo() returns. 109 110 */ 111 void PaUtil_SetLastHostErrorInfo( PaHostApiTypeId hostApiType, long errorCode, 112 const char *errorText ); 113 114 115 116 /* the following functions are implemented in a platform platform specific 117 .c file 118 */ 119 120 /** Allocate size bytes, guaranteed to be aligned to a FIXME byte boundary */ 121 void *PaUtil_AllocateMemory( long size ); 122 123 124 /** Realease block if non-NULL. block may be NULL */ 125 void PaUtil_FreeMemory( void *block ); 126 127 128 /** Return the number of currently allocated blocks. This function can be 129 used for detecting memory leaks. 130 131 @note Allocations will only be tracked if PA_TRACK_MEMORY is #defined. If 132 it isn't, this function will always return 0. 133 */ 134 int PaUtil_CountCurrentlyAllocatedBlocks( void ); 135 136 137 /** Initialize the clock used by PaUtil_GetTime(). Call this before calling 138 PaUtil_GetTime. 139 140 @see PaUtil_GetTime 141 */ 142 void PaUtil_InitializeClock( void ); 143 144 145 /** Return the system time in seconds. Used to implement CPU load functions 146 147 @see PaUtil_InitializeClock 148 */ 149 double PaUtil_GetTime( void ); 150 151 152 /* void Pa_Sleep( long msec ); must also be implemented in per-platform .c file */ 153 154 155 156 #ifdef __cplusplus 157 } 158 #endif /* __cplusplus */ 159 #endif /* PA_UTIL_H */