- Main Page
- Modules
- Data Structures
- Files
- Related Pages

- Search for |

- File List
- Globals

# utrace.h

Go to the documentation of this file.

    00001 /*
    00002 *******************************************************************************
    00003 *
    00004 *   Copyright (C) 2003-2006, 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
    00037 U_CDECL_BEGIN
    00038
    00044 typedef enum UTraceLevel {
    00046     UTRACE_OFF=-1,
    00048     UTRACE_ERROR=0,
    00050     UTRACE_WARNING=3,
    00052     UTRACE_OPEN_CLOSE=5,
    00054     UTRACE_INFO=7,
    00056     UTRACE_VERBOSE=9
    00057 } UTraceLevel;
    00058
    00063 typedef enum UTraceFunctionNumber {
    00064     UTRACE_FUNCTION_START=0,
    00065     UTRACE_U_INIT=UTRACE_FUNCTION_START,
    00066     UTRACE_U_CLEANUP,
    00067     UTRACE_FUNCTION_LIMIT,
    00068
    00069     UTRACE_CONVERSION_START=0x1000,
    00070     UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START,
    00071     UTRACE_UCNV_OPEN_PACKAGE,
    00072     UTRACE_UCNV_OPEN_ALGORITHMIC,
    00073     UTRACE_UCNV_CLONE,
    00074     UTRACE_UCNV_CLOSE,
    00075     UTRACE_UCNV_FLUSH_CACHE,
    00076     UTRACE_UCNV_LOAD,
    00077     UTRACE_UCNV_UNLOAD,
    00078     UTRACE_CONVERSION_LIMIT,
    00079
    00080     UTRACE_COLLATION_START=0x2000,
    00081     UTRACE_UCOL_OPEN=UTRACE_COLLATION_START,
    00082     UTRACE_UCOL_CLOSE,
    00083     UTRACE_UCOL_STRCOLL,
    00084     UTRACE_UCOL_GET_SORTKEY,
    00085     UTRACE_UCOL_GETLOCALE,
    00086     UTRACE_UCOL_NEXTSORTKEYPART,
    00087     UTRACE_UCOL_STRCOLLITER,
    00088     UTRACE_UCOL_OPEN_FROM_SHORT_STRING,
    00089     UTRACE_COLLATION_LIMIT
    00090 } UTraceFunctionNumber;
    00091
    00097 U_STABLE void U_EXPORT2
    00098 utrace_setLevel(int32_t traceLevel);
    00099
    00105 U_STABLE int32_t U_EXPORT2
    00106 utrace_getLevel(void);
    00107
    00108 /* Trace function pointers types  ----------------------------- */
    00109
    00116 typedef void U_CALLCONV
    00117 UTraceEntry(const void *context, int32_t fnNumber);
    00118
    00132 typedef void U_CALLCONV
    00133 UTraceExit(const void *context, int32_t fnNumber,
    00134            const char *fmt, va_list args);
    00135
    00147 typedef void U_CALLCONV
    00148 UTraceData(const void *context, int32_t fnNumber, int32_t level,
    00149            const char *fmt, va_list args);
    00150
    00179 U_STABLE void U_EXPORT2
    00180 utrace_setFunctions(const void *context,
    00181                     UTraceEntry *e, UTraceExit *x, UTraceData *d);
    00182
    00193 U_STABLE void U_EXPORT2
    00194 utrace_getFunctions(const void **context,
    00195                     UTraceEntry **e, UTraceExit **x, UTraceData **d);
    00196
    00197
    00198
    00199 /*
    00200  *
    00201  * ICU trace format string syntax
    00202  *
    00203  * Format Strings are passed to UTraceData functions, and define the
    00204  * number and types of the trace data being passed on each call.
    00205  *
    00206  * The UTraceData function, which is supplied by the application,
    00207  * not by ICU, can either forward the trace data (passed via
    00208  * varargs) and the format string back to ICU for formatting into
    00209  * a displayable string, or it can interpret the format itself,
    00210  * and do as it wishes with the trace data.
    00211  *
    00212  *
    00213  * Goals for the format string
    00214  * - basic data output
    00215  * - easy to use for trace programmer
    00216  * - sufficient provision for data types for trace output readability
    00217  * - well-defined types and binary portable APIs
    00218  *
    00219  * Non-goals
    00220  * - printf compatibility
    00221  * - fancy formatting
    00222  * - argument reordering and other internationalization features
    00223  *
    00224  * ICU trace format strings contain plain text with argument inserts,
    00225  * much like standard printf format strings.
    00226  * Each insert begins with a '%', then optionally contains a 'v',
    00227  * then exactly one type character.
    00228  * Two '%' in a row represent a '%' instead of an insert.
    00229  * The trace format strings need not have \n at the end.
    00230  *
    00231  *
    00232  * Types
    00233  * -----
    00234  *
    00235  * Type characters:
    00236  * - c A char character in the default codepage.
    00237  * - s A NUL-terminated char * string in the default codepage.
    00238  * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
    00239  * - b A byte (8-bit integer).
    00240  * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
    00241  * - d A 32-bit integer.  Also a 20 bit Unicode code point value.
    00242  * - l A 64-bit integer.
    00243  * - p A data pointer.
    00244  *
    00245  * Vectors
    00246  * -------
    00247  *
    00248  * If the 'v' is not specified, then one item of the specified type
    00249  * is passed in.
    00250  * If the 'v' (for "vector") is specified, then a vector of items of the
    00251  * specified type is passed in, via a pointer to the first item
    00252  * and an int32_t value for the length of the vector.
    00253  * Length==-1 means zero or NUL termination.  Works for vectors of all types.
    00254  *
    00255  * Note:  %vS is a vector of (UChar *) strings.  The strings must
    00256  *        be nul terminated as there is no way to provide a
    00257  *        separate length parameter for each string.  The length
    00258  *        parameter (required for all vectors) is the number of
    00259  *        strings, not the length of the strings.
    00260  *
    00261  * Examples
    00262  * --------
    00263  *
    00264  * These examples show the parameters that will be passed to an application's
    00265  *   UTraceData() function for various formats.
    00266  *
    00267  * - the precise formatting is up to the application!
    00268  * - the examples use type casts for arguments only to _show_ the types of
    00269  *   arguments without needing variable declarations in the examples;
    00270  *   the type casts will not be necessary in actual code
    00271  *
    00272  * UTraceDataFunc(context, fnNumber, level,
    00273  *              "There is a character %c in the string %s.",   // Format String
    00274  *              (char)c, (const char *)s);                     // varargs parameters
    00275  * ->   There is a character 0x42 'B' in the string "Bravo".
    00276  *
    00277  * UTraceDataFunc(context, fnNumber, level,
    00278  *              "Vector of bytes %vb vector of chars %vc",
    00279  *              (const uint8_t *)bytes, (int32_t)bytesLength,
    00280  *              (const char *)chars, (int32_t)charsLength);
    00281  * ->  Vector of bytes
    00282  *      42 63 64 3f [4]
    00283  *     vector of chars
    00284  *      "Bcd?"[4]
    00285  *
    00286  * UTraceDataFunc(context, fnNumber, level,
    00287  *              "An int32_t %d and a whole bunch of them %vd",
    00288  *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
    00289  * ->   An int32_t 0xfffffffb and a whole bunch of them
    00290  *      fffffffb 00000005 0000010a [3]
    00291  *
    00292  */
    00293
    00294
    00295
    00315 U_STABLE int32_t U_EXPORT2
    00316 utrace_vformat(char *outBuf, int32_t capacity,
    00317               int32_t indent, const char *fmt,  va_list args);
    00318
    00336 U_STABLE int32_t U_EXPORT2
    00337 utrace_format(char *outBuf, int32_t capacity,
    00338               int32_t indent, const char *fmt,  ...);
    00339
    00340
    00341
    00342 /* Trace function numbers --------------------------------------------------- */
    00343
    00353 U_STABLE const char * U_EXPORT2
    00354 utrace_functionName(int32_t fnNumber);
    00355
    00356 U_CDECL_END
    00357
    00358 #endif