4
* $Id: pa_util.h 1339 2008-02-15 07:50:33Z rossb $
5
* Portable Audio I/O Library implementation utilities header
6
* common implementation utilities and interfaces
8
* Based on the Open Source API proposed by Ross Bencina
9
* Copyright (c) 1999-2008 Ross Bencina, Phil Burk
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:
19
* The above copyright notice and this permission notice shall be
20
* included in all copies or substantial portions of the Software.
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.
32
* The text above constitutes the entire PortAudio license; however,
33
* the PortAudio community also makes the following non-binding requests:
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
45
@brief Prototypes for utility functions used by PortAudio implementations.
47
Some functions declared here are defined in pa_front.c while others
48
are implemented separately for each platform.
50
@todo Document and adhere to the alignment guarantees provided by
51
PaUtil_AllocateMemory().
55
#include "portaudio.h"
60
#endif /* __cplusplus */
63
struct PaUtilHostApiRepresentation;
66
/** Retrieve a specific host API representation. This function can be used
67
by implementations to retrieve a pointer to their representation in
68
host api specific extension functions which aren't passed a rep pointer
71
@param hostApi A pointer to a host API represenation pointer. Apon success
72
this will receive the requested representation pointer.
74
@param type A valid host API type identifier.
76
@returns An error code. If the result is PaNoError then a pointer to the
77
requested host API representation will be stored in *hostApi. If the host API
78
specified by type is not found, this function returns paHostApiNotFound.
80
PaError PaUtil_GetHostApiRepresentation( struct PaUtilHostApiRepresentation **hostApi,
81
PaHostApiTypeId type );
84
/** Convert a PortAudio device index into a host API specific device index.
85
@param hostApiDevice Pointer to a device index, on success this will recieve the
86
converted device index value.
87
@param device The PortAudio device index to convert.
88
@param hostApi The host api which the index should be converted for.
90
@returns On success returns PaNoError and places the converted index in the
91
hostApiDevice parameter.
93
PaError PaUtil_DeviceIndexToHostApiDeviceIndex(
94
PaDeviceIndex *hostApiDevice, PaDeviceIndex device,
95
struct PaUtilHostApiRepresentation *hostApi );
98
/** Set the host error information returned by Pa_GetLastHostErrorInfo. This
99
function and the paUnanticipatedHostError error code should be used as a
100
last resort. Implementors should use existing PA error codes where possible,
101
or nominate new ones. Note that at it is always better to use
102
PaUtil_SetLastHostErrorInfo() and paUnanticipatedHostError than to return an
103
ambiguous or inaccurate PaError code.
105
@param hostApiType The host API which encountered the error (ie of the caller)
107
@param errorCode The error code returned by the native API function.
109
@param errorText A string describing the error. PaUtil_SetLastHostErrorInfo
110
makes a copy of the string, so it is not necessary for the pointer to remain
111
valid after the call to PaUtil_SetLastHostErrorInfo() returns.
114
void PaUtil_SetLastHostErrorInfo( PaHostApiTypeId hostApiType, long errorCode,
115
const char *errorText );
119
/* the following functions are implemented in a platform platform specific
123
/** Allocate size bytes, guaranteed to be aligned to a FIXME byte boundary */
124
void *PaUtil_AllocateMemory( long size );
127
/** Realease block if non-NULL. block may be NULL */
128
void PaUtil_FreeMemory( void *block );
131
/** Return the number of currently allocated blocks. This function can be
132
used for detecting memory leaks.
134
@note Allocations will only be tracked if PA_TRACK_MEMORY is #defined. If
135
it isn't, this function will always return 0.
137
int PaUtil_CountCurrentlyAllocatedBlocks( void );
140
/** Initialize the clock used by PaUtil_GetTime(). Call this before calling
145
void PaUtil_InitializeClock( void );
148
/** Return the system time in seconds. Used to implement CPU load functions
150
@see PaUtil_InitializeClock
152
double PaUtil_GetTime( void );
155
/* void Pa_Sleep( long msec ); must also be implemented in per-platform .c file */
161
#endif /* __cplusplus */
162
#endif /* PA_UTIL_H */