logger.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020   \file logger.h
00021   \brief Support for logging to various files, console and syslog
00022    Configuration in file logger.conf
00023 */
00024 
00025 #ifndef _ASTERISK_LOGGER_H
00026 #define _ASTERISK_LOGGER_H
00027 
00028 #include "asterisk/options.h" /* need option_debug */
00029 
00030 #if defined(__cplusplus) || defined(c_plusplus)
00031 extern "C" {
00032 #endif
00033 
00034 #define EVENTLOG "event_log"
00035 #define  QUEUELOG "queue_log"
00036 
00037 #define DEBUG_M(a) { \
00038    a; \
00039 }
00040 
00041 #define VERBOSE_PREFIX_1 " "
00042 #define VERBOSE_PREFIX_2 "  == "
00043 #define VERBOSE_PREFIX_3 "    -- "
00044 #define VERBOSE_PREFIX_4 "       > "
00045 
00046 #define AST_CALLID_BUFFER_LENGTH 13
00047 
00048 /*! \brief Used for sending a log message
00049    This is the standard logger function.  Probably the only way you will invoke it would be something like this:
00050    ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
00051    where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
00052    on which log you wish to output to. These are implemented as macros, that
00053    will provide the function with the needed arguments.
00054 
00055    \param level   Type of log event
00056    \param file Will be provided by the AST_LOG_* macro
00057    \param line Will be provided by the AST_LOG_* macro
00058    \param function   Will be provided by the AST_LOG_* macro
00059    \param fmt  This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
00060  */
00061 
00062 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
00063    __attribute__((format(printf, 5, 6)));
00064 
00065 /*!
00066  * \brief Used for sending a log message with protection against recursion.
00067  *
00068  * \note This function should be used by all error messages that might be directly
00069  * or indirectly caused by logging.
00070  *
00071  * \see ast_log for documentation on the parameters.
00072  */
00073 void ast_log_safe(int level, const char *file, int line, const char *function, const char *fmt, ...)
00074    __attribute__((format(printf, 5, 6)));
00075 
00076 /* XXX needs documentation */
00077 typedef unsigned int ast_callid;
00078 
00079 /*! \brief Used for sending a log message with a known call_id
00080    This is a modified logger function which is functionally identical to the above logger function,
00081    it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
00082    join the log message with a call_id.
00083 
00084    \param level   Type of log event
00085    \param file Will be provided by the AST_LOG_* macro
00086    \param line Will be provided by the AST_LOG_* macro
00087    \param function   Will be provided by the AST_LOG_* macro
00088    \param callid  This is the ast_callid that is associated with the log message. May be NULL.
00089    \param fmt  This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
00090 */
00091 void ast_log_callid(int level, const char *file, int line, const char *function, ast_callid callid, const char *fmt, ...)
00092    __attribute__((format(printf, 6, 7)));
00093 
00094 /*!
00095  * \brief Log a backtrace of the current thread's execution stack to the Asterisk log
00096  */
00097 void ast_log_backtrace(void);
00098 
00099 /*! \brief Reload logger without rotating log files */
00100 int logger_reload(void);
00101 
00102 /*! \brief Reload logger while rotating log files */
00103 int ast_logger_rotate(void);
00104 
00105 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
00106 
00107 /*!
00108  * \brief Send a verbose message (based on verbose level)
00109  *
00110  * \details This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
00111  *
00112  * ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
00113  *
00114  * This will print the message to the console if the verbose level is set to a level >= 3
00115  *
00116  * Note the absence of a comma after the VERBOSE_PREFIX_3.  This is important.
00117  * VERBOSE_PREFIX_1 through VERBOSE_PREFIX_4 are defined.
00118  *
00119  * \version 11 added level parameter
00120  */
00121 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
00122 
00123 /*!
00124  * \brief Send a verbose message (based on verbose level) with deliberately specified callid
00125  *
00126  * \details just like __ast_verbose, only __ast_verbose_callid allows you to specify which callid is being used
00127  * for the log without needing to bind it to a thread. NULL is a valid argument for this function and will
00128  * allow you to specify that a log will never display a call id even when there is a call id bound to the
00129  * thread.
00130  */
00131 void __attribute__((format(printf, 6, 7))) __ast_verbose_callid(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt, ...);
00132 
00133 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, __VA_ARGS__)
00134 #define ast_verbose_callid(callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, callid, __VA_ARGS__)
00135 
00136 void __attribute__((format(printf, 6, 0))) __ast_verbose_ap(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt, va_list ap);
00137 
00138 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
00139 
00140 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
00141 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
00142 
00143 /*
00144  * These gymnastics are due to platforms which designate char as unsigned by
00145  * default.  Level is the negative character -- offset by 1, because \0 is
00146  * the string terminator.
00147  */
00148 #define VERBOSE_MAGIC2LEVEL(x) (((char) -*(signed char *) (x)) - 1)
00149 #define VERBOSE_HASMAGIC(x)   (*(signed char *) (x) < 0)
00150 
00151 void ast_console_puts(const char *string);
00152 
00153 /*!
00154  * \brief log the string to the console, and all attached
00155  * console clients
00156  * \version 1.6.1 added level parameter
00157  */
00158 void ast_console_puts_mutable(const char *string, int level);
00159 void ast_console_toggle_mute(int fd, int silent);
00160 
00161 /*!
00162  * \brief enables or disables logging of a specified level to the console
00163  * fd specifies the index of the console receiving the level change
00164  * level specifies the index of the logging level being toggled
00165  * state indicates whether logging will be on or off (0 for off, 1 for on)
00166  */
00167 void ast_console_toggle_loglevel(int fd, int level, int state);
00168 
00169 /* Note: The AST_LOG_* macros below are the same as
00170  * the LOG_* macros and are intended to eventually replace
00171  * the LOG_* macros to avoid name collisions with the syslog(3)
00172  * log levels. However, please do NOT remove
00173  * the LOG_* macros from the source since these may be still
00174  * needed for third-party modules
00175  */
00176 
00177 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
00178 
00179 #ifdef LOG_DEBUG
00180 #undef LOG_DEBUG
00181 #endif
00182 #define __LOG_DEBUG    0
00183 #define LOG_DEBUG      __LOG_DEBUG, _A_
00184 
00185 #ifdef AST_LOG_DEBUG
00186 #undef AST_LOG_DEBUG
00187 #endif
00188 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
00189 
00190 #ifdef LOG_NOTICE
00191 #undef LOG_NOTICE
00192 #endif
00193 #define __LOG_NOTICE   2
00194 #define LOG_NOTICE     __LOG_NOTICE, _A_
00195 
00196 #ifdef AST_LOG_NOTICE
00197 #undef AST_LOG_NOTICE
00198 #endif
00199 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
00200 
00201 #ifdef LOG_WARNING
00202 #undef LOG_WARNING
00203 #endif
00204 #define __LOG_WARNING  3
00205 #define LOG_WARNING    __LOG_WARNING, _A_
00206 
00207 #ifdef AST_LOG_WARNING
00208 #undef AST_LOG_WARNING
00209 #endif
00210 #define AST_LOG_WARNING    __LOG_WARNING, _A_
00211 
00212 #ifdef LOG_ERROR
00213 #undef LOG_ERROR
00214 #endif
00215 #define __LOG_ERROR    4
00216 #define LOG_ERROR      __LOG_ERROR, _A_
00217 
00218 #ifdef AST_LOG_ERROR
00219 #undef AST_LOG_ERROR
00220 #endif
00221 #define AST_LOG_ERROR      __LOG_ERROR, _A_
00222 
00223 #ifdef LOG_VERBOSE
00224 #undef LOG_VERBOSE
00225 #endif
00226 #define __LOG_VERBOSE  5
00227 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
00228 
00229 #ifdef AST_LOG_VERBOSE
00230 #undef AST_LOG_VERBOSE
00231 #endif
00232 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
00233 
00234 #ifdef LOG_DTMF
00235 #undef LOG_DTMF
00236 #endif
00237 #define __LOG_DTMF  6
00238 #define LOG_DTMF    __LOG_DTMF, _A_
00239 
00240 #ifdef AST_LOG_DTMF
00241 #undef AST_LOG_DTMF
00242 #endif
00243 #define AST_LOG_DTMF    __LOG_DTMF, _A_
00244 
00245 #define NUMLOGLEVELS 32
00246 
00247 /*!
00248  * \brief Get the debug level for a module
00249  * \param module the name of module
00250  * \return the debug level
00251  */
00252 unsigned int ast_debug_get_by_module(const char *module);
00253 
00254 /*!
00255  * \brief Get the verbose level for a module
00256  * \param module the name of module
00257  * \return the verbose level
00258  * \version 11.0.0 deprecated
00259  */
00260 unsigned int ast_verbose_get_by_module(const char *module) __attribute__((deprecated));
00261 
00262 /*!
00263  * \brief Register a new logger level
00264  * \param name The name of the level to be registered
00265  * \retval -1 if an error occurs
00266  * \retval non-zero level to be used with ast_log for sending messages to this level
00267  * \since 1.8
00268  */
00269 int ast_logger_register_level(const char *name);
00270 
00271 /*!
00272  * \brief Unregister a previously registered logger level
00273  * \param name The name of the level to be unregistered
00274  * \return nothing
00275  * \since 1.8
00276  */
00277 void ast_logger_unregister_level(const char *name);
00278 
00279 /*!
00280  * \brief Get the logger configured date format
00281  *
00282  * \retval The date format string
00283  *
00284  * \since 13.0.0
00285  */
00286 const char *ast_logger_get_dateformat(void);
00287 
00288 /*!
00289  * \brief factory function to create a new uniquely identifying callid.
00290  *
00291  * \retval The call id
00292  */
00293 ast_callid ast_create_callid(void);
00294 
00295 /*!
00296  * \brief extracts the callerid from the thread
00297  *
00298  * \retval Non-zero Call id related to the thread
00299  * \retval 0 if no call_id is present in the thread
00300  */
00301 ast_callid ast_read_threadstorage_callid(void);
00302 
00303 /*!
00304  * \brief Sets what is stored in the thread storage to the given
00305  *        callid if it does not match what is already there.
00306  *
00307  * \retval 0 - success
00308  * \retval non-zero - failure
00309  */
00310 int ast_callid_threadassoc_change(ast_callid callid);
00311 
00312 /*!
00313  * \brief Adds a known callid to thread storage of the calling thread
00314  *
00315  * \retval 0 - success
00316  * \retval non-zero - failure
00317  */
00318 int ast_callid_threadassoc_add(ast_callid callid);
00319 
00320 /*!
00321  * \brief Removes callid from thread storage of the calling thread
00322  *
00323  * \retval 0 - success
00324  * \retval non-zero - failure
00325  */
00326 int ast_callid_threadassoc_remove(void);
00327 
00328 /*!
00329  * \brief Checks thread storage for a callid and stores a reference if it exists.
00330  *        If not, then a new one will be created, bound to the thread, and a reference
00331  *        to it will be stored.
00332  *
00333  * \param callid pointer to store the callid
00334  * \retval 0 - callid was found
00335  * \retval 1 - callid was created
00336  * \retval -1 - the function failed somehow (presumably memory problems)
00337  */
00338 int ast_callid_threadstorage_auto(ast_callid *callid);
00339 
00340 /*!
00341  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
00342  *        references and if the callid was created by threadstorage_auto, unbinds
00343  *        the callid from the threadstorage
00344  * \param callid The callid set by ast_callid_threadstorage_auto
00345  * \param callid_created The integer returned through ast_callid_threadstorage_auto
00346  */
00347 void ast_callid_threadstorage_auto_clean(ast_callid callid, int callid_created);
00348 
00349 /*!
00350  * \brief copy a string representation of the callid into a target string
00351  *
00352  * \param buffer destination of callid string (should be able to store 13 characters or more)
00353  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
00354  * \param callid Callid for which string is being requested
00355  */
00356 void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid);
00357 
00358 /*!
00359  * \brief Send a log message to a dynamically registered log level
00360  * \param level The log level to send the message to
00361  *
00362  * Like ast_log, the log message may include printf-style formats, and
00363  * the data for these must be provided as additional parameters after
00364  * the log message.
00365  *
00366  * \return nothing
00367  * \since 1.8
00368  */
00369 
00370 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
00371 
00372 #define DEBUG_ATLEAST(level) \
00373    (option_debug >= (level) \
00374       || (ast_opt_dbg_module && (int)ast_debug_get_by_module(AST_MODULE) >= (level)))
00375 
00376 /*!
00377  * \brief Log a DEBUG message
00378  * \param level The minimum value of option_debug for this message
00379  *        to get logged
00380  */
00381 #define ast_debug(level, ...) \
00382    do { \
00383       if (DEBUG_ATLEAST(level)) { \
00384          ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
00385       } \
00386    } while (0)
00387 
00388 extern int ast_verb_sys_level;
00389 
00390 #define VERBOSITY_ATLEAST(level) ((level) <= ast_verb_sys_level)
00391 
00392 #define ast_verb(level, ...) \
00393    do { \
00394       if (VERBOSITY_ATLEAST(level) ) { \
00395          __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__); \
00396       } \
00397    } while (0)
00398 
00399 #define ast_verb_callid(level, callid, ...) \
00400    do { \
00401       if (VERBOSITY_ATLEAST(level) ) { \
00402          __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, callid, __VA_ARGS__); \
00403       } \
00404    } while (0)
00405 
00406 /*!
00407  * \brief Re-evaluate the system max verbosity level (ast_verb_sys_level).
00408  *
00409  * \return Nothing
00410  */
00411 void ast_verb_update(void);
00412 
00413 /*!
00414  * \brief Register this thread's console verbosity level pointer.
00415  *
00416  * \param level Where the verbose level value is.
00417  *
00418  * \return Nothing
00419  */
00420 void ast_verb_console_register(int *level);
00421 
00422 /*!
00423  * \brief Unregister this thread's console verbosity level.
00424  *
00425  * \return Nothing
00426  */
00427 void ast_verb_console_unregister(void);
00428 
00429 /*!
00430  * \brief Get this thread's console verbosity level.
00431  *
00432  * \retval verbosity level of the console.
00433  */
00434 int ast_verb_console_get(void);
00435 
00436 /*!
00437  * \brief Set this thread's console verbosity level.
00438  *
00439  * \param verb_level New level to set.
00440  *
00441  * \return Nothing
00442  */
00443 void ast_verb_console_set(int verb_level);
00444 
00445 #if defined(__cplusplus) || defined(c_plusplus)
00446 }
00447 #endif
00448 
00449 #endif /* _ASTERISK_LOGGER_H */

Generated on Thu Apr 16 06:27:38 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6