1/*
2*******************************************************************************
3*
4*   Copyright (C) 2003-2013, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*
7*******************************************************************************
8*   file name:  utrace.h
9*   encoding:   US-ASCII
10*   tab size:   8 (not used)
11*   indentation:4
12*
13*   created on: 2003aug06
14*   created by: Markus W. Scherer
15*
16*   Definitions for ICU tracing/logging.
17*
18*/
19
20#ifndef __UTRACE_H__
21#define __UTRACE_H__
22
23#include <stdarg.h>
24#include "unicode/utypes.h"
25
26/**
27 * \file
28 * \brief C API:  Definitions for ICU tracing/logging.
29 *
30 * This provides API for debugging the internals of ICU without the use of
31 * a traditional debugger.
32 *
33 * By default, tracing is disabled in ICU. If you need to debug ICU with
34 * tracing, please compile ICU with the --enable-tracing configure option.
35 */
36
37U_CDECL_BEGIN
38
39/**
40 * Trace severity levels.  Higher levels increase the verbosity of the trace output.
41 * @see utrace_setLevel
42 * @stable ICU 2.8
43 */
44typedef enum UTraceLevel {
45    /** Disable all tracing  @stable ICU 2.8*/
46    UTRACE_OFF=-1,
47    /** Trace error conditions only  @stable ICU 2.8*/
48    UTRACE_ERROR=0,
49    /** Trace errors and warnings  @stable ICU 2.8*/
50    UTRACE_WARNING=3,
51    /** Trace opens and closes of ICU services  @stable ICU 2.8*/
52    UTRACE_OPEN_CLOSE=5,
53    /** Trace an intermediate number of ICU operations  @stable ICU 2.8*/
54    UTRACE_INFO=7,
55    /** Trace the maximum number of ICU operations  @stable ICU 2.8*/
56    UTRACE_VERBOSE=9
57} UTraceLevel;
58
59/**
60 *  These are the ICU functions that will be traced when tracing is enabled.
61 *  @stable ICU 2.8
62 */
63typedef enum UTraceFunctionNumber {
64    UTRACE_FUNCTION_START=0,
65    UTRACE_U_INIT=UTRACE_FUNCTION_START,
66    UTRACE_U_CLEANUP,
67    UTRACE_FUNCTION_LIMIT,
68
69    UTRACE_CONVERSION_START=0x1000,
70    UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START,
71    UTRACE_UCNV_OPEN_PACKAGE,
72    UTRACE_UCNV_OPEN_ALGORITHMIC,
73    UTRACE_UCNV_CLONE,
74    UTRACE_UCNV_CLOSE,
75    UTRACE_UCNV_FLUSH_CACHE,
76    UTRACE_UCNV_LOAD,
77    UTRACE_UCNV_UNLOAD,
78    UTRACE_CONVERSION_LIMIT,
79
80    UTRACE_COLLATION_START=0x2000,
81    UTRACE_UCOL_OPEN=UTRACE_COLLATION_START,
82    UTRACE_UCOL_CLOSE,
83    UTRACE_UCOL_STRCOLL,
84    UTRACE_UCOL_GET_SORTKEY,
85    UTRACE_UCOL_GETLOCALE,
86    UTRACE_UCOL_NEXTSORTKEYPART,
87    UTRACE_UCOL_STRCOLLITER,
88    UTRACE_UCOL_OPEN_FROM_SHORT_STRING,
89    UTRACE_UCOL_STRCOLLUTF8, /**< @stable ICU 50 */
90    UTRACE_COLLATION_LIMIT
91} UTraceFunctionNumber;
92
93/**
94 * Setter for the trace level.
95 * @param traceLevel A UTraceLevel value.
96 * @stable ICU 2.8
97 */
98U_STABLE void U_EXPORT2
99utrace_setLevel(int32_t traceLevel);
100
101/**
102 * Getter for the trace level.
103 * @return The UTraceLevel value being used by ICU.
104 * @stable ICU 2.8
105 */
106U_STABLE int32_t U_EXPORT2
107utrace_getLevel(void);
108
109/* Trace function pointers types  ----------------------------- */
110
111/**
112  *  Type signature for the trace function to be called when entering a function.
113  *  @param context value supplied at the time the trace functions are set.
114  *  @param fnNumber Enum value indicating the ICU function being entered.
115  *  @stable ICU 2.8
116  */
117typedef void U_CALLCONV
118UTraceEntry(const void *context, int32_t fnNumber);
119
120/**
121  *  Type signature for the trace function to be called when exiting from a function.
122  *  @param context value supplied at the time the trace functions are set.
123  *  @param fnNumber Enum value indicating the ICU function being exited.
124  *  @param fmt     A formatting string that describes the number and types
125  *                 of arguments included with the variable args.  The fmt
126  *                 string has the same form as the utrace_vformat format
127  *                 string.
128  *  @param args    A variable arguments list.  Contents are described by
129  *                 the fmt parameter.
130  *  @see   utrace_vformat
131  *  @stable ICU 2.8
132  */
133typedef void U_CALLCONV
134UTraceExit(const void *context, int32_t fnNumber,
135           const char *fmt, va_list args);
136
137/**
138  *  Type signature for the trace function to be called from within an ICU function
139  *  to display data or messages.
140  *  @param context  value supplied at the time the trace functions are set.
141  *  @param fnNumber Enum value indicating the ICU function being exited.
142  *  @param level    The current tracing level
143  *  @param fmt      A format string describing the tracing data that is supplied
144  *                  as variable args
145  *  @param args     The data being traced, passed as variable args.
146  *  @stable ICU 2.8
147  */
148typedef void U_CALLCONV
149UTraceData(const void *context, int32_t fnNumber, int32_t level,
150           const char *fmt, va_list args);
151
152/**
153  *  Set ICU Tracing functions.  Installs application-provided tracing
154  *  functions into ICU.  After doing this, subsequent ICU operations
155  *  will call back to the installed functions, providing a trace
156  *  of the use of ICU.  Passing a NULL pointer for a tracing function
157  *  is allowed, and inhibits tracing action at points where that function
158  *  would be called.
159  *  <p>
160  *  Tracing and Threads:  Tracing functions are global to a process, and
161  *  will be called in response to ICU operations performed by any
162  *  thread.  If tracing of an individual thread is desired, the
163  *  tracing functions must themselves filter by checking that the
164  *  current thread is the desired thread.
165  *
166  *  @param context an uninterpretted pointer.  Whatever is passed in
167  *                 here will in turn be passed to each of the tracing
168  *                 functions UTraceEntry, UTraceExit and UTraceData.
169  *                 ICU does not use or alter this pointer.
170  *  @param e       Callback function to be called on entry to a
171  *                 a traced ICU function.
172  *  @param x       Callback function to be called on exit from a
173  *                 traced ICU function.
174  *  @param d       Callback function to be called from within a
175  *                 traced ICU function, for the purpose of providing
176  *                 data to the trace.
177  *
178  *  @stable ICU 2.8
179  */
180U_STABLE void U_EXPORT2
181utrace_setFunctions(const void *context,
182                    UTraceEntry *e, UTraceExit *x, UTraceData *d);
183
184/**
185  * Get the currently installed ICU tracing functions.   Note that a null function
186  *   pointer will be returned if no trace function has been set.
187  *
188  * @param context  The currently installed tracing context.
189  * @param e        The currently installed UTraceEntry function.
190  * @param x        The currently installed UTraceExit function.
191  * @param d        The currently installed UTraceData function.
192  * @stable ICU 2.8
193  */
194U_STABLE void U_EXPORT2
195utrace_getFunctions(const void **context,
196                    UTraceEntry **e, UTraceExit **x, UTraceData **d);
197
198
199
200/*
201 *
202 * ICU trace format string syntax
203 *
204 * Format Strings are passed to UTraceData functions, and define the
205 * number and types of the trace data being passed on each call.
206 *
207 * The UTraceData function, which is supplied by the application,
208 * not by ICU, can either forward the trace data (passed via
209 * varargs) and the format string back to ICU for formatting into
210 * a displayable string, or it can interpret the format itself,
211 * and do as it wishes with the trace data.
212 *
213 *
214 * Goals for the format string
215 * - basic data output
216 * - easy to use for trace programmer
217 * - sufficient provision for data types for trace output readability
218 * - well-defined types and binary portable APIs
219 *
220 * Non-goals
221 * - printf compatibility
222 * - fancy formatting
223 * - argument reordering and other internationalization features
224 *
225 * ICU trace format strings contain plain text with argument inserts,
226 * much like standard printf format strings.
227 * Each insert begins with a '%', then optionally contains a 'v',
228 * then exactly one type character.
229 * Two '%' in a row represent a '%' instead of an insert.
230 * The trace format strings need not have \n at the end.
231 *
232 *
233 * Types
234 * -----
235 *
236 * Type characters:
237 * - c A char character in the default codepage.
238 * - s A NUL-terminated char * string in the default codepage.
239 * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
240 * - b A byte (8-bit integer).
241 * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
242 * - d A 32-bit integer.  Also a 20 bit Unicode code point value.
243 * - l A 64-bit integer.
244 * - p A data pointer.
245 *
246 * Vectors
247 * -------
248 *
249 * If the 'v' is not specified, then one item of the specified type
250 * is passed in.
251 * If the 'v' (for "vector") is specified, then a vector of items of the
252 * specified type is passed in, via a pointer to the first item
253 * and an int32_t value for the length of the vector.
254 * Length==-1 means zero or NUL termination.  Works for vectors of all types.
255 *
256 * Note:  %vS is a vector of (UChar *) strings.  The strings must
257 *        be nul terminated as there is no way to provide a
258 *        separate length parameter for each string.  The length
259 *        parameter (required for all vectors) is the number of
260 *        strings, not the length of the strings.
261 *
262 * Examples
263 * --------
264 *
265 * These examples show the parameters that will be passed to an application's
266 *   UTraceData() function for various formats.
267 *
268 * - the precise formatting is up to the application!
269 * - the examples use type casts for arguments only to _show_ the types of
270 *   arguments without needing variable declarations in the examples;
271 *   the type casts will not be necessary in actual code
272 *
273 * UTraceDataFunc(context, fnNumber, level,
274 *              "There is a character %c in the string %s.",   // Format String
275 *              (char)c, (const char *)s);                     // varargs parameters
276 * ->   There is a character 0x42 'B' in the string "Bravo".
277 *
278 * UTraceDataFunc(context, fnNumber, level,
279 *              "Vector of bytes %vb vector of chars %vc",
280 *              (const uint8_t *)bytes, (int32_t)bytesLength,
281 *              (const char *)chars, (int32_t)charsLength);
282 * ->  Vector of bytes
283 *      42 63 64 3f [4]
284 *     vector of chars
285 *      "Bcd?"[4]
286 *
287 * UTraceDataFunc(context, fnNumber, level,
288 *              "An int32_t %d and a whole bunch of them %vd",
289 *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
290 * ->   An int32_t 0xfffffffb and a whole bunch of them
291 *      fffffffb 00000005 0000010a [3]
292 *
293 */
294
295
296
297/**
298  *  Trace output Formatter.  An application's UTraceData tracing functions may call
299  *                 back to this function to format the trace output in a
300  *                 human readable form.  Note that a UTraceData function may choose
301  *                 to not format the data;  it could, for example, save it in
302  *                 in the raw form it was received (more compact), leaving
303  *                 formatting for a later trace analyis tool.
304  *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
305  *                 will be nul terminated if there is space in the buffer -
306  *                 if the length of the requested output < the output buffer size.
307  *  @param capacity  Length of the output buffer.
308  *  @param indent  Number of spaces to indent the output.  Intended to allow
309  *                 data displayed from nested functions to be indented for readability.
310  *  @param fmt     Format specification for the data to output
311  *  @param args    Data to be formatted.
312  *  @return        Length of formatted output, including the terminating NUL.
313  *                 If buffer capacity is insufficient, the required capacity is returned.
314  *  @stable ICU 2.8
315  */
316U_STABLE int32_t U_EXPORT2
317utrace_vformat(char *outBuf, int32_t capacity,
318              int32_t indent, const char *fmt,  va_list args);
319
320/**
321  *  Trace output Formatter.  An application's UTraceData tracing functions may call
322  *                 this function to format any additional trace data, beyond that
323  *                 provided by default, in human readable form with the same
324  *                 formatting conventions used by utrace_vformat().
325  *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
326  *                 will be nul terminated if there is space in the buffer -
327  *                 if the length of the requested output < the output buffer size.
328  *  @param capacity  Length of the output buffer.
329  *  @param indent  Number of spaces to indent the output.  Intended to allow
330  *                 data displayed from nested functions to be indented for readability.
331  *  @param fmt     Format specification for the data to output
332  *  @param ...     Data to be formatted.
333  *  @return        Length of formatted output, including the terminating NUL.
334  *                 If buffer capacity is insufficient, the required capacity is returned.
335  *  @stable ICU 2.8
336  */
337U_STABLE int32_t U_EXPORT2
338utrace_format(char *outBuf, int32_t capacity,
339              int32_t indent, const char *fmt,  ...);
340
341
342
343/* Trace function numbers --------------------------------------------------- */
344
345/**
346 * Get the name of a function from its trace function number.
347 *
348 * @param fnNumber The trace number for an ICU function.
349 * @return The name string for the function.
350 *
351 * @see UTraceFunctionNumber
352 * @stable ICU 2.8
353 */
354U_STABLE const char * U_EXPORT2
355utrace_functionName(int32_t fnNumber);
356
357U_CDECL_END
358
359#endif
360