ICU 56.1: utrace.h Source File

ICU 56.1 56.1

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

- File List
- Globals

utrace.h
Go to the documentation of this file.
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
37 U_CDECL_BEGIN
38
44 typedef enum UTraceLevel {
46 UTRACE_OFF=-1,
48 UTRACE_ERROR=0,
50 UTRACE_WARNING=3,
52 UTRACE_OPEN_CLOSE=5,
54 UTRACE_INFO=7,
56 UTRACE_VERBOSE=9
57 } UTraceLevel;
58
63 typedef 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,
90 UTRACE_COLLATION_LIMIT
91 } UTraceFunctionNumber;
92
98 U_STABLE void U_EXPORT2
99 utrace_setLevel(int32_t traceLevel);
100
106 U_STABLE int32_t U_EXPORT2
107 utrace_getLevel(void);
108
109 /* Trace function pointers types ----------------------------- */
110
117 typedef void U_CALLCONV
118 UTraceEntry(const void *context, int32_t fnNumber);
119
133 typedef void U_CALLCONV
134 UTraceExit(const void *context, int32_t fnNumber,
135 const char *fmt, va_list args);
136
148 typedef void U_CALLCONV
149 UTraceData(const void *context, int32_t fnNumber, int32_t level,
150 const char *fmt, va_list args);
151
180 U_STABLE void U_EXPORT2
181 utrace_setFunctions(const void *context,
182 UTraceEntry *e, UTraceExit *x, UTraceData *d);
183
194 U_STABLE void U_EXPORT2
195 utrace_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
316 U_STABLE int32_t U_EXPORT2
317 utrace_vformat(char *outBuf, int32_t capacity,
318 int32_t indent, const char *fmt, va_list args);
319
337 U_STABLE int32_t U_EXPORT2
338 utrace_format(char *outBuf, int32_t capacity,
339 int32_t indent, const char *fmt, ...);
340
341
342
343 /* Trace function numbers --------------------------------------------------- */
344
354 U_STABLE const char * U_EXPORT2
355 utrace_functionName(int32_t fnNumber);
356
357 U_CDECL_END
358
359 #endif
UTraceLevel
UTraceLevel
Trace severity levels.
Definition: utrace.h:44
UTRACE_UCOL_STRCOLLUTF8
Definition: utrace.h:89
UTRACE_VERBOSE
Trace the maximum number of ICU operations.
Definition: utrace.h:56
UTraceEntry
void UTraceEntry(const void *context, int32_t fnNumber)
Type signature for the trace function to be called when entering a function.
Definition: utrace.h:118
U_CALLCONV
#define U_CALLCONV
Similar to U_CDECL_BEGIN/U_CDECL_END, this qualifier is necessary in callback function typedefs to ma...
Definition: platform.h:823
UTraceExit
void 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.
Definition: utrace.h:134
utrace_getLevel
int32_t utrace_getLevel(void)
Getter for the trace level.
UTRACE_ERROR
Trace error conditions only.
Definition: utrace.h:48
U_CDECL_BEGIN
#define U_CDECL_BEGIN
This is used to begin a declaration of a library private ICU C API.
Definition: umachine.h:82
UTRACE_INFO
Trace an intermediate number of ICU operations.
Definition: utrace.h:54
UTraceData
void 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 mes...
Definition: utrace.h:149
utrace_setLevel
void utrace_setLevel(int32_t traceLevel)
Setter for the trace level.
utrace_functionName
const char * utrace_functionName(int32_t fnNumber)
Get the name of a function from its trace function number.
UTRACE_WARNING
Trace errors and warnings.
Definition: utrace.h:50
utrace_setFunctions
void utrace_setFunctions(const void *context, UTraceEntry *e, UTraceExit *x, UTraceData *d)
Set ICU Tracing functions.
utrace_format
int32_t utrace_format(char *outBuf, int32_t capacity, int32_t indent, const char *fmt,...)
Trace output Formatter.
UTraceFunctionNumber
UTraceFunctionNumber
These are the ICU functions that will be traced when tracing is enabled.
Definition: utrace.h:63
U_CDECL_END
#define U_CDECL_END
This is used to end a declaration of a library private ICU C API.
Definition: umachine.h:83
UTRACE_OFF
Disable all tracing.
Definition: utrace.h:46
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UTRACE_OPEN_CLOSE
Trace opens and closes of ICU services.
Definition: utrace.h:52
utrace_vformat
int32_t utrace_vformat(char *outBuf, int32_t capacity, int32_t indent, const char *fmt, va_list args)
Trace output Formatter.
U_STABLE
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:109
utrace_getFunctions
void utrace_getFunctions(const void **context, UTraceEntry **e, UTraceExit **x, UTraceData **d)
Get the currently installed ICU tracing functions.