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

utrace.h

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

Generated on Tue Jul 26 00:40:03 2005 for ICU 3.2 by  doxygen 1.3.9.1