Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id: log.h 3752 2011-09-18 14:38:46Z bennylp $ */ |
| 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 | } while (0) |
| 111 | |
| 112 | /** |
| 113 | * Signature for function to be registered to the logging subsystem to |
| 114 | * write the actual log message to some output device. |
| 115 | * |
| 116 | * @param level Log level. |
| 117 | * @param data Log message, which will be NULL terminated. |
| 118 | * @param len Message length. |
| 119 | */ |
| 120 | typedef void pj_log_func(int level, const char *data, int len); |
| 121 | |
| 122 | /** |
| 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. |
| 127 | * |
| 128 | * @param level Log level. |
| 129 | * @param buffer Log message. |
| 130 | * @param len Message length. |
| 131 | */ |
| 132 | PJ_DECL(void) pj_log_write(int level, const char *buffer, int len); |
| 133 | |
| 134 | |
| 135 | #if PJ_LOG_MAX_LEVEL >= 1 |
| 136 | |
| 137 | /** |
| 138 | * Write to log. |
| 139 | * |
| 140 | * @param sender Source of the message. |
| 141 | * @param level Verbosity level. |
| 142 | * @param format Format. |
| 143 | * @param marker Marker. |
| 144 | */ |
| 145 | PJ_DECL(void) pj_log(const char *sender, int level, |
| 146 | const char *format, va_list marker); |
| 147 | |
| 148 | /** |
| 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. |
| 153 | * |
| 154 | * @param func The function that will be called to write the log |
| 155 | * messages to the desired device. |
| 156 | */ |
| 157 | PJ_DECL(void) pj_log_set_log_func( pj_log_func *func ); |
| 158 | |
| 159 | /** |
| 160 | * Get the current log output function that is used to write log messages. |
| 161 | * |
| 162 | * @return Current log output function. |
| 163 | */ |
| 164 | PJ_DECL(pj_log_func*) pj_log_get_log_func(void); |
| 165 | |
| 166 | /** |
| 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 |
| 171 | * PJ_LOG_MAX_LEVEL. |
| 172 | * |
| 173 | * @param level The maximum level of verbosity of the logging |
| 174 | * messages (6=very detailed..1=error only, 0=disabled) |
| 175 | */ |
| 176 | PJ_DECL(void) pj_log_set_level(int level); |
| 177 | |
| 178 | /** |
| 179 | * Get current maximum log verbositylevel. |
| 180 | * |
| 181 | * @return Current log maximum level. |
| 182 | */ |
| 183 | #if 1 |
| 184 | PJ_DECL(int) pj_log_get_level(void); |
| 185 | #else |
| 186 | PJ_DECL_DATA(int) pj_log_max_level; |
| 187 | #define pj_log_get_level() pj_log_max_level |
| 188 | #endif |
| 189 | |
| 190 | /** |
| 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 |
| 194 | * log message. |
| 195 | * |
| 196 | * @param decor Bitmask combination of #pj_log_decoration to control |
| 197 | * the layout of the log message. |
| 198 | */ |
| 199 | PJ_DECL(void) pj_log_set_decor(unsigned decor); |
| 200 | |
| 201 | /** |
| 202 | * Get current log decoration flag. |
| 203 | * |
| 204 | * @return Log decoration flag. |
| 205 | */ |
| 206 | PJ_DECL(unsigned) pj_log_get_decor(void); |
| 207 | |
| 208 | /** |
| 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. |
| 211 | * |
| 212 | * @param indent The indentation to add or substract. Positive value |
| 213 | * adds current indent, negative value subtracts current |
| 214 | * indent. |
| 215 | */ |
| 216 | PJ_DECL(void) pj_log_add_indent(int indent); |
| 217 | |
| 218 | /** |
| 219 | * Push indentation to the right by default value (PJ_LOG_INDENT). |
| 220 | */ |
| 221 | PJ_DECL(void) pj_log_push_indent(void); |
| 222 | |
| 223 | /** |
| 224 | * Pop indentation (to the left) by default value (PJ_LOG_INDENT). |
| 225 | */ |
| 226 | PJ_DECL(void) pj_log_pop_indent(void); |
| 227 | |
| 228 | /** |
| 229 | * Set color of log messages. |
| 230 | * |
| 231 | * @param level Log level which color will be changed. |
| 232 | * @param color Desired color. |
| 233 | */ |
| 234 | PJ_DECL(void) pj_log_set_color(int level, pj_color_t color); |
| 235 | |
| 236 | /** |
| 237 | * Get color of log messages. |
| 238 | * |
| 239 | * @param level Log level which color will be returned. |
| 240 | * @return Log color. |
| 241 | */ |
| 242 | PJ_DECL(pj_color_t) pj_log_get_color(int level); |
| 243 | |
| 244 | /** |
| 245 | * Internal function to be called by pj_init() |
| 246 | */ |
| 247 | pj_status_t pj_log_init(void); |
| 248 | |
| 249 | #else /* #if PJ_LOG_MAX_LEVEL >= 1 */ |
| 250 | |
| 251 | /** |
| 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. |
| 256 | * |
| 257 | * @param func The function that will be called to write the log |
| 258 | * messages to the desired device. |
| 259 | */ |
| 260 | # define pj_log_set_log_func(func) |
| 261 | |
| 262 | /** |
| 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 |
| 267 | * PJ_LOG_MAX_LEVEL. |
| 268 | * |
| 269 | * @param level The maximum level of verbosity of the logging |
| 270 | * messages (6=very detailed..1=error only, 0=disabled) |
| 271 | */ |
| 272 | # define pj_log_set_level(level) |
| 273 | |
| 274 | /** |
| 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 |
| 278 | * log message. |
| 279 | * |
| 280 | * @param decor Bitmask combination of #pj_log_decoration to control |
| 281 | * the layout of the log message. |
| 282 | */ |
| 283 | # define pj_log_set_decor(decor) |
| 284 | |
| 285 | /** |
| 286 | * Set color of log messages. |
| 287 | * |
| 288 | * @param level Log level which color will be changed. |
| 289 | * @param color Desired color. |
| 290 | */ |
| 291 | # define pj_log_set_color(level, color) |
| 292 | |
| 293 | /** |
| 294 | * Get current maximum log verbositylevel. |
| 295 | * |
| 296 | * @return Current log maximum level. |
| 297 | */ |
| 298 | # define pj_log_get_level() 0 |
| 299 | |
| 300 | /** |
| 301 | * Get current log decoration flag. |
| 302 | * |
| 303 | * @return Log decoration flag. |
| 304 | */ |
| 305 | # define pj_log_get_decor() 0 |
| 306 | |
| 307 | /** |
| 308 | * Get color of log messages. |
| 309 | * |
| 310 | * @param level Log level which color will be returned. |
| 311 | * @return Log color. |
| 312 | */ |
| 313 | # define pj_log_get_color(level) 0 |
| 314 | |
| 315 | |
| 316 | /** |
| 317 | * Internal. |
| 318 | */ |
| 319 | # define pj_log_init() PJ_SUCCESS |
| 320 | |
| 321 | #endif /* #if PJ_LOG_MAX_LEVEL >= 1 */ |
| 322 | |
| 323 | /** |
| 324 | * @} |
| 325 | */ |
| 326 | |
| 327 | /* **************************************************************************/ |
| 328 | /* |
| 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. |
| 333 | */ |
| 334 | |
| 335 | /** |
| 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. |
| 340 | */ |
| 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, ...); |
| 345 | #else |
| 346 | #define pj_log_wrapper_1(arg) |
| 347 | #endif |
| 348 | |
| 349 | /** |
| 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. |
| 354 | */ |
| 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, ...); |
| 359 | #else |
| 360 | #define pj_log_wrapper_2(arg) |
| 361 | #endif |
| 362 | |
| 363 | /** |
| 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. |
| 368 | */ |
| 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, ...); |
| 373 | #else |
| 374 | #define pj_log_wrapper_3(arg) |
| 375 | #endif |
| 376 | |
| 377 | /** |
| 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. |
| 382 | */ |
| 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, ...); |
| 387 | #else |
| 388 | #define pj_log_wrapper_4(arg) |
| 389 | #endif |
| 390 | |
| 391 | /** |
| 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. |
| 396 | */ |
| 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, ...); |
| 401 | #else |
| 402 | #define pj_log_wrapper_5(arg) |
| 403 | #endif |
| 404 | |
| 405 | /** |
| 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. |
| 410 | */ |
| 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, ...); |
| 415 | #else |
| 416 | #define pj_log_wrapper_6(arg) |
| 417 | #endif |
| 418 | |
| 419 | |
| 420 | PJ_END_DECL |
| 421 | |
| 422 | #endif /* __PJ_LOG_H__ */ |
| 423 | |