Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

utrace.h File Reference

#include <stdarg.h>
#include "unicode/utypes.h"

Go to the source code of this file.

Typedefs

typedef enum UTraceLevel UTraceLevel
 Trace severity levels. More...

typedef void U_CALLCONV UTraceEntry (const void *context, int32_t fnNumber)
 Type signature for the trace function to be called when entering a function. More...

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 when exiting from a function. More...

typedef void U_CALLCONV UTraceData (const void *context, int32_t fnNumber, int32_t level, 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. More...

typedef enum UTraceFunctionNumber UTraceFunctionNumber
 These are the ICU functions that will be traced when tracing is enabled. More...


Enumerations

enum  UTraceLevel {
  UTRACE_OFF = -1, UTRACE_ERROR = 0, UTRACE_WARNING = 3, UTRACE_OPEN_CLOSE = 5,
  UTRACE_INFO = 7, UTRACE_VERBOSE = 9
}
 Trace severity levels. More...

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_CLOSE, UTRACE_UCNV_FLUSH_CACHE,
  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_COLLATION_LIMIT
}
 These are the ICU functions that will be traced when tracing is enabled. More...


Functions

void utrace_setLevel (int32_t traceLevel)
 Setter for the trace level. More...

int32_t utrace_getLevel ()
 Getter for the trace level. More...

void utrace_setFunctions (const void *context, UTraceEntry *e, UTraceExit *x, UTraceData *d)
 Set ICU Tracing functions. More...

void utrace_getFunctions (const void **context, UTraceEntry **e, UTraceExit **x, UTraceData **d)
 Get the currently installed ICU tracing functions. More...

int32_t utrace_vformat (char *outBuf, int32_t capacity, int32_t indent, const char *fmt, va_list args)
 Trace output Formatter. More...

int32_t utrace_format (char *outBuf, int32_t capacity, int32_t indent, const char *fmt,...)
 Trace output Formatter. More...

const char * utrace_functionName (int32_t fnNumber)
 Get the name of a function from its trace function number. More...


Typedef Documentation

typedef void U_CALLCONV UTraceData(const void *context, int32_t fnNumber, int32_t level, 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.

Parameters:
context  value supplied at the time the trace functions are set.
fnNumber  Enum value indicating the ICU function being exited.
level  The current tracing level
fmt  A format string describing the tracing data that is supplied as variable args
args  The data being traced, passed as variable args.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

Definition at line 106 of file utrace.h.

typedef void U_CALLCONV UTraceEntry(const void *context, int32_t fnNumber)
 

Type signature for the trace function to be called when entering a function.

Parameters:
context  value supplied at the time the trace functions are set.
fnNumber  Enum value indicating the ICU function being entered.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

Definition at line 75 of file utrace.h.

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 when exiting from a function.

Parameters:
context  value supplied at the time the trace functions are set.
fnNumber  Enum value indicating the ICU function being exited.
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.
args  A variable arguments list. Contents are described by the fmt parameter.
See also:
utrace_vformat
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

Definition at line 91 of file utrace.h.

typedef enum UTraceFunctionNumber UTraceFunctionNumber
 

These are the ICU functions that will be traced when tracing is enabled.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

typedef enum UTraceLevel UTraceLevel
 

Trace severity levels.

Higher levels increase the verbosity of the trace output.

See also:
utrace_setLevel
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.


Enumeration Type Documentation

enum UTraceFunctionNumber
 

These are the ICU functions that will be traced when tracing is enabled.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
Enumeration values:
UTRACE_FUNCTION_START 
UTRACE_U_INIT 
UTRACE_U_CLEANUP 
UTRACE_FUNCTION_LIMIT 
UTRACE_CONVERSION_START 
UTRACE_UCNV_OPEN 
UTRACE_UCNV_CLOSE 
UTRACE_UCNV_FLUSH_CACHE 
UTRACE_CONVERSION_LIMIT 
UTRACE_COLLATION_START 
UTRACE_UCOL_OPEN 
UTRACE_UCOL_CLOSE 
UTRACE_UCOL_STRCOLL 
UTRACE_UCOL_GET_SORTKEY 
UTRACE_UCOL_GETLOCALE 
UTRACE_UCOL_NEXTSORTKEYPART 
UTRACE_UCOL_STRCOLLITER 
UTRACE_COLLATION_LIMIT 

Definition at line 318 of file utrace.h.

enum UTraceLevel
 

Trace severity levels.

Higher levels increase the verbosity of the trace output.

See also:
utrace_setLevel
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
Enumeration values:
UTRACE_OFF  Disable all tracing.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
UTRACE_ERROR  Trace error conditions only.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
UTRACE_WARNING  Trace errors and warnings.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
UTRACE_OPEN_CLOSE  Trace opens and closes of ICU services.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
UTRACE_INFO  Trace an intermediate number of ICU operations.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.
UTRACE_VERBOSE  Trace the maximum number of ICU operations.

Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

Definition at line 34 of file utrace.h.


Function Documentation

int32_t utrace_format char *    outBuf,
int32_t    capacity,
int32_t    indent,
const char *    fmt,
...   
 

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().

Parameters:
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.
capacity  Length of the output buffer.
indent  Number of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmt  Format specification for the data to output
...  Data to be formatted.
Returns:
Length of formatted output, including the terminating NUL. If buffer capacity is insufficient, the required capacity is returned.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

const char* utrace_functionName int32_t    fnNumber
 

Get the name of a function from its trace function number.

Parameters:
fnNumber  The trace number for an ICU function.
Returns:
The name string for the function.
See also:
UTraceFunctionNumber
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

void utrace_getFunctions 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.

Parameters:
context  The currently installed tracing context.
e  The currently installed UTraceEntry function.
x  The currently installed UTraceExit function.
d  The currently installed UTraceData function.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

int32_t utrace_getLevel  
 

Getter for the trace level.

Parameters:
traceLevel  A UTraceLevel value.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

void utrace_setFunctions const void *    context,
UTraceEntry   e,
UTraceExit   x,
UTraceData   d
 

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.

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.

Parameters:
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.
e  Callback function to be called on entry to a a traced ICU function.
x  Callback function to be called on exit from a traced ICU function.
d  Callback function to be called from within a traced ICU function, for the purpose of providing data to the trace.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

void utrace_setLevel int32_t    traceLevel
 

Setter for the trace level.

Parameters:
traceLevel  A UTraceLevel value.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

int32_t 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 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.

Parameters:
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.
capacity  Length of the output buffer.
indent  Number of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmt  Format specification for the data to output
args  Data to be formatted.
Returns:
Length of formatted output, including the terminating NUL. If buffer capacity is insufficient, the required capacity is returned.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.


Generated on Mon Nov 24 14:36:12 2003 for ICU 2.8 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001