00001 /* 00002 ******************************************************************************* 00003 * 00004 * Copyright (C) 2003-2004, International Business Machines 00005 * Corporation and others. All Rights Reserved. 00006 * 00007 ******************************************************************************* 00008 * file name: utrace.h 00009 * encoding: US-ASCII 00010 * tab size: 8 (not used) 00011 * indentation:4 00012 * 00013 * created on: 2003aug06 00014 * created by: Markus W. Scherer 00015 * 00016 * Definitions for ICU tracing/logging. 00017 * 00018 */ 00019 00020 #ifndef __UTRACE_H__ 00021 #define __UTRACE_H__ 00022 00023 #include <stdarg.h> 00024 #include "unicode/utypes.h" 00025 00026 U_CDECL_BEGIN 00027 00028 #ifndef U_HIDE_DRAFT_API 00029 00035 typedef enum UTraceLevel { 00037 UTRACE_OFF=-1, 00039 UTRACE_ERROR=0, 00041 UTRACE_WARNING=3, 00043 UTRACE_OPEN_CLOSE=5, 00045 UTRACE_INFO=7, 00047 UTRACE_VERBOSE=9 00048 } UTraceLevel; 00049 00054 typedef enum UTraceFunctionNumber { 00055 UTRACE_FUNCTION_START=0, 00056 UTRACE_U_INIT=UTRACE_FUNCTION_START, 00057 UTRACE_U_CLEANUP, 00058 UTRACE_FUNCTION_LIMIT, 00059 00060 UTRACE_CONVERSION_START=0x1000, 00061 UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START, 00062 UTRACE_UCNV_OPEN_PACKAGE, 00063 UTRACE_UCNV_OPEN_ALGORITHMIC, 00064 UTRACE_UCNV_CLONE, 00065 UTRACE_UCNV_CLOSE, 00066 UTRACE_UCNV_FLUSH_CACHE, 00067 UTRACE_UCNV_LOAD, 00068 UTRACE_UCNV_UNLOAD, 00069 UTRACE_CONVERSION_LIMIT, 00070 00071 UTRACE_COLLATION_START=0x2000, 00072 UTRACE_UCOL_OPEN=UTRACE_COLLATION_START, 00073 UTRACE_UCOL_CLOSE, 00074 UTRACE_UCOL_STRCOLL, 00075 UTRACE_UCOL_GET_SORTKEY, 00076 UTRACE_UCOL_GETLOCALE, 00077 UTRACE_UCOL_NEXTSORTKEYPART, 00078 UTRACE_UCOL_STRCOLLITER, 00079 UTRACE_UCOL_OPEN_FROM_SHORT_STRING, 00080 UTRACE_COLLATION_LIMIT 00081 } UTraceFunctionNumber; 00082 00083 #endif /*U_HIDE_DRAFT_API*/ 00084 00090 U_DRAFT void U_EXPORT2 00091 utrace_setLevel(int32_t traceLevel); 00092 00098 U_DRAFT int32_t U_EXPORT2 00099 utrace_getLevel(void); 00100 00101 /* Trace function pointers types ----------------------------- */ 00102 00109 typedef void U_CALLCONV 00110 UTraceEntry(const void *context, int32_t fnNumber); 00111 00125 typedef void U_CALLCONV 00126 UTraceExit(const void *context, int32_t fnNumber, 00127 const char *fmt, va_list args); 00128 00140 typedef void U_CALLCONV 00141 UTraceData(const void *context, int32_t fnNumber, int32_t level, 00142 const char *fmt, va_list args); 00143 00172 U_DRAFT void U_EXPORT2 00173 utrace_setFunctions(const void *context, 00174 UTraceEntry *e, UTraceExit *x, UTraceData *d); 00175 00186 U_DRAFT void U_EXPORT2 00187 utrace_getFunctions(const void **context, 00188 UTraceEntry **e, UTraceExit **x, UTraceData **d); 00189 00190 00191 00192 /* 00193 * 00194 * ICU trace format string syntax 00195 * 00196 * Format Strings are passed to UTraceData functions, and define the 00197 * number and types of the trace data being passed on each call. 00198 * 00199 * The UTraceData function, which is supplied by the application, 00200 * not by ICU, can either forward the trace data (passed via 00201 * varargs) and the format string back to ICU for formatting into 00202 * a displayable string, or it can interpret the format itself, 00203 * and do as it wishes with the trace data. 00204 * 00205 * 00206 * Goals for the format string 00207 * - basic data output 00208 * - easy to use for trace programmer 00209 * - sufficient provision for data types for trace output readability 00210 * - well-defined types and binary portable APIs 00211 * 00212 * Non-goals 00213 * - printf compatibility 00214 * - fancy formatting 00215 * - argument reordering and other internationalization features 00216 * 00217 * ICU trace format strings contain plain text with argument inserts, 00218 * much like standard printf format strings. 00219 * Each insert begins with a '%', then optionally contains a 'v', 00220 * then exactly one type character. 00221 * Two '%' in a row represent a '%' instead of an insert. 00222 * The trace format strings need not have \n at the end. 00223 * 00224 * 00225 * Types 00226 * ----- 00227 * 00228 * Type characters: 00229 * - c A char character in the default codepage. 00230 * - s A NUL-terminated char * string in the default codepage. 00231 * - S A UChar * string. Requires two params, (ptr, length). Length=-1 for nul term. 00232 * - b A byte (8-bit integer). 00233 * - h A 16-bit integer. Also a 16 bit Unicode code unit. 00234 * - d A 32-bit integer. Also a 20 bit Unicode code point value. 00235 * - l A 64-bit integer. 00236 * - p A data pointer. 00237 * 00238 * Vectors 00239 * ------- 00240 * 00241 * If the 'v' is not specified, then one item of the specified type 00242 * is passed in. 00243 * If the 'v' (for "vector") is specified, then a vector of items of the 00244 * specified type is passed in, via a pointer to the first item 00245 * and an int32_t value for the length of the vector. 00246 * Length==-1 means zero or NUL termination. Works for vectors of all types. 00247 * 00248 * Note: %vS is a vector of (UChar *) strings. The strings must 00249 * be nul terminated as there is no way to provide a 00250 * separate length parameter for each string. The length 00251 * parameter (required for all vectors) is the number of 00252 * strings, not the length of the strings. 00253 * 00254 * Examples 00255 * -------- 00256 * 00257 * These examples show the parameters that will be passed to an application's 00258 * UTraceData() function for various formats. 00259 * 00260 * - the precise formatting is up to the application! 00261 * - the examples use type casts for arguments only to _show_ the types of 00262 * arguments without needing variable declarations in the examples; 00263 * the type casts will not be necessary in actual code 00264 * 00265 * UTraceDataFunc(context, fnNumber, level, 00266 * "There is a character %c in the string %s.", // Format String 00267 * (char)c, (const char *)s); // varargs parameters 00268 * -> There is a character 0x42 'B' in the string "Bravo". 00269 * 00270 * UTraceDataFunc(context, fnNumber, level, 00271 * "Vector of bytes %vb vector of chars %vc", 00272 * (const uint8_t *)bytes, (int32_t)bytesLength, 00273 * (const char *)chars, (int32_t)charsLength); 00274 * -> Vector of bytes 00275 * 42 63 64 3f [4] 00276 * vector of chars 00277 * "Bcd?"[4] 00278 * 00279 * UTraceDataFunc(context, fnNumber, level, 00280 * "An int32_t %d and a whole bunch of them %vd", 00281 * (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength); 00282 * -> An int32_t 0xfffffffb and a whole bunch of them 00283 * fffffffb 00000005 0000010a [3] 00284 * 00285 */ 00286 00287 00288 00308 U_DRAFT int32_t U_EXPORT2 00309 utrace_vformat(char *outBuf, int32_t capacity, 00310 int32_t indent, const char *fmt, va_list args); 00311 00329 U_DRAFT int32_t U_EXPORT2 00330 utrace_format(char *outBuf, int32_t capacity, 00331 int32_t indent, const char *fmt, ...); 00332 00333 00334 00335 /* Trace function numbers --------------------------------------------------- */ 00336 00346 U_DRAFT const char * U_EXPORT2 00347 utrace_functionName(int32_t fnNumber); 00348 00349 U_CDECL_END 00350 00351 #endif