1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 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. 10 * 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. 15 * 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 19 */ 20 #ifndef __PJ_LOG_H__ 21 #define __PJ_LOG_H__ 22 23 /** 24 * @file log.h 25 * @brief Logging Utility. 26 */ 27 28 #include <pj/types.h> 29 #include <stdarg.h> 30 31 PJ_BEGIN_DECL 32 33 /** 34 * @defgroup PJ_MISC Miscelaneous 35 */ 36 37 /** 38 * @defgroup PJ_LOG Logging Facility 39 * @ingroup PJ_MISC 40 * @{ 41 * 42 * The PJLIB logging facility is a configurable, flexible, and convenient 43 * way to write logging or trace information. 44 * 45 * To write to the log, one uses construct like below: 46 * 47 * <pre> 48 * ... 49 * PJ_LOG(3, ("main.c", "Starting hello...")); 50 * ... 51 * PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid())); 52 * ... 53 * </pre> 54 * 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. 58 * 59 * 60 * \section pj_log_quick_sample_sec Examples 61 * 62 * For examples, see: 63 * - @ref page_pjlib_samples_log_c. 64 * 65 */ 66 67 /** 68 * Log decoration flag, to be specified with #pj_log_set_decor(). 69 */ 70 enum pj_log_decoration 71 { 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] */ 87 }; 88 89 /** 90 * Write log message. 91 * This is the main macro used to write text to the logging backend. 92 * 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. 100 * 101 * Sample: 102 * \verbatim 103 PJ_LOG(2, (__FILE__, "current value is %d", value)); 104 \endverbatim 105 * @hideinitializer 106 */ 107 #define PJ_LOG(level,arg) do { \ 108 if (level <= pj_log_get_level()) { \ 109 pj_log_wrapper_##level(arg); \ 110 } \ 111 } while (0) 112 113 /** 114 * Signature for function to be registered to the logging subsystem to 115 * write the actual log message to some output device. 116 * 117 * @param level Log level. 118 * @param data Log message, which will be NULL terminated. 119 * @param len Message length. 120 */ 121 typedef void pj_log_func(int level, const char *data, int len); 122 123 /** 124 * Default logging writer function used by front end logger function. 125 * This function will print the log message to stdout only. 126 * Application normally should NOT need to call this function, but 127 * rather use the PJ_LOG macro. 128 * 129 * @param level Log level. 130 * @param buffer Log message. 131 * @param len Message length. 132 */ 133 PJ_DECL(void) pj_log_write(int level, const char *buffer, int len); 134 135 136 #if PJ_LOG_MAX_LEVEL >= 1 137 138 /** 139 * Write to log. 140 * 141 * @param sender Source of the message. 142 * @param level Verbosity level. 143 * @param format Format. 144 * @param marker Marker. 145 */ 146 PJ_DECL(void) pj_log(const char *sender, int level, 147 const char *format, va_list marker); 148 149 /** 150 * Change log output function. The front-end logging functions will call 151 * this function to write the actual message to the desired device. 152 * By default, the front-end functions use pj_log_write() to write 153 * the messages, unless it's changed by calling this function. 154 * 155 * @param func The function that will be called to write the log 156 * messages to the desired device. 157 */ 158 PJ_DECL(void) pj_log_set_log_func( pj_log_func *func ); 159 160 /** 161 * Get the current log output function that is used to write log messages. 162 * 163 * @return Current log output function. 164 */ 165 PJ_DECL(pj_log_func*) pj_log_get_log_func(void); 166 167 /** 168 * Set maximum log level. Application can call this function to set 169 * the desired level of verbosity of the logging messages. The bigger the 170 * value, the more verbose the logging messages will be printed. However, 171 * the maximum level of verbosity can not exceed compile time value of 172 * PJ_LOG_MAX_LEVEL. 173 * 174 * @param level The maximum level of verbosity of the logging 175 * messages (6=very detailed..1=error only, 0=disabled) 176 */ 177 PJ_DECL(void) pj_log_set_level(int level); 178 179 /** 180 * Get current maximum log verbositylevel. 181 * 182 * @return Current log maximum level. 183 */ 184 #if 1 185 PJ_DECL(int) pj_log_get_level(void); 186 #else 187 PJ_DECL_DATA(int) pj_log_max_level; 188 #define pj_log_get_level() pj_log_max_level 189 #endif 190 191 /** 192 * Set log decoration. The log decoration flag controls what are printed 193 * to output device alongside the actual message. For example, application 194 * can specify that date/time information should be displayed with each 195 * log message. 196 * 197 * @param decor Bitmask combination of #pj_log_decoration to control 198 * the layout of the log message. 199 */ 200 PJ_DECL(void) pj_log_set_decor(unsigned decor); 201 202 /** 203 * Get current log decoration flag. 204 * 205 * @return Log decoration flag. 206 */ 207 PJ_DECL(unsigned) pj_log_get_decor(void); 208 209 /** 210 * Add indentation to log message. Indentation will add PJ_LOG_INDENT_CHAR 211 * before the message, and is useful to show the depth of function calls. 212 * 213 * @param indent The indentation to add or substract. Positive value 214 * adds current indent, negative value subtracts current 215 * indent. 216 */ 217 PJ_DECL(void) pj_log_add_indent(int indent); 218 219 /** 220 * Push indentation to the right by default value (PJ_LOG_INDENT). 221 */ 222 PJ_DECL(void) pj_log_push_indent(void); 223 224 /** 225 * Pop indentation (to the left) by default value (PJ_LOG_INDENT). 226 */ 227 PJ_DECL(void) pj_log_pop_indent(void); 228 229 /** 230 * Set color of log messages. 231 * 232 * @param level Log level which color will be changed. 233 * @param color Desired color. 234 */ 235 PJ_DECL(void) pj_log_set_color(int level, pj_color_t color); 236 237 /** 238 * Get color of log messages. 239 * 240 * @param level Log level which color will be returned. 241 * @return Log color. 242 */ 243 PJ_DECL(pj_color_t) pj_log_get_color(int level); 244 245 /** 246 * Internal function to be called by pj_init() 247 */ 248 pj_status_t pj_log_init(void); 249 250 #else /* #if PJ_LOG_MAX_LEVEL >= 1 */ 251 252 /** 253 * Change log output function. The front-end logging functions will call 254 * this function to write the actual message to the desired device. 255 * By default, the front-end functions use pj_log_write() to write 256 * the messages, unless it's changed by calling this function. 257 * 258 * @param func The function that will be called to write the log 259 * messages to the desired device. 260 */ 261 # define pj_log_set_log_func(func) 262 263 /** 264 * Write to log. 265 * 266 * @param sender Source of the message. 267 * @param level Verbosity level. 268 * @param format Format. 269 * @param marker Marker. 270 */ 271 # define pj_log(sender, level, format, marker) 272 273 /** 274 * Set maximum log level. Application can call this function to set 275 * the desired level of verbosity of the logging messages. The bigger the 276 * value, the more verbose the logging messages will be printed. However, 277 * the maximum level of verbosity can not exceed compile time value of 278 * PJ_LOG_MAX_LEVEL. 279 * 280 * @param level The maximum level of verbosity of the logging 281 * messages (6=very detailed..1=error only, 0=disabled) 282 */ 283 # define pj_log_set_level(level) 284 285 /** 286 * Set log decoration. The log decoration flag controls what are printed 287 * to output device alongside the actual message. For example, application 288 * can specify that date/time information should be displayed with each 289 * log message. 290 * 291 * @param decor Bitmask combination of #pj_log_decoration to control 292 * the layout of the log message. 293 */ 294 # define pj_log_set_decor(decor) 295 296 /** 297 * Add indentation to log message. Indentation will add PJ_LOG_INDENT_CHAR 298 * before the message, and is useful to show the depth of function calls. 299 * 300 * @param indent The indentation to add or substract. Positive value 301 * adds current indent, negative value subtracts current 302 * indent. 303 */ 304 # define pj_log_add_indent(indent) 305 306 /** 307 * Push indentation to the right by default value (PJ_LOG_INDENT). 308 */ 309 # define pj_log_push_indent() 310 311 /** 312 * Pop indentation (to the left) by default value (PJ_LOG_INDENT). 313 */ 314 # define pj_log_pop_indent() 315 316 /** 317 * Set color of log messages. 318 * 319 * @param level Log level which color will be changed. 320 * @param color Desired color. 321 */ 322 # define pj_log_set_color(level, color) 323 324 /** 325 * Get current maximum log verbositylevel. 326 * 327 * @return Current log maximum level. 328 */ 329 # define pj_log_get_level() 0 330 331 /** 332 * Get current log decoration flag. 333 * 334 * @return Log decoration flag. 335 */ 336 # define pj_log_get_decor() 0 337 338 /** 339 * Get color of log messages. 340 * 341 * @param level Log level which color will be returned. 342 * @return Log color. 343 */ 344 # define pj_log_get_color(level) 0 345 346 347 /** 348 * Internal. 349 */ 350 # define pj_log_init() PJ_SUCCESS 351 352 #endif /* #if PJ_LOG_MAX_LEVEL >= 1 */ 353 354 /** 355 * @} 356 */ 357 358 /* **************************************************************************/ 359 /* 360 * Log functions implementation prototypes. 361 * These functions are called by PJ_LOG macros according to verbosity 362 * level specified when calling the macro. Applications should not normally 363 * need to call these functions directly. 364 */ 365 366 /** 367 * @def pj_log_wrapper_1(arg) 368 * Internal function to write log with verbosity 1. Will evaluate to 369 * empty expression if PJ_LOG_MAX_LEVEL is below 1. 370 * @param arg Log expression. 371 */ 372 #if PJ_LOG_MAX_LEVEL >= 1 373 #define pj_log_wrapper_1(arg) pj_log_1 arg 374 /** Internal function. */ 375 PJ_DECL(void) pj_log_1(const char *src, const char *format, ...); 376 #else 377 #define pj_log_wrapper_1(arg) 378 #endif 379 380 /** 381 * @def pj_log_wrapper_2(arg) 382 * Internal function to write log with verbosity 2. Will evaluate to 383 * empty expression if PJ_LOG_MAX_LEVEL is below 2. 384 * @param arg Log expression. 385 */ 386 #if PJ_LOG_MAX_LEVEL >= 2 387 #define pj_log_wrapper_2(arg) pj_log_2 arg 388 /** Internal function. */ 389 PJ_DECL(void) pj_log_2(const char *src, const char *format, ...); 390 #else 391 #define pj_log_wrapper_2(arg) 392 #endif 393 394 /** 395 * @def pj_log_wrapper_3(arg) 396 * Internal function to write log with verbosity 3. Will evaluate to 397 * empty expression if PJ_LOG_MAX_LEVEL is below 3. 398 * @param arg Log expression. 399 */ 400 #if PJ_LOG_MAX_LEVEL >= 3 401 #define pj_log_wrapper_3(arg) pj_log_3 arg 402 /** Internal function. */ 403 PJ_DECL(void) pj_log_3(const char *src, const char *format, ...); 404 #else 405 #define pj_log_wrapper_3(arg) 406 #endif 407 408 /** 409 * @def pj_log_wrapper_4(arg) 410 * Internal function to write log with verbosity 4. Will evaluate to 411 * empty expression if PJ_LOG_MAX_LEVEL is below 4. 412 * @param arg Log expression. 413 */ 414 #if PJ_LOG_MAX_LEVEL >= 4 415 #define pj_log_wrapper_4(arg) pj_log_4 arg 416 /** Internal function. */ 417 PJ_DECL(void) pj_log_4(const char *src, const char *format, ...); 418 #else 419 #define pj_log_wrapper_4(arg) 420 #endif 421 422 /** 423 * @def pj_log_wrapper_5(arg) 424 * Internal function to write log with verbosity 5. Will evaluate to 425 * empty expression if PJ_LOG_MAX_LEVEL is below 5. 426 * @param arg Log expression. 427 */ 428 #if PJ_LOG_MAX_LEVEL >= 5 429 #define pj_log_wrapper_5(arg) pj_log_5 arg 430 /** Internal function. */ 431 PJ_DECL(void) pj_log_5(const char *src, const char *format, ...); 432 #else 433 #define pj_log_wrapper_5(arg) 434 #endif 435 436 /** 437 * @def pj_log_wrapper_6(arg) 438 * Internal function to write log with verbosity 6. Will evaluate to 439 * empty expression if PJ_LOG_MAX_LEVEL is below 6. 440 * @param arg Log expression. 441 */ 442 #if PJ_LOG_MAX_LEVEL >= 6 443 #define pj_log_wrapper_6(arg) pj_log_6 arg 444 /** Internal function. */ 445 PJ_DECL(void) pj_log_6(const char *src, const char *format, ...); 446 #else 447 #define pj_log_wrapper_6(arg) 448 #endif 449 450 451 PJ_END_DECL 452 453 #endif /* __PJ_LOG_H__ */ 454 455