ICU 67.1: utrace.h Source File

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 #ifndef U_HIDE_DRAFT_API
00181 
00185     UTRACE_UBRK_START=0x4000,
00186 
00192     UTRACE_UBRK_CREATE_CHARACTER = UTRACE_UBRK_START,
00193 
00199     UTRACE_UBRK_CREATE_WORD,
00200 
00209     UTRACE_UBRK_CREATE_LINE,
00210 
00216     UTRACE_UBRK_CREATE_SENTENCE,
00217 
00223     UTRACE_UBRK_CREATE_TITLE,
00224 
00233     UTRACE_UBRK_CREATE_BREAK_ENGINE,
00234 
00235 #endif  // U_HIDE_DRAFT_API
00236 
00237 #ifndef U_HIDE_INTERNAL_API
00238 
00242     UTRACE_UBRK_LIMIT,
00243 #endif  // U_HIDE_INTERNAL_API
00244 
00245 } UTraceFunctionNumber;
00246 
00252 U_STABLE void U_EXPORT2
00253 utrace_setLevel(int32_t traceLevel);
00254 
00260 U_STABLE int32_t U_EXPORT2
00261 utrace_getLevel(void);
00262 
00263 /* Trace function pointers types  ----------------------------- */
00264 
00271 typedef void U_CALLCONV
00272 UTraceEntry(const void *context, int32_t fnNumber);
00273 
00287 typedef void U_CALLCONV
00288 UTraceExit(const void *context, int32_t fnNumber, 
00289            const char *fmt, va_list args);
00290 
00302 typedef void U_CALLCONV
00303 UTraceData(const void *context, int32_t fnNumber, int32_t level,
00304            const char *fmt, va_list args);
00305 
00334 U_STABLE void U_EXPORT2
00335 utrace_setFunctions(const void *context,
00336                     UTraceEntry *e, UTraceExit *x, UTraceData *d);
00337 
00348 U_STABLE void U_EXPORT2
00349 utrace_getFunctions(const void **context,
00350                     UTraceEntry **e, UTraceExit **x, UTraceData **d);
00351 
00352 
00353 
00354 /*
00355  *
00356  * ICU trace format string syntax
00357  *
00358  * Format Strings are passed to UTraceData functions, and define the
00359  * number and types of the trace data being passed on each call.
00360  *
00361  * The UTraceData function, which is supplied by the application,
00362  * not by ICU, can either forward the trace data (passed via
00363  * varargs) and the format string back to ICU for formatting into
00364  * a displayable string, or it can interpret the format itself,
00365  * and do as it wishes with the trace data.
00366  *
00367  *
00368  * Goals for the format string
00369  * - basic data output
00370  * - easy to use for trace programmer
00371  * - sufficient provision for data types for trace output readability
00372  * - well-defined types and binary portable APIs
00373  *
00374  * Non-goals
00375  * - printf compatibility
00376  * - fancy formatting
00377  * - argument reordering and other internationalization features
00378  *
00379  * ICU trace format strings contain plain text with argument inserts,
00380  * much like standard printf format strings.
00381  * Each insert begins with a '%', then optionally contains a 'v',
00382  * then exactly one type character.
00383  * Two '%' in a row represent a '%' instead of an insert.
00384  * The trace format strings need not have \n at the end.
00385  *
00386  *
00387  * Types
00388  * -----
00389  *
00390  * Type characters:
00391  * - c A char character in the default codepage.
00392  * - s A NUL-terminated char * string in the default codepage.
00393  * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
00394  * - b A byte (8-bit integer).
00395  * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
00396  * - d A 32-bit integer.  Also a 20 bit Unicode code point value. 
00397  * - l A 64-bit integer.
00398  * - p A data pointer.
00399  *
00400  * Vectors
00401  * -------
00402  *
00403  * If the 'v' is not specified, then one item of the specified type
00404  * is passed in.
00405  * If the 'v' (for "vector") is specified, then a vector of items of the
00406  * specified type is passed in, via a pointer to the first item
00407  * and an int32_t value for the length of the vector.
00408  * Length==-1 means zero or NUL termination.  Works for vectors of all types.
00409  *
00410  * Note:  %vS is a vector of (UChar *) strings.  The strings must
00411  *        be nul terminated as there is no way to provide a
00412  *        separate length parameter for each string.  The length
00413  *        parameter (required for all vectors) is the number of
00414  *        strings, not the length of the strings.
00415  *
00416  * Examples
00417  * --------
00418  *
00419  * These examples show the parameters that will be passed to an application's
00420  *   UTraceData() function for various formats.
00421  *
00422  * - the precise formatting is up to the application!
00423  * - the examples use type casts for arguments only to _show_ the types of
00424  *   arguments without needing variable declarations in the examples;
00425  *   the type casts will not be necessary in actual code
00426  *
00427  * UTraceDataFunc(context, fnNumber, level,
00428  *              "There is a character %c in the string %s.",   // Format String 
00429  *              (char)c, (const char *)s);                     // varargs parameters
00430  * ->   There is a character 0x42 'B' in the string "Bravo".
00431  *
00432  * UTraceDataFunc(context, fnNumber, level,
00433  *              "Vector of bytes %vb vector of chars %vc",
00434  *              (const uint8_t *)bytes, (int32_t)bytesLength,
00435  *              (const char *)chars, (int32_t)charsLength);
00436  * ->  Vector of bytes
00437  *      42 63 64 3f [4]
00438  *     vector of chars
00439  *      "Bcd?"[4]
00440  *
00441  * UTraceDataFunc(context, fnNumber, level,
00442  *              "An int32_t %d and a whole bunch of them %vd",
00443  *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
00444  * ->   An int32_t 0xfffffffb and a whole bunch of them
00445  *      fffffffb 00000005 0000010a [3]
00446  *
00447  */
00448 
00449 
00450 
00470 U_STABLE int32_t U_EXPORT2
00471 utrace_vformat(char *outBuf, int32_t capacity,
00472               int32_t indent, const char *fmt,  va_list args);
00473 
00491 U_STABLE int32_t U_EXPORT2
00492 utrace_format(char *outBuf, int32_t capacity,
00493               int32_t indent, const char *fmt,  ...);
00494 
00495 
00496 
00497 /* Trace function numbers --------------------------------------------------- */
00498 
00508 U_STABLE const char * U_EXPORT2
00509 utrace_functionName(int32_t fnNumber);
00510 
00511 U_CDECL_END
00512 
00513 #endif