pa_util.h File Reference

Prototypes for utility functions used by PortAudio implementations. More...

#include "portaudio.h"

Go to the source code of this file.

Macros
#define	PA_STRINGIZE_HELPER(x)   #x
#define	PA_STRINGIZE(x)   PA_STRINGIZE_HELPER(x)

Functions
PaError	PaUtil_GetHostApiRepresentation (struct PaUtilHostApiRepresentation **hostApi, PaHostApiTypeId type)
PaError	PaUtil_DeviceIndexToHostApiDeviceIndex (PaDeviceIndex *hostApiDevice, PaDeviceIndex device, struct PaUtilHostApiRepresentation *hostApi)
void	PaUtil_SetLastHostErrorInfo (PaHostApiTypeId hostApiType, long errorCode, const char *errorText)
void *	PaUtil_AllocateZeroInitializedMemory (long size)
void	PaUtil_FreeMemory (void *block)
int	PaUtil_CountCurrentlyAllocatedBlocks (void)
void	PaUtil_InitializeClock (void)
double	PaUtil_GetTime (void)

Detailed Description

Prototypes for utility functions used by PortAudio implementations.

Some functions declared here are defined in pa_front.c while others are implemented separately for each platform.

Macro Definition Documentation

#define PA_STRINGIZE

(

x

)

PA_STRINGIZE_HELPER(x)

#define PA_STRINGIZE_HELPER

(

x

)

#x

Preprocessor Utilities

Function Documentation

void* PaUtil_AllocateZeroInitializedMemory

(

long

size

)

Allocate size bytes of zero-initialized memory.

Guaranteed to be aligned to a FIXME byte boundary.

Referenced by InitializeWave(), OpenStream(), PaAlsa_Initialize(), PaAsiHpi_Initialize(), PaAsio_Initialize(), PaJack_Initialize(), PaMacCore_Initialize(), PaOSS_Initialize(), PaPulseAudio_New(), PaPulseAudio_RenameSink(), PaPulseAudio_RenameSource(), PaSkeleton_Initialize(), PaSndio_Initialize(), PaUtil_CreateAllocationGroup(), PaUtil_GroupAllocateZeroInitializedMemory(), PaUtil_InitializeBufferProcessor(), PaWasapi_Initialize(), PaWinDs_Initialize(), PaWinMme_Initialize(), PaWinWdm_Initialize(), and ProcessingThread().

int PaUtil_CountCurrentlyAllocatedBlocks

(

void

)

Return the number of currently allocated blocks. This function can be used for detecting memory leaks.

Note

Allocations will only be tracked if PA_TRACK_MEMORY is #defined. If it isn't, this function will always return 0.

PaError PaUtil_DeviceIndexToHostApiDeviceIndex	(	PaDeviceIndex *	hostApiDevice,
		PaDeviceIndex	device,
		struct PaUtilHostApiRepresentation *	hostApi
	)

Convert a PortAudio device index into a host API specific device index.

Parameters

hostApiDevice	Pointer to a device index, on success this will receive the converted device index value.
device	The PortAudio device index to convert.
hostApi	The host api which the index should be converted for.

Returns

On success returns PaNoError and places the converted index in the hostApiDevice parameter.

References PaUtilPrivatePaFrontHostApiInfo::baseDeviceIndex, PaHostApiInfo::deviceCount, PaUtilHostApiRepresentation::info, paInvalidDevice, paNoError, and PaUtilHostApiRepresentation::privatePaFrontInfo.

Referenced by PaAsio_GetAvailableBufferSizes(), PaAsio_GetInputChannelName(), PaAsio_GetOutputChannelName(), PaAsio_ShowControlPanel(), PaMacCore_GetBufferSizeRange(), PaPulseAudio_StartStreamCb(), and PaWasapi_IsLoopback().

void PaUtil_FreeMemory

(

void *

block

)

Release block allocated by PaUtil_AllocateZeroInitializedMemory()

if block is non-NULL. block may be NULL

Referenced by OpenStream(), PaAlsa_Initialize(), PaAsiHpi_Initialize(), PaAsio_Initialize(), PaJack_Initialize(), PaMacCore_Initialize(), PaOSS_Initialize(), PaPulseAudio_CloseStreamCb(), PaPulseAudio_Free(), PaPulseAudio_RenameSink(), PaPulseAudio_RenameSource(), PaSkeleton_Initialize(), PaUtil_CreateAllocationGroup(), PaUtil_DestroyAllocationGroup(), PaUtil_FreeAllAllocations(), PaUtil_GroupFreeMemory(), PaUtil_InitializeBufferProcessor(), PaUtil_TerminateBufferProcessor(), PaWin_WDMKS_QueryFilterMaximumChannelCount(), PaWinMme_Initialize(), and ProcessingThread().

PaError PaUtil_GetHostApiRepresentation	(	struct PaUtilHostApiRepresentation **	hostApi,
		PaHostApiTypeId	type
	)

Retrieve a specific host API representation. This function can be used by implementations to retrieve a pointer to their representation in host api specific extension functions which aren't passed a rep pointer by pa_front.c.

Parameters

hostApi	A pointer to a host API representation pointer. Upon success this will receive the requested representation pointer.
type	A valid host API type identifier.

Returns

An error code. If the result is PaNoError then a pointer to the requested host API representation will be stored in *hostApi. If the host API specified by type is not found, this function returns paHostApiNotFound.

References PA_IS_INITIALISED_, paHostApiNotFound, paNoError, and paNotInitialized.

Referenced by PaAsio_GetAvailableBufferSizes(), PaAsio_GetInputChannelName(), PaAsio_GetOutputChannelName(), PaAsio_ShowControlPanel(), PaJack_GetClientName(), PaMacCore_GetBufferSizeRange(), and PaMacCore_GetChannelName().

double PaUtil_GetTime

(

void

)

Return the system time in seconds. Used to implement CPU load functions

Note

Do not make assumptions about which underlying clock is used to implement PaUtil_GetTime, or use the current implementation as a guide. Do not use this function when a specific clock is required (e.g. when using platform APIs such as pthreads). If you need to use a specific clock, use a native API that returns that clock.

See Also

PaUtil_InitializeClock

Referenced by PaUnixThread_New(), PaUtil_BeginCpuLoadMeasurement(), PaUtil_EndCpuLoadMeasurement(), PaWinWdm_Initialize(), ProcessingThreadProc(), and waitUntilBlioWriteBufferIsEmpty().

void PaUtil_InitializeClock

(

void

)

Initialize the clock used by PaUtil_GetTime(). Call this before calling PaUtil_GetTime.

See Also

PaUtil_GetTime

Referenced by Pa_Initialize().

void PaUtil_SetLastHostErrorInfo	(	PaHostApiTypeId	hostApiType,
		long	errorCode,
		const char *	errorText
	)

Set the host error information returned by Pa_GetLastHostErrorInfo. This function and the paUnanticipatedHostError error code should be used as a last resort. Implementors should use existing PA error codes where possible, or nominate new ones. Note that at it is always better to use PaUtil_SetLastHostErrorInfo() and paUnanticipatedHostError than to return an ambiguous or inaccurate PaError code.

Parameters

hostApiType	The host API which encountered the error (ie of the caller)
errorCode	The error code returned by the native API function.
errorText	A string describing the error. PaUtil_SetLastHostErrorInfo makes a copy of the string, so it is not necessary for the pointer to remain valid after the call to PaUtil_SetLastHostErrorInfo() returns.

References PaHostErrorInfo::errorCode, PaHostErrorInfo::hostApiType, and PA_LAST_HOST_ERROR_TEXT_LENGTH_.

Referenced by PaMacCore_SetError(), PaMacCore_SetUnixError(), and PaWinUtil_SetLastSystemErrorInfo().