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 */
160