Benny Prijono | dd859a6 | 2005-11-01 16:42:51 +0000 | [diff] [blame^] | 1 | /* $Header: /pjproject-0.3/pjlib/include/pj/log.h 7 10/14/05 12:26a Bennylp $ */ |
| 2 | |
| 3 | #ifndef __PJ_LOG_H__ |
| 4 | #define __PJ_LOG_H__ |
| 5 | |
| 6 | /** |
| 7 | * @file log.h |
| 8 | * @brief Logging Utility. |
| 9 | */ |
| 10 | |
| 11 | #include <pj/types.h> |
| 12 | |
| 13 | |
| 14 | PJ_BEGIN_DECL |
| 15 | |
| 16 | /** |
| 17 | * @defgroup PJ_MISC Miscelaneous |
| 18 | * @ingroup PJ |
| 19 | */ |
| 20 | |
| 21 | /** |
| 22 | * @defgroup PJ_LOG Logging Facility |
| 23 | * @ingroup PJ_MISC |
| 24 | * @{ |
| 25 | * |
| 26 | * The PJLIB logging facility is a configurable, flexible, and convenient |
| 27 | * way to write logging or trace information. |
| 28 | * |
| 29 | * To write to the log, one uses construct like below: |
| 30 | * |
| 31 | * <pre> |
| 32 | * ... |
| 33 | * PJ_LOG(3, ("main.c", "Starting hello...")); |
| 34 | * ... |
| 35 | * PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid())); |
| 36 | * ... |
| 37 | * </pre> |
| 38 | * |
| 39 | * In the above example, the number @b 3 controls the verbosity level of |
| 40 | * the information (which means "information", by convention). The string |
| 41 | * "main.c" specifies the source or sender of the message. |
| 42 | * |
| 43 | * |
| 44 | * \section pj_log_quick_sample_sec Examples |
| 45 | * |
| 46 | * For examples, see: |
| 47 | * - @ref page_pjlib_samples_log_c. |
| 48 | * |
| 49 | */ |
| 50 | |
| 51 | /** |
| 52 | * Log decoration flag, to be specified with #pj_log_set_decor(). |
| 53 | */ |
| 54 | enum pj_log_decoration |
| 55 | { |
| 56 | PJ_LOG_HAS_DAY_NAME = 1, /**< Include day name [default: no]. */ |
| 57 | PJ_LOG_HAS_YEAR = 2, /**< Include year digit [default: no] */ |
| 58 | PJ_LOG_HAS_MONTH = 4, /**< Include month [default: no] */ |
| 59 | PJ_LOG_HAS_DAY_OF_MON = 8, /**< Include day of month [default: no] */ |
| 60 | PJ_LOG_HAS_TIME = 16, /**< Include time [default: yes]. */ |
| 61 | PJ_LOG_HAS_MICRO_SEC = 32, /**< Include microseconds [yes] */ |
| 62 | PJ_LOG_HAS_SENDER = 64, /**< Include sender in the log [yes]. */ |
| 63 | PJ_LOG_HAS_NEWLINE = 128, /**< Terminate each call with newline [yes].*/ |
| 64 | }; |
| 65 | |
| 66 | /** |
| 67 | * Write log message. |
| 68 | * This is the main macro used to write text to the logging backend. |
| 69 | * |
| 70 | * @param level The logging verbosity level. Lower number indicates higher |
| 71 | * importance, with level zero indicates fatal error. Only |
| 72 | * numeral argument is permitted (e.g. not variable). |
| 73 | * @param arg Enclosed 'printf' like arguments, with the first |
| 74 | * argument is the sender, the second argument is format |
| 75 | * string and the following arguments are variable number of |
| 76 | * arguments suitable for the format string. |
| 77 | * |
| 78 | * Sample: |
| 79 | * \verbatim |
| 80 | PJ_LOG(2, (__FILE__, "current value is %d", value)); |
| 81 | \endverbatim |
| 82 | * @hideinitializer |
| 83 | */ |
| 84 | #define PJ_LOG(level,arg) pj_log_wrapper_##level(arg) |
| 85 | |
| 86 | /** |
| 87 | * Signature for function to be registered to the logging subsystem to |
| 88 | * write the actual log message to some output device. |
| 89 | * |
| 90 | * @param level Log level. |
| 91 | * @param data Log message. |
| 92 | * @param len Message length. |
| 93 | */ |
| 94 | typedef void pj_log_func(int level, const char *data, int len); |
| 95 | |
| 96 | /** |
| 97 | * Default logging writer function used by front end logger function. |
| 98 | * Application normally should NOT need to call this function, but |
| 99 | * rather use the PJ_LOG macro. |
| 100 | * |
| 101 | * @param level Log level. |
| 102 | * @param buffer Log message. |
| 103 | * @param len Message length. |
| 104 | */ |
| 105 | PJ_DECL(void) pj_log_write(int level, const char *buffer, int len); |
| 106 | |
| 107 | |
| 108 | #if PJ_LOG_MAX_LEVEL >= 1 |
| 109 | |
| 110 | /** |
| 111 | * Change log output function. The front-end logging functions will call |
| 112 | * this function to write the actual message to the desired device. |
| 113 | * By default, the front-end functions use pj_log_write() to write |
| 114 | * the messages, unless it's changed by calling this function. |
| 115 | * |
| 116 | * @param func The function that will be called to write the log |
| 117 | * messages to the desired device. |
| 118 | */ |
| 119 | PJ_DECL(void) pj_log_set_log_func( pj_log_func *func ); |
| 120 | |
| 121 | /** |
| 122 | * Get the current log output function that is used to write log messages. |
| 123 | * |
| 124 | * @return Current log output function. |
| 125 | */ |
| 126 | PJ_DECL(pj_log_func*) pj_log_get_log_func(void); |
| 127 | |
| 128 | /** |
| 129 | * Set maximum log level. Application can call this function to set |
| 130 | * the desired level of verbosity of the logging messages. The bigger the |
| 131 | * value, the more verbose the logging messages will be printed. However, |
| 132 | * the maximum level of verbosity can not exceed compile time value of |
| 133 | * PJ_LOG_MAX_LEVEL. |
| 134 | * |
| 135 | * @param level The maximum level of verbosity of the logging |
| 136 | * messages (6=very detailed..1=error only, 0=disabled) |
| 137 | */ |
| 138 | PJ_DECL(void) pj_log_set_level(int level); |
| 139 | |
| 140 | /** |
| 141 | * Get current maximum log verbositylevel. |
| 142 | * |
| 143 | * @return Current log maximum level. |
| 144 | */ |
| 145 | PJ_DECL(int) pj_log_get_level(void); |
| 146 | |
| 147 | /** |
| 148 | * Set log decoration. The log decoration flag controls what are printed |
| 149 | * to output device alongside the actual message. For example, application |
| 150 | * can specify that date/time information should be displayed with each |
| 151 | * log message. |
| 152 | * |
| 153 | * @param decor Bitmask combination of #pj_log_decoration to control |
| 154 | * the layout of the log message. |
| 155 | */ |
| 156 | PJ_DECL(void) pj_log_set_decor(unsigned decor); |
| 157 | |
| 158 | /** |
| 159 | * Get current log decoration flag. |
| 160 | * |
| 161 | * @return Log decoration flag. |
| 162 | */ |
| 163 | PJ_DECL(unsigned) pj_log_get_decor(void); |
| 164 | |
| 165 | |
| 166 | #else /* #if PJ_LOG_MAX_LEVEL >= 1 */ |
| 167 | |
| 168 | /** |
| 169 | * Change log output function. The front-end logging functions will call |
| 170 | * this function to write the actual message to the desired device. |
| 171 | * By default, the front-end functions use pj_log_write() to write |
| 172 | * the messages, unless it's changed by calling this function. |
| 173 | * |
| 174 | * @param func The function that will be called to write the log |
| 175 | * messages to the desired device. |
| 176 | */ |
| 177 | # define pj_log_set_log_func(func) |
| 178 | |
| 179 | /** |
| 180 | * Set maximum log level. Application can call this function to set |
| 181 | * the desired level of verbosity of the logging messages. The bigger the |
| 182 | * value, the more verbose the logging messages will be printed. However, |
| 183 | * the maximum level of verbosity can not exceed compile time value of |
| 184 | * PJ_LOG_MAX_LEVEL. |
| 185 | * |
| 186 | * @param level The maximum level of verbosity of the logging |
| 187 | * messages (6=very detailed..1=error only, 0=disabled) |
| 188 | */ |
| 189 | # define pj_log_set_level(level) |
| 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 | # define pj_log_set_decor(decor) |
| 201 | |
| 202 | #endif /* #if PJ_LOG_MAX_LEVEL >= 1 */ |
| 203 | |
| 204 | /** |
| 205 | * @} |
| 206 | */ |
| 207 | |
| 208 | /////////////////////////////////////////////////////////////////////////////// |
| 209 | /* |
| 210 | * Log functions implementation prototypes. |
| 211 | * These functions are called by PJ_LOG macros according to verbosity |
| 212 | * level specified when calling the macro. Applications should not normally |
| 213 | * need to call these functions directly. |
| 214 | */ |
| 215 | |
| 216 | /** |
| 217 | * @def pj_log_wrapper_1(arg) |
| 218 | * Internal function to write log with verbosity 1. Will evaluate to |
| 219 | * empty expression if PJ_LOG_MAX_LEVEL is below 1. |
| 220 | * @param arg Log expression. |
| 221 | */ |
| 222 | #if PJ_LOG_MAX_LEVEL >= 1 |
| 223 | #define pj_log_wrapper_1(arg) pj_log_1 arg |
| 224 | /** Internal function. */ |
| 225 | PJ_DECL(void) pj_log_1(const char *src, const char *format, ...); |
| 226 | #else |
| 227 | #define pj_log_wrapper_1(arg) |
| 228 | #endif |
| 229 | |
| 230 | /** |
| 231 | * @def pj_log_wrapper_2(arg) |
| 232 | * Internal function to write log with verbosity 2. Will evaluate to |
| 233 | * empty expression if PJ_LOG_MAX_LEVEL is below 2. |
| 234 | * @param arg Log expression. |
| 235 | */ |
| 236 | #if PJ_LOG_MAX_LEVEL >= 2 |
| 237 | #define pj_log_wrapper_2(arg) pj_log_2 arg |
| 238 | /** Internal function. */ |
| 239 | PJ_DECL(void) pj_log_2(const char *src, const char *format, ...); |
| 240 | #else |
| 241 | #define pj_log_wrapper_2(arg) |
| 242 | #endif |
| 243 | |
| 244 | /** |
| 245 | * @def pj_log_wrapper_3(arg) |
| 246 | * Internal function to write log with verbosity 3. Will evaluate to |
| 247 | * empty expression if PJ_LOG_MAX_LEVEL is below 3. |
| 248 | * @param arg Log expression. |
| 249 | */ |
| 250 | #if PJ_LOG_MAX_LEVEL >= 3 |
| 251 | #define pj_log_wrapper_3(arg) pj_log_3 arg |
| 252 | /** Internal function. */ |
| 253 | PJ_DECL(void) pj_log_3(const char *src, const char *format, ...); |
| 254 | #else |
| 255 | #define pj_log_wrapper_3(arg) |
| 256 | #endif |
| 257 | |
| 258 | /** |
| 259 | * @def pj_log_wrapper_4(arg) |
| 260 | * Internal function to write log with verbosity 4. Will evaluate to |
| 261 | * empty expression if PJ_LOG_MAX_LEVEL is below 4. |
| 262 | * @param arg Log expression. |
| 263 | */ |
| 264 | #if PJ_LOG_MAX_LEVEL >= 4 |
| 265 | #define pj_log_wrapper_4(arg) pj_log_4 arg |
| 266 | /** Internal function. */ |
| 267 | PJ_DECL(void) pj_log_4(const char *src, const char *format, ...); |
| 268 | #else |
| 269 | #define pj_log_wrapper_4(arg) |
| 270 | #endif |
| 271 | |
| 272 | /** |
| 273 | * @def pj_log_wrapper_5(arg) |
| 274 | * Internal function to write log with verbosity 5. Will evaluate to |
| 275 | * empty expression if PJ_LOG_MAX_LEVEL is below 5. |
| 276 | * @param arg Log expression. |
| 277 | */ |
| 278 | #if PJ_LOG_MAX_LEVEL >= 5 |
| 279 | #define pj_log_wrapper_5(arg) pj_log_5 arg |
| 280 | /** Internal function. */ |
| 281 | PJ_DECL(void) pj_log_5(const char *src, const char *format, ...); |
| 282 | #else |
| 283 | #define pj_log_wrapper_5(arg) |
| 284 | #endif |
| 285 | |
| 286 | /** |
| 287 | * @def pj_log_wrapper_6(arg) |
| 288 | * Internal function to write log with verbosity 6. Will evaluate to |
| 289 | * empty expression if PJ_LOG_MAX_LEVEL is below 6. |
| 290 | * @param arg Log expression. |
| 291 | */ |
| 292 | #if PJ_LOG_MAX_LEVEL >= 6 |
| 293 | #define pj_log_wrapper_6(arg) pj_log_6 arg |
| 294 | /** Internal function. */ |
| 295 | PJ_DECL(void) pj_log_6(const char *src, const char *format, ...); |
| 296 | #else |
| 297 | #define pj_log_wrapper_6(arg) |
| 298 | #endif |
| 299 | |
| 300 | |
| 301 | PJ_END_DECL |
| 302 | |
| 303 | #endif /* __PJ_LOG_H__ */ |
| 304 | |