00001 // © 2016 and later: Unicode, Inc. and others. 00002 // License & terms of use: http://www.unicode.org/copyright.html 00003 /* 00004 ******************************************************************************* 00005 * 00006 * Copyright (C) 2003-2013, International Business Machines 00007 * Corporation and others. All Rights Reserved. 00008 * 00009 ******************************************************************************* 00010 * file name: utrace.h 00011 * encoding: UTF-8 00012 * tab size: 8 (not used) 00013 * indentation:4 00014 * 00015 * created on: 2003aug06 00016 * created by: Markus W. Scherer 00017 * 00018 * Definitions for ICU tracing/logging. 00019 * 00020 */ 00021 00022 #ifndef __UTRACE_H__ 00023 #define __UTRACE_H__ 00024 00025 #include <stdarg.h> 00026 #include "unicode/utypes.h" 00027 00039 U_CDECL_BEGIN 00040 00046 typedef enum UTraceLevel { 00048 UTRACE_OFF=-1, 00050 UTRACE_ERROR=0, 00052 UTRACE_WARNING=3, 00054 UTRACE_OPEN_CLOSE=5, 00056 UTRACE_INFO=7, 00058 UTRACE_VERBOSE=9 00059 } UTraceLevel; 00060 00065 typedef enum UTraceFunctionNumber { 00066 UTRACE_FUNCTION_START=0, 00067 UTRACE_U_INIT=UTRACE_FUNCTION_START, 00068 UTRACE_U_CLEANUP, 00069 00070 #ifndef U_HIDE_DEPRECATED_API 00071 00075 UTRACE_FUNCTION_LIMIT, 00076 #endif // U_HIDE_DEPRECATED_API 00077 00078 UTRACE_CONVERSION_START=0x1000, 00079 UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START, 00080 UTRACE_UCNV_OPEN_PACKAGE, 00081 UTRACE_UCNV_OPEN_ALGORITHMIC, 00082 UTRACE_UCNV_CLONE, 00083 UTRACE_UCNV_CLOSE, 00084 UTRACE_UCNV_FLUSH_CACHE, 00085 UTRACE_UCNV_LOAD, 00086 UTRACE_UCNV_UNLOAD, 00087 00088 #ifndef U_HIDE_DEPRECATED_API 00089 00093 UTRACE_CONVERSION_LIMIT, 00094 #endif // U_HIDE_DEPRECATED_API 00095 00096 UTRACE_COLLATION_START=0x2000, 00097 UTRACE_UCOL_OPEN=UTRACE_COLLATION_START, 00098 UTRACE_UCOL_CLOSE, 00099 UTRACE_UCOL_STRCOLL, 00100 UTRACE_UCOL_GET_SORTKEY, 00101 UTRACE_UCOL_GETLOCALE, 00102 UTRACE_UCOL_NEXTSORTKEYPART, 00103 UTRACE_UCOL_STRCOLLITER, 00104 UTRACE_UCOL_OPEN_FROM_SHORT_STRING, 00105 UTRACE_UCOL_STRCOLLUTF8, 00107 #ifndef U_HIDE_DEPRECATED_API 00108 00112 UTRACE_COLLATION_LIMIT, 00113 #endif // U_HIDE_DEPRECATED_API 00114 00115 #ifndef U_HIDE_DRAFT_API 00116 00121 UTRACE_UDATA_START=0x3000, 00122 00138 UTRACE_UDATA_RESOURCE=UTRACE_UDATA_START, 00139 00146 UTRACE_UDATA_BUNDLE, 00147 00155 UTRACE_UDATA_DATA_FILE, 00156 00168 UTRACE_UDATA_RES_FILE, 00169 00170 #endif // U_HIDE_DRAFT_API 00171 00172 #ifndef U_HIDE_INTERNAL_API 00173 00177 UTRACE_RES_DATA_LIMIT, 00178 #endif // U_HIDE_INTERNAL_API 00179 00180 } UTraceFunctionNumber; 00181 00187 U_STABLE void U_EXPORT2 00188 utrace_setLevel(int32_t traceLevel); 00189 00195 U_STABLE int32_t U_EXPORT2 00196 utrace_getLevel(void); 00197 00198 /* Trace function pointers types ----------------------------- */ 00199 00206 typedef void U_CALLCONV 00207 UTraceEntry(const void *context, int32_t fnNumber); 00208 00222 typedef void U_CALLCONV 00223 UTraceExit(const void *context, int32_t fnNumber, 00224 const char *fmt, va_list args); 00225 00237 typedef void U_CALLCONV 00238 UTraceData(const void *context, int32_t fnNumber, int32_t level, 00239 const char *fmt, va_list args); 00240 00269 U_STABLE void U_EXPORT2 00270 utrace_setFunctions(const void *context, 00271 UTraceEntry *e, UTraceExit *x, UTraceData *d); 00272 00283 U_STABLE void U_EXPORT2 00284 utrace_getFunctions(const void **context, 00285 UTraceEntry **e, UTraceExit **x, UTraceData **d); 00286 00287 00288 00289 /* 00290 * 00291 * ICU trace format string syntax 00292 * 00293 * Format Strings are passed to UTraceData functions, and define the 00294 * number and types of the trace data being passed on each call. 00295 * 00296 * The UTraceData function, which is supplied by the application, 00297 * not by ICU, can either forward the trace data (passed via 00298 * varargs) and the format string back to ICU for formatting into 00299 * a displayable string, or it can interpret the format itself, 00300 * and do as it wishes with the trace data. 00301 * 00302 * 00303 * Goals for the format string 00304 * - basic data output 00305 * - easy to use for trace programmer 00306 * - sufficient provision for data types for trace output readability 00307 * - well-defined types and binary portable APIs 00308 * 00309 * Non-goals 00310 * - printf compatibility 00311 * - fancy formatting 00312 * - argument reordering and other internationalization features 00313 * 00314 * ICU trace format strings contain plain text with argument inserts, 00315 * much like standard printf format strings. 00316 * Each insert begins with a '%', then optionally contains a 'v', 00317 * then exactly one type character. 00318 * Two '%' in a row represent a '%' instead of an insert. 00319 * The trace format strings need not have \n at the end. 00320 * 00321 * 00322 * Types 00323 * ----- 00324 * 00325 * Type characters: 00326 * - c A char character in the default codepage. 00327 * - s A NUL-terminated char * string in the default codepage. 00328 * - S A UChar * string. Requires two params, (ptr, length). Length=-1 for nul term. 00329 * - b A byte (8-bit integer). 00330 * - h A 16-bit integer. Also a 16 bit Unicode code unit. 00331 * - d A 32-bit integer. Also a 20 bit Unicode code point value. 00332 * - l A 64-bit integer. 00333 * - p A data pointer. 00334 * 00335 * Vectors 00336 * ------- 00337 * 00338 * If the 'v' is not specified, then one item of the specified type 00339 * is passed in. 00340 * If the 'v' (for "vector") is specified, then a vector of items of the 00341 * specified type is passed in, via a pointer to the first item 00342 * and an int32_t value for the length of the vector. 00343 * Length==-1 means zero or NUL termination. Works for vectors of all types. 00344 * 00345 * Note: %vS is a vector of (UChar *) strings. The strings must 00346 * be nul terminated as there is no way to provide a 00347 * separate length parameter for each string. The length 00348 * parameter (required for all vectors) is the number of 00349 * strings, not the length of the strings. 00350 * 00351 * Examples 00352 * -------- 00353 * 00354 * These examples show the parameters that will be passed to an application's 00355 * UTraceData() function for various formats. 00356 * 00357 * - the precise formatting is up to the application! 00358 * - the examples use type casts for arguments only to _show_ the types of 00359 * arguments without needing variable declarations in the examples; 00360 * the type casts will not be necessary in actual code 00361 * 00362 * UTraceDataFunc(context, fnNumber, level, 00363 * "There is a character %c in the string %s.", // Format String 00364 * (char)c, (const char *)s); // varargs parameters 00365 * -> There is a character 0x42 'B' in the string "Bravo". 00366 * 00367 * UTraceDataFunc(context, fnNumber, level, 00368 * "Vector of bytes %vb vector of chars %vc", 00369 * (const uint8_t *)bytes, (int32_t)bytesLength, 00370 * (const char *)chars, (int32_t)charsLength); 00371 * -> Vector of bytes 00372 * 42 63 64 3f [4] 00373 * vector of chars 00374 * "Bcd?"[4] 00375 * 00376 * UTraceDataFunc(context, fnNumber, level, 00377 * "An int32_t %d and a whole bunch of them %vd", 00378 * (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength); 00379 * -> An int32_t 0xfffffffb and a whole bunch of them 00380 * fffffffb 00000005 0000010a [3] 00381 * 00382 */ 00383 00384 00385 00405 U_STABLE int32_t U_EXPORT2 00406 utrace_vformat(char *outBuf, int32_t capacity, 00407 int32_t indent, const char *fmt, va_list args); 00408 00426 U_STABLE int32_t U_EXPORT2 00427 utrace_format(char *outBuf, int32_t capacity, 00428 int32_t indent, const char *fmt, ...); 00429 00430 00431 00432 /* Trace function numbers --------------------------------------------------- */ 00433 00443 U_STABLE const char * U_EXPORT2 00444 utrace_functionName(int32_t fnNumber); 00445 00446 U_CDECL_END 00447 00448 #endif
1.6.1