PortAudio  2.0
pa_debugprint.h
Go to the documentation of this file.
00001 #ifndef PA_LOG_H
00002 #define PA_LOG_H
00003 /*
00004  * Log file redirector function
00005  * Copyright (c) 1999-2006 Ross Bencina, Phil Burk
00006  *
00007  * Permission is hereby granted, free of charge, to any person obtaining
00008  * a copy of this software and associated documentation files
00009  * (the "Software"), to deal in the Software without restriction,
00010  * including without limitation the rights to use, copy, modify, merge,
00011  * publish, distribute, sublicense, and/or sell copies of the Software,
00012  * and to permit persons to whom the Software is furnished to do so,
00013  * subject to the following conditions:
00014  *
00015  * The above copyright notice and this permission notice shall be
00016  * included in all copies or substantial portions of the Software.
00017  *
00018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00019  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00020  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00021  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00022  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00023  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00024  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00025  */
00026 
00027 /*
00028  * The text above constitutes the entire PortAudio license; however,
00029  * the PortAudio community also makes the following non-binding requests:
00030  *
00031  * Any person wishing to distribute modifications to the Software is
00032  * requested to send the modifications to the original developer so that
00033  * they can be incorporated into the canonical version. It is also
00034  * requested that these non-binding requests be included along with the
00035  * license above.
00036  */
00037 
00043 #ifdef __cplusplus
00044 extern "C"
00045 {
00046 #endif /* __cplusplus */
00047 
00048 
00049 
00050 void PaUtil_DebugPrint( const char *format, ... );
00051 
00052 
00053 /*
00054     The basic format for log messages is described below. If you need to
00055     add any log messages, please follow this format.
00056 
00057     Function entry (void function):
00058 
00059         "FunctionName called.\n"
00060 
00061     Function entry (non void function):
00062 
00063         "FunctionName called:\n"
00064         "\tParam1Type param1: param1Value\n"
00065         "\tParam2Type param2: param2Value\n"      (etc...)
00066 
00067 
00068     Function exit (no return value):
00069 
00070         "FunctionName returned.\n"
00071 
00072     Function exit (simple return value):
00073 
00074         "FunctionName returned:\n"
00075         "\tReturnType: returnValue\n"
00076 
00077     If the return type is an error code, the error text is displayed in ()
00078 
00079     If the return type is not an error code, but has taken a special value
00080     because an error occurred, then the reason for the error is shown in []
00081 
00082     If the return type is a struct ptr, the struct is dumped.
00083 
00084     See the code below for examples
00085 */
00086 
00096 #ifdef PA_ENABLE_DEBUG_OUTPUT
00097 #define PA_DEBUG(x) PaUtil_DebugPrint x ;
00098 #else
00099 #define PA_DEBUG(x)
00100 #endif
00101 
00102 
00103 #ifdef PA_LOG_API_CALLS
00104 #define PA_LOGAPI(x) PaUtil_DebugPrint x 
00105 
00106 #define PA_LOGAPI_ENTER(functionName) PaUtil_DebugPrint( functionName " called.\n" )
00107 
00108 #define PA_LOGAPI_ENTER_PARAMS(functionName) PaUtil_DebugPrint( functionName " called:\n" )
00109 
00110 #define PA_LOGAPI_EXIT(functionName) PaUtil_DebugPrint( functionName " returned.\n" )
00111 
00112 #define PA_LOGAPI_EXIT_PAERROR( functionName, result ) \
00113         PaUtil_DebugPrint( functionName " returned:\n" ); \
00114         PaUtil_DebugPrint("\tPaError: %d ( %s )\n", result, Pa_GetErrorText( result ) )
00115 
00116 #define PA_LOGAPI_EXIT_T( functionName, resultFormatString, result ) \
00117         PaUtil_DebugPrint( functionName " returned:\n" ); \
00118         PaUtil_DebugPrint("\t" resultFormatString "\n", result )
00119 
00120 #define PA_LOGAPI_EXIT_PAERROR_OR_T_RESULT( functionName, positiveResultFormatString, result ) \
00121         PaUtil_DebugPrint( functionName " returned:\n" ); \
00122         if( result > 0 ) \
00123         PaUtil_DebugPrint("\t" positiveResultFormatString "\n", result ); \
00124     else \
00125         PaUtil_DebugPrint("\tPaError: %d ( %s )\n", result, Pa_GetErrorText( result ) )
00126 #else
00127 #define PA_LOGAPI(x)
00128 #define PA_LOGAPI_ENTER(functionName)
00129 #define PA_LOGAPI_ENTER_PARAMS(functionName)
00130 #define PA_LOGAPI_EXIT(functionName)
00131 #define PA_LOGAPI_EXIT_PAERROR( functionName, result )
00132 #define PA_LOGAPI_EXIT_T( functionName, resultFormatString, result )
00133 #define PA_LOGAPI_EXIT_PAERROR_OR_T_RESULT( functionName, positiveResultFormatString, result )
00134 #endif
00135 
00136     
00137 typedef void (*PaUtilLogCallback ) (const char *log);
00138 
00142 void PaUtil_SetDebugPrintFunction(PaUtilLogCallback  cb);
00143 
00144 
00145 
00146 #ifdef __cplusplus
00147 }
00148 #endif /* __cplusplus */
00149 #endif /* PA_LOG_H */