Main Page | Class Hierarchy | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

utrace.h

00001 /* 00002 ******************************************************************************* 00003 * 00004 * Copyright (C) 2003, 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 00034 typedef enum UTraceLevel { 00036 UTRACE_OFF=-1, 00038 UTRACE_ERROR=0, 00040 UTRACE_WARNING=3, 00042 UTRACE_OPEN_CLOSE=5, 00044 UTRACE_INFO=7, 00046 UTRACE_VERBOSE=9 00047 } UTraceLevel; 00048 00049 00055 U_CAPI void U_EXPORT2 00056 utrace_setLevel(int32_t traceLevel); 00057 00063 U_CAPI int32_t U_EXPORT2 00064 utrace_getLevel(void); 00065 00066 /* Trace function pointers types ----------------------------- */ 00067 00074 typedef void U_CALLCONV 00075 UTraceEntry(const void *context, int32_t fnNumber); 00076 00090 typedef void U_CALLCONV 00091 UTraceExit(const void *context, int32_t fnNumber, 00092 const char *fmt, va_list args); 00093 00105 typedef void U_CALLCONV 00106 UTraceData(const void *context, int32_t fnNumber, int32_t level, 00107 const char *fmt, va_list args); 00108 00137 U_CAPI void U_EXPORT2 00138 utrace_setFunctions(const void *context, 00139 UTraceEntry *e, UTraceExit *x, UTraceData *d); 00140 00151 U_CAPI void U_EXPORT2 00152 utrace_getFunctions(const void **context, 00153 UTraceEntry **e, UTraceExit **x, UTraceData **d); 00154 00155 00156 00157 /* 00158 * 00159 * ICU trace format string syntax 00160 * 00161 * Format Strings are passed to UTraceData functions, and define the 00162 * number and types of the trace data being passed on each call. 00163 * 00164 * The UTraceData function, which is supplied by the application, 00165 * not by ICU, can either forward the trace data (passed via 00166 * varargs) and the format string back to ICU for formatting into 00167 * a displayable string, or it can interpret the format itself, 00168 * and do as it wishes with the trace data. 00169 * 00170 * 00171 * Goals for the format string 00172 * - basic data output 00173 * - easy to use for trace programmer 00174 * - sufficient provision for data types for trace output readability 00175 * - well-defined types and binary portable APIs 00176 * 00177 * Non-goals 00178 * - printf compatibility 00179 * - fancy formatting 00180 * - argument reordering and other internationalization features 00181 * 00182 * ICU trace format strings contain plain text with argument inserts, 00183 * much like standard printf format strings. 00184 * Each insert begins with a '%', then optionally contains a 'v', 00185 * then exactly one type character. 00186 * Two '%' in a row represent a '%' instead of an insert. 00187 * The trace format strings need not have \n at the end. 00188 * 00189 * 00190 * Types 00191 * ----- 00192 * 00193 * Type characters: 00194 * - c A char character in the default codepage. 00195 * - s A NUL-terminated char * string in the default codepage. 00196 * - S A UChar * string. Requires two params, (ptr, length). Length=-1 for nul term. 00197 * - b A byte (8-bit integer). 00198 * - h A 16-bit integer. Also a 16 bit Unicode code unit. 00199 * - d A 32-bit integer. Also a 20 bit Unicode code point value. 00200 * - l A 64-bit integer. 00201 * - p A data pointer. 00202 * 00203 * Vectors 00204 * ------- 00205 * 00206 * If the 'v' is not specified, then one item of the specified type 00207 * is passed in. 00208 * If the 'v' (for "vector") is specified, then a vector of items of the 00209 * specified type is passed in, via a pointer to the first item 00210 * and an int32_t value for the length of the vector. 00211 * Length==-1 means zero or NUL termination. Works for vectors of all types. 00212 * 00213 * Note: %vS is a vector of (UChar *) strings. The strings must 00214 * be nul terminated as there is no way to provide a 00215 * separate length parameter for each string. The length 00216 * parameter (required for all vectors) is the number of 00217 * strings, not the length of the strings. 00218 * 00219 * Examples 00220 * -------- 00221 * 00222 * These examples show the parameters that will be passed to an application's 00223 * UTraceData() function for various formats. 00224 * 00225 * - the precise formatting is up to the application! 00226 * - the examples use type casts for arguments only to _show_ the types of 00227 * arguments without needing variable declarations in the examples; 00228 * the type casts will not be necessary in actual code 00229 * 00230 * UTraceDataFunc(context, fnNumber, level, 00231 * "There is a character %c in the string %s.", // Format String 00232 * (char)c, (const char *)s); // varargs parameters 00233 * -> There is a character 0x42 'B' in the string "Bravo". 00234 * 00235 * UTraceDataFunc(context, fnNumber, level, 00236 * "Vector of bytes %vb vector of chars %vc", 00237 * (const uint8_t *)bytes, (int32_t)bytesLength, 00238 * (const char *)chars, (int32_t)charsLength); 00239 * -> Vector of bytes 00240 * 42 63 64 3f [4] 00241 * vector of chars 00242 * "Bcd?"[4] 00243 * 00244 * UTraceDataFunc(context, fnNumber, level, 00245 * "An int32_t %d and a whole bunch of them %vd", 00246 * (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength); 00247 * -> An int32_t 0xfffffffb and a whole bunch of them 00248 * fffffffb 00000005 0000010a [3] 00249 * 00250 */ 00251 00252 00253 00273 U_CAPI int32_t U_EXPORT2 00274 utrace_vformat(char *outBuf, int32_t capacity, 00275 int32_t indent, const char *fmt, va_list args); 00276 00294 U_CAPI int32_t U_EXPORT2 00295 utrace_format(char *outBuf, int32_t capacity, 00296 int32_t indent, const char *fmt, ...); 00297 00298 00299 00300 /* Trace function numbers --------------------------------------------------- */ 00301 00311 U_CAPI const char * U_EXPORT2 00312 utrace_functionName(int32_t fnNumber); 00313 00318 typedef enum UTraceFunctionNumber { 00319 UTRACE_FUNCTION_START=0, 00320 UTRACE_U_INIT=UTRACE_FUNCTION_START, 00321 UTRACE_U_CLEANUP, 00322 UTRACE_FUNCTION_LIMIT, 00323 00324 UTRACE_CONVERSION_START=0x1000, 00325 UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START, 00326 UTRACE_UCNV_OPEN_PACKAGE, 00327 UTRACE_UCNV_OPEN_ALGORITHMIC, 00328 UTRACE_UCNV_CLONE, 00329 UTRACE_UCNV_CLOSE, 00330 UTRACE_UCNV_FLUSH_CACHE, 00331 UTRACE_UCNV_LOAD, 00332 UTRACE_UCNV_UNLOAD, 00333 UTRACE_CONVERSION_LIMIT, 00334 00335 UTRACE_COLLATION_START=0x2000, 00336 UTRACE_UCOL_OPEN=UTRACE_COLLATION_START, 00337 UTRACE_UCOL_CLOSE, 00338 UTRACE_UCOL_STRCOLL, 00339 UTRACE_UCOL_GET_SORTKEY, 00340 UTRACE_UCOL_GETLOCALE, 00341 UTRACE_UCOL_NEXTSORTKEYPART, 00342 UTRACE_UCOL_STRCOLLITER, 00343 UTRACE_COLLATION_LIMIT 00344 } UTraceFunctionNumber; 00345 00346 U_CDECL_END 00347 00348 #endif

Generated on Wed Sep 15 17:18:10 2004 for ICU 2.8 by doxygen 1.3.8