1
/* $Id: log.h 3752 2011-09-18 14:38:46Z bennylp $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25
* @brief Logging Utility.
34
* @defgroup PJ_MISC Miscelaneous
38
* @defgroup PJ_LOG Logging Facility
42
* The PJLIB logging facility is a configurable, flexible, and convenient
43
* way to write logging or trace information.
45
* To write to the log, one uses construct like below:
49
* PJ_LOG(3, ("main.c", "Starting hello..."));
51
* PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid()));
55
* In the above example, the number @b 3 controls the verbosity level of
56
* the information (which means "information", by convention). The string
57
* "main.c" specifies the source or sender of the message.
60
* \section pj_log_quick_sample_sec Examples
63
* - @ref page_pjlib_samples_log_c.
68
* Log decoration flag, to be specified with #pj_log_set_decor().
70
enum pj_log_decoration
72
PJ_LOG_HAS_DAY_NAME = 1, /**< Include day name [default: no] */
73
PJ_LOG_HAS_YEAR = 2, /**< Include year digit [no] */
74
PJ_LOG_HAS_MONTH = 4, /**< Include month [no] */
75
PJ_LOG_HAS_DAY_OF_MON = 8, /**< Include day of month [no] */
76
PJ_LOG_HAS_TIME = 16, /**< Include time [yes] */
77
PJ_LOG_HAS_MICRO_SEC = 32, /**< Include microseconds [yes] */
78
PJ_LOG_HAS_SENDER = 64, /**< Include sender in the log [yes] */
79
PJ_LOG_HAS_NEWLINE = 128, /**< Terminate each call with newline [yes] */
80
PJ_LOG_HAS_CR = 256, /**< Include carriage return [no] */
81
PJ_LOG_HAS_SPACE = 512, /**< Include two spaces before log [yes] */
82
PJ_LOG_HAS_COLOR = 1024, /**< Colorize logs [yes on win32] */
83
PJ_LOG_HAS_LEVEL_TEXT = 2048, /**< Include level text string [no] */
84
PJ_LOG_HAS_THREAD_ID = 4096, /**< Include thread identification [no] */
85
PJ_LOG_HAS_THREAD_SWC = 8192, /**< Add mark when thread has switched [yes]*/
86
PJ_LOG_HAS_INDENT =16384 /**< Indentation. Say yes! [yes] */
91
* This is the main macro used to write text to the logging backend.
93
* @param level The logging verbosity level. Lower number indicates higher
94
* importance, with level zero indicates fatal error. Only
95
* numeral argument is permitted (e.g. not variable).
96
* @param arg Enclosed 'printf' like arguments, with the first
97
* argument is the sender, the second argument is format
98
* string and the following arguments are variable number of
99
* arguments suitable for the format string.
103
PJ_LOG(2, (__FILE__, "current value is %d", value));
107
#define PJ_LOG(level,arg) do { \
108
if (level <= pj_log_get_level()) \
109
pj_log_wrapper_##level(arg); \
113
* Signature for function to be registered to the logging subsystem to
114
* write the actual log message to some output device.
116
* @param level Log level.
117
* @param data Log message, which will be NULL terminated.
118
* @param len Message length.
120
typedef void pj_log_func(int level, const char *data, int len);
123
* Default logging writer function used by front end logger function.
124
* This function will print the log message to stdout only.
125
* Application normally should NOT need to call this function, but
126
* rather use the PJ_LOG macro.
128
* @param level Log level.
129
* @param buffer Log message.
130
* @param len Message length.
132
PJ_DECL(void) pj_log_write(int level, const char *buffer, int len);
135
#if PJ_LOG_MAX_LEVEL >= 1
140
* @param sender Source of the message.
141
* @param level Verbosity level.
142
* @param format Format.
143
* @param marker Marker.
145
PJ_DECL(void) pj_log(const char *sender, int level,
146
const char *format, va_list marker);
149
* Change log output function. The front-end logging functions will call
150
* this function to write the actual message to the desired device.
151
* By default, the front-end functions use pj_log_write() to write
152
* the messages, unless it's changed by calling this function.
154
* @param func The function that will be called to write the log
155
* messages to the desired device.
157
PJ_DECL(void) pj_log_set_log_func( pj_log_func *func );
160
* Get the current log output function that is used to write log messages.
162
* @return Current log output function.
164
PJ_DECL(pj_log_func*) pj_log_get_log_func(void);
167
* Set maximum log level. Application can call this function to set
168
* the desired level of verbosity of the logging messages. The bigger the
169
* value, the more verbose the logging messages will be printed. However,
170
* the maximum level of verbosity can not exceed compile time value of
173
* @param level The maximum level of verbosity of the logging
174
* messages (6=very detailed..1=error only, 0=disabled)
176
PJ_DECL(void) pj_log_set_level(int level);
179
* Get current maximum log verbositylevel.
181
* @return Current log maximum level.
184
PJ_DECL(int) pj_log_get_level(void);
186
PJ_DECL_DATA(int) pj_log_max_level;
187
#define pj_log_get_level() pj_log_max_level
191
* Set log decoration. The log decoration flag controls what are printed
192
* to output device alongside the actual message. For example, application
193
* can specify that date/time information should be displayed with each
196
* @param decor Bitmask combination of #pj_log_decoration to control
197
* the layout of the log message.
199
PJ_DECL(void) pj_log_set_decor(unsigned decor);
202
* Get current log decoration flag.
204
* @return Log decoration flag.
206
PJ_DECL(unsigned) pj_log_get_decor(void);
209
* Add indentation to log message. Indentation will add PJ_LOG_INDENT_CHAR
210
* before the message, and is useful to show the depth of function calls.
212
* @param indent The indentation to add or substract. Positive value
213
* adds current indent, negative value subtracts current
216
PJ_DECL(void) pj_log_add_indent(int indent);
219
* Push indentation to the right by default value (PJ_LOG_INDENT).
221
PJ_DECL(void) pj_log_push_indent(void);
224
* Pop indentation (to the left) by default value (PJ_LOG_INDENT).
226
PJ_DECL(void) pj_log_pop_indent(void);
229
* Set color of log messages.
231
* @param level Log level which color will be changed.
232
* @param color Desired color.
234
PJ_DECL(void) pj_log_set_color(int level, pj_color_t color);
237
* Get color of log messages.
239
* @param level Log level which color will be returned.
242
PJ_DECL(pj_color_t) pj_log_get_color(int level);
245
* Internal function to be called by pj_init()
247
pj_status_t pj_log_init(void);
249
#else /* #if PJ_LOG_MAX_LEVEL >= 1 */
252
* Change log output function. The front-end logging functions will call
253
* this function to write the actual message to the desired device.
254
* By default, the front-end functions use pj_log_write() to write
255
* the messages, unless it's changed by calling this function.
257
* @param func The function that will be called to write the log
258
* messages to the desired device.
260
# define pj_log_set_log_func(func)
263
* Set maximum log level. Application can call this function to set
264
* the desired level of verbosity of the logging messages. The bigger the
265
* value, the more verbose the logging messages will be printed. However,
266
* the maximum level of verbosity can not exceed compile time value of
269
* @param level The maximum level of verbosity of the logging
270
* messages (6=very detailed..1=error only, 0=disabled)
272
# define pj_log_set_level(level)
275
* Set log decoration. The log decoration flag controls what are printed
276
* to output device alongside the actual message. For example, application
277
* can specify that date/time information should be displayed with each
280
* @param decor Bitmask combination of #pj_log_decoration to control
281
* the layout of the log message.
283
# define pj_log_set_decor(decor)
286
* Set color of log messages.
288
* @param level Log level which color will be changed.
289
* @param color Desired color.
291
# define pj_log_set_color(level, color)
294
* Get current maximum log verbositylevel.
296
* @return Current log maximum level.
298
# define pj_log_get_level() 0
301
* Get current log decoration flag.
303
* @return Log decoration flag.
305
# define pj_log_get_decor() 0
308
* Get color of log messages.
310
* @param level Log level which color will be returned.
313
# define pj_log_get_color(level) 0
319
# define pj_log_init() PJ_SUCCESS
321
#endif /* #if PJ_LOG_MAX_LEVEL >= 1 */
327
/* **************************************************************************/
329
* Log functions implementation prototypes.
330
* These functions are called by PJ_LOG macros according to verbosity
331
* level specified when calling the macro. Applications should not normally
332
* need to call these functions directly.
336
* @def pj_log_wrapper_1(arg)
337
* Internal function to write log with verbosity 1. Will evaluate to
338
* empty expression if PJ_LOG_MAX_LEVEL is below 1.
339
* @param arg Log expression.
341
#if PJ_LOG_MAX_LEVEL >= 1
342
#define pj_log_wrapper_1(arg) pj_log_1 arg
343
/** Internal function. */
344
PJ_DECL(void) pj_log_1(const char *src, const char *format, ...);
346
#define pj_log_wrapper_1(arg)
350
* @def pj_log_wrapper_2(arg)
351
* Internal function to write log with verbosity 2. Will evaluate to
352
* empty expression if PJ_LOG_MAX_LEVEL is below 2.
353
* @param arg Log expression.
355
#if PJ_LOG_MAX_LEVEL >= 2
356
#define pj_log_wrapper_2(arg) pj_log_2 arg
357
/** Internal function. */
358
PJ_DECL(void) pj_log_2(const char *src, const char *format, ...);
360
#define pj_log_wrapper_2(arg)
364
* @def pj_log_wrapper_3(arg)
365
* Internal function to write log with verbosity 3. Will evaluate to
366
* empty expression if PJ_LOG_MAX_LEVEL is below 3.
367
* @param arg Log expression.
369
#if PJ_LOG_MAX_LEVEL >= 3
370
#define pj_log_wrapper_3(arg) pj_log_3 arg
371
/** Internal function. */
372
PJ_DECL(void) pj_log_3(const char *src, const char *format, ...);
374
#define pj_log_wrapper_3(arg)
378
* @def pj_log_wrapper_4(arg)
379
* Internal function to write log with verbosity 4. Will evaluate to
380
* empty expression if PJ_LOG_MAX_LEVEL is below 4.
381
* @param arg Log expression.
383
#if PJ_LOG_MAX_LEVEL >= 4
384
#define pj_log_wrapper_4(arg) pj_log_4 arg
385
/** Internal function. */
386
PJ_DECL(void) pj_log_4(const char *src, const char *format, ...);
388
#define pj_log_wrapper_4(arg)
392
* @def pj_log_wrapper_5(arg)
393
* Internal function to write log with verbosity 5. Will evaluate to
394
* empty expression if PJ_LOG_MAX_LEVEL is below 5.
395
* @param arg Log expression.
397
#if PJ_LOG_MAX_LEVEL >= 5
398
#define pj_log_wrapper_5(arg) pj_log_5 arg
399
/** Internal function. */
400
PJ_DECL(void) pj_log_5(const char *src, const char *format, ...);
402
#define pj_log_wrapper_5(arg)
406
* @def pj_log_wrapper_6(arg)
407
* Internal function to write log with verbosity 6. Will evaluate to
408
* empty expression if PJ_LOG_MAX_LEVEL is below 6.
409
* @param arg Log expression.
411
#if PJ_LOG_MAX_LEVEL >= 6
412
#define pj_log_wrapper_6(arg) pj_log_6 arg
413
/** Internal function. */
414
PJ_DECL(void) pj_log_6(const char *src, const char *format, ...);
416
#define pj_log_wrapper_6(arg)
422
#endif /* __PJ_LOG_H__ */