Move ICU headers part 1

public/common/unicode/utrace.h

-/*
-*******************************************************************************
-*
-*   Copyright (C) 2003-2006, International Business Machines
-*   Corporation and others.  All Rights Reserved.
-*
-*******************************************************************************
-*   file name:  utrace.h
-*   encoding:   US-ASCII
-*   tab size:   8 (not used)
-*   indentation:4
-*
-*   created on: 2003aug06
-*   created by: Markus W. Scherer
-*
-*   Definitions for ICU tracing/logging.
-*
-*/
-
-#ifndef __UTRACE_H__
-#define __UTRACE_H__
-
-#include <stdarg.h>
-#include "unicode/utypes.h"
-
-/**
- * \file
- * \brief C API:  Definitions for ICU tracing/logging. 
- *
- * This provides API for debugging the internals of ICU without the use of
- * a traditional debugger.
- *
- * By default, tracing is disabled in ICU. If you need to debug ICU with 
- * tracing, please compile ICU with the --enable-tracing configure option.
- */
- 
-U_CDECL_BEGIN
-
-/**
- * Trace severity levels.  Higher levels increase the verbosity of the trace output.
- * @see utrace_setLevel
- * @stable ICU 2.8
- */
-typedef enum UTraceLevel {
-    /** Disable all tracing  @stable ICU 2.8*/
-    UTRACE_OFF=-1,
-    /** Trace error conditions only  @stable ICU 2.8*/
-    UTRACE_ERROR=0,
-    /** Trace errors and warnings  @stable ICU 2.8*/
-    UTRACE_WARNING=3,
-    /** Trace opens and closes of ICU services  @stable ICU 2.8*/
-    UTRACE_OPEN_CLOSE=5,
-    /** Trace an intermediate number of ICU operations  @stable ICU 2.8*/
-    UTRACE_INFO=7,
-    /** Trace the maximum number of ICU operations  @stable ICU 2.8*/
-    UTRACE_VERBOSE=9
-} UTraceLevel;
-
-/**
- *  These are the ICU functions that will be traced when tracing is enabled.
- *  @stable ICU 2.8
- */
-typedef enum UTraceFunctionNumber {
-    UTRACE_FUNCTION_START=0,
-    UTRACE_U_INIT=UTRACE_FUNCTION_START,
-    UTRACE_U_CLEANUP,
-    UTRACE_FUNCTION_LIMIT,
-
-    UTRACE_CONVERSION_START=0x1000,
-    UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START,
-    UTRACE_UCNV_OPEN_PACKAGE,
-    UTRACE_UCNV_OPEN_ALGORITHMIC,
-    UTRACE_UCNV_CLONE,
-    UTRACE_UCNV_CLOSE,
-    UTRACE_UCNV_FLUSH_CACHE,
-    UTRACE_UCNV_LOAD,
-    UTRACE_UCNV_UNLOAD,
-    UTRACE_CONVERSION_LIMIT,
-
-    UTRACE_COLLATION_START=0x2000,
-    UTRACE_UCOL_OPEN=UTRACE_COLLATION_START,
-    UTRACE_UCOL_CLOSE,
-    UTRACE_UCOL_STRCOLL,
-    UTRACE_UCOL_GET_SORTKEY,
-    UTRACE_UCOL_GETLOCALE,
-    UTRACE_UCOL_NEXTSORTKEYPART,
-    UTRACE_UCOL_STRCOLLITER,
-    UTRACE_UCOL_OPEN_FROM_SHORT_STRING,
-    UTRACE_COLLATION_LIMIT
-} UTraceFunctionNumber;
-
-/**
- * Setter for the trace level.
- * @param traceLevel A UTraceLevel value.
- * @stable ICU 2.8
- */
-U_STABLE void U_EXPORT2
-utrace_setLevel(int32_t traceLevel);
-
-/**
- * Getter for the trace level.
- * @return The UTraceLevel value being used by ICU.
- * @stable ICU 2.8
- */
-U_STABLE int32_t U_EXPORT2
-utrace_getLevel(void);
-
-/* Trace function pointers types  ----------------------------- */
-
-/**
-  *  Type signature for the trace function to be called when entering a function.
-  *  @param context value supplied at the time the trace functions are set.
-  *  @param fnNumber Enum value indicating the ICU function being entered.
-  *  @stable ICU 2.8
-  */
-typedef void U_CALLCONV
-UTraceEntry(const void *context, int32_t fnNumber);
-
-/**
-  *  Type signature for the trace function to be called when exiting from a function.
-  *  @param context value supplied at the time the trace functions are set.
-  *  @param fnNumber Enum value indicating the ICU function being exited.
-  *  @param fmt     A formatting string that describes the number and types
-  *                 of arguments included with the variable args.  The fmt
-  *                 string has the same form as the utrace_vformat format
-  *                 string.
-  *  @param args    A variable arguments list.  Contents are described by
-  *                 the fmt parameter.
-  *  @see   utrace_vformat
-  *  @stable ICU 2.8
-  */
-typedef void U_CALLCONV
-UTraceExit(const void *context, int32_t fnNumber, 
-           const char *fmt, va_list args);
-
-/**
-  *  Type signature for the trace function to be called from within an ICU function
-  *  to display data or messages.
-  *  @param context  value supplied at the time the trace functions are set.
-  *  @param fnNumber Enum value indicating the ICU function being exited.
-  *  @param level    The current tracing level
-  *  @param fmt      A format string describing the tracing data that is supplied
-  *                  as variable args
-  *  @param args     The data being traced, passed as variable args.
-  *  @stable ICU 2.8
-  */
-typedef void U_CALLCONV
-UTraceData(const void *context, int32_t fnNumber, int32_t level,
-           const char *fmt, va_list args);
-
-/**
-  *  Set ICU Tracing functions.  Installs application-provided tracing
-  *  functions into ICU.  After doing this, subsequent ICU operations
-  *  will call back to the installed functions, providing a trace
-  *  of the use of ICU.  Passing a NULL pointer for a tracing function
-  *  is allowed, and inhibits tracing action at points where that function
-  *  would be called.
-  *  <p>
-  *  Tracing and Threads:  Tracing functions are global to a process, and
-  *  will be called in response to ICU operations performed by any
-  *  thread.  If tracing of an individual thread is desired, the
-  *  tracing functions must themselves filter by checking that the
-  *  current thread is the desired thread.
-  *
-  *  @param context an uninterpretted pointer.  Whatever is passed in
-  *                 here will in turn be passed to each of the tracing
-  *                 functions UTraceEntry, UTraceExit and UTraceData.
-  *                 ICU does not use or alter this pointer.
-  *  @param e       Callback function to be called on entry to a 
-  *                 a traced ICU function.
-  *  @param x       Callback function to be called on exit from a
-  *                 traced ICU function.
-  *  @param d       Callback function to be called from within a 
-  *                 traced ICU function, for the purpose of providing
-  *                 data to the trace.
-  *
-  *  @stable ICU 2.8
-  */
-U_STABLE void U_EXPORT2
-utrace_setFunctions(const void *context,
-                    UTraceEntry *e, UTraceExit *x, UTraceData *d);
-
-/**
-  * Get the currently installed ICU tracing functions.   Note that a null function
-  *   pointer will be returned if no trace function has been set.
-  *
-  * @param context  The currently installed tracing context.
-  * @param e        The currently installed UTraceEntry function.
-  * @param x        The currently installed UTraceExit function.
-  * @param d        The currently installed UTraceData function.
-  * @stable ICU 2.8
-  */
-U_STABLE void U_EXPORT2
-utrace_getFunctions(const void **context,
-                    UTraceEntry **e, UTraceExit **x, UTraceData **d);
-
-
-
-/*
- *
- * ICU trace format string syntax
- *
- * Format Strings are passed to UTraceData functions, and define the
- * number and types of the trace data being passed on each call.
- *
- * The UTraceData function, which is supplied by the application,
- * not by ICU, can either forward the trace data (passed via
- * varargs) and the format string back to ICU for formatting into
- * a displayable string, or it can interpret the format itself,
- * and do as it wishes with the trace data.
- *
- *
- * Goals for the format string
- * - basic data output
- * - easy to use for trace programmer
- * - sufficient provision for data types for trace output readability
- * - well-defined types and binary portable APIs
- *
- * Non-goals
- * - printf compatibility
- * - fancy formatting
- * - argument reordering and other internationalization features
- *
- * ICU trace format strings contain plain text with argument inserts,
- * much like standard printf format strings.
- * Each insert begins with a '%', then optionally contains a 'v',
- * then exactly one type character.
- * Two '%' in a row represent a '%' instead of an insert.
- * The trace format strings need not have \n at the end.
- *
- *
- * Types
- * -----
- *
- * Type characters:
- * - c A char character in the default codepage.
- * - s A NUL-terminated char * string in the default codepage.
- * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
- * - b A byte (8-bit integer).
- * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
- * - d A 32-bit integer.  Also a 20 bit Unicode code point value. 
- * - l A 64-bit integer.
- * - p A data pointer.
- *
- * Vectors
- * -------
- *
- * If the 'v' is not specified, then one item of the specified type
- * is passed in.
- * If the 'v' (for "vector") is specified, then a vector of items of the
- * specified type is passed in, via a pointer to the first item
- * and an int32_t value for the length of the vector.
- * Length==-1 means zero or NUL termination.  Works for vectors of all types.
- *
- * Note:  %vS is a vector of (UChar *) strings.  The strings must
- *        be nul terminated as there is no way to provide a
- *        separate length parameter for each string.  The length
- *        parameter (required for all vectors) is the number of
- *        strings, not the length of the strings.
- *
- * Examples
- * --------
- *
- * These examples show the parameters that will be passed to an application's
- *   UTraceData() function for various formats.
- *
- * - the precise formatting is up to the application!
- * - the examples use type casts for arguments only to _show_ the types of
- *   arguments without needing variable declarations in the examples;
- *   the type casts will not be necessary in actual code
- *
- * UTraceDataFunc(context, fnNumber, level,
- *              "There is a character %c in the string %s.",   // Format String 
- *              (char)c, (const char *)s);                     // varargs parameters
- * ->   There is a character 0x42 'B' in the string "Bravo".
- *
- * UTraceDataFunc(context, fnNumber, level,
- *              "Vector of bytes %vb vector of chars %vc",
- *              (const uint8_t *)bytes, (int32_t)bytesLength,
- *              (const char *)chars, (int32_t)charsLength);
- * ->  Vector of bytes
- *      42 63 64 3f [4]
- *     vector of chars
- *      "Bcd?"[4]
- *
- * UTraceDataFunc(context, fnNumber, level,
- *              "An int32_t %d and a whole bunch of them %vd",
- *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
- * ->   An int32_t 0xfffffffb and a whole bunch of them
- *      fffffffb 00000005 0000010a [3]
- *
- */
-
-
-
-/**
-  *  Trace output Formatter.  An application's UTraceData tracing functions may call
-  *                 back to this function to format the trace output in a
-  *                 human readable form.  Note that a UTraceData function may choose
-  *                 to not format the data;  it could, for example, save it in
-  *                 in the raw form it was received (more compact), leaving
-  *                 formatting for a later trace analyis tool.
-  *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
-  *                 will be nul terminated if there is space in the buffer -
-  *                 if the length of the requested output < the output buffer size.
-  *  @param capacity  Length of the output buffer.
-  *  @param indent  Number of spaces to indent the output.  Intended to allow
-  *                 data displayed from nested functions to be indented for readability.
-  *  @param fmt     Format specification for the data to output
-  *  @param args    Data to be formatted.
-  *  @return        Length of formatted output, including the terminating NUL.
-  *                 If buffer capacity is insufficient, the required capacity is returned. 
-  *  @stable ICU 2.8
-  */
-U_STABLE int32_t U_EXPORT2
-utrace_vformat(char *outBuf, int32_t capacity,
-              int32_t indent, const char *fmt,  va_list args);
-
-/**
-  *  Trace output Formatter.  An application's UTraceData tracing functions may call
-  *                 this function to format any additional trace data, beyond that
-  *                 provided by default, in human readable form with the same
-  *                 formatting conventions used by utrace_vformat().
-  *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
-  *                 will be nul terminated if there is space in the buffer -
-  *                 if the length of the requested output < the output buffer size.
-  *  @param capacity  Length of the output buffer.
-  *  @param indent  Number of spaces to indent the output.  Intended to allow
-  *                 data displayed from nested functions to be indented for readability.
-  *  @param fmt     Format specification for the data to output
-  *  @param ...     Data to be formatted.
-  *  @return        Length of formatted output, including the terminating NUL.
-  *                 If buffer capacity is insufficient, the required capacity is returned. 
-  *  @stable ICU 2.8
-  */
-U_STABLE int32_t U_EXPORT2
-utrace_format(char *outBuf, int32_t capacity,
-              int32_t indent, const char *fmt,  ...);
-
-
-
-/* Trace function numbers --------------------------------------------------- */
-
-/**
- * Get the name of a function from its trace function number.
- *
- * @param fnNumber The trace number for an ICU function.
- * @return The name string for the function.
- *
- * @see UTraceFunctionNumber
- * @stable ICU 2.8
- */
-U_STABLE const char * U_EXPORT2
-utrace_functionName(int32_t fnNumber);
-
-U_CDECL_END
-
-#endif