diff options
Diffstat (limited to 'pjlib/include/pj/log.h')
-rw-r--r-- | pjlib/include/pj/log.h | 633 |
1 files changed, 327 insertions, 306 deletions
diff --git a/pjlib/include/pj/log.h b/pjlib/include/pj/log.h index 5dfe17c1..6e89d72b 100644 --- a/pjlib/include/pj/log.h +++ b/pjlib/include/pj/log.h @@ -1,306 +1,327 @@ -/* $Id$ - * - */ - -#ifndef __PJ_LOG_H__ -#define __PJ_LOG_H__ - -/** - * @file log.h - * @brief Logging Utility. - */ - -#include <pj/types.h> - - -PJ_BEGIN_DECL - -/** - * @defgroup PJ_MISC Miscelaneous - * @ingroup PJ - */ - -/** - * @defgroup PJ_LOG Logging Facility - * @ingroup PJ_MISC - * @{ - * - * The PJLIB logging facility is a configurable, flexible, and convenient - * way to write logging or trace information. - * - * To write to the log, one uses construct like below: - * - * <pre> - * ... - * PJ_LOG(3, ("main.c", "Starting hello...")); - * ... - * PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid())); - * ... - * </pre> - * - * In the above example, the number @b 3 controls the verbosity level of - * the information (which means "information", by convention). The string - * "main.c" specifies the source or sender of the message. - * - * - * \section pj_log_quick_sample_sec Examples - * - * For examples, see: - * - @ref page_pjlib_samples_log_c. - * - */ - -/** - * Log decoration flag, to be specified with #pj_log_set_decor(). - */ -enum pj_log_decoration -{ - PJ_LOG_HAS_DAY_NAME = 1, /**< Include day name [default: no]. */ - PJ_LOG_HAS_YEAR = 2, /**< Include year digit [default: no] */ - PJ_LOG_HAS_MONTH = 4, /**< Include month [default: no] */ - PJ_LOG_HAS_DAY_OF_MON = 8, /**< Include day of month [default: no] */ - PJ_LOG_HAS_TIME = 16, /**< Include time [default: yes]. */ - PJ_LOG_HAS_MICRO_SEC = 32, /**< Include microseconds [yes] */ - PJ_LOG_HAS_SENDER = 64, /**< Include sender in the log [yes]. */ - PJ_LOG_HAS_NEWLINE = 128, /**< Terminate each call with newline [yes].*/ -}; - -/** - * Write log message. - * This is the main macro used to write text to the logging backend. - * - * @param level The logging verbosity level. Lower number indicates higher - * importance, with level zero indicates fatal error. Only - * numeral argument is permitted (e.g. not variable). - * @param arg Enclosed 'printf' like arguments, with the first - * argument is the sender, the second argument is format - * string and the following arguments are variable number of - * arguments suitable for the format string. - * - * Sample: - * \verbatim - PJ_LOG(2, (__FILE__, "current value is %d", value)); - \endverbatim - * @hideinitializer - */ -#define PJ_LOG(level,arg) pj_log_wrapper_##level(arg) - -/** - * Signature for function to be registered to the logging subsystem to - * write the actual log message to some output device. - * - * @param level Log level. - * @param data Log message. - * @param len Message length. - */ -typedef void pj_log_func(int level, const char *data, int len); - -/** - * Default logging writer function used by front end logger function. - * Application normally should NOT need to call this function, but - * rather use the PJ_LOG macro. - * - * @param level Log level. - * @param buffer Log message. - * @param len Message length. - */ -PJ_DECL(void) pj_log_write(int level, const char *buffer, int len); - - -#if PJ_LOG_MAX_LEVEL >= 1 - -/** - * Change log output function. The front-end logging functions will call - * this function to write the actual message to the desired device. - * By default, the front-end functions use pj_log_write() to write - * the messages, unless it's changed by calling this function. - * - * @param func The function that will be called to write the log - * messages to the desired device. - */ -PJ_DECL(void) pj_log_set_log_func( pj_log_func *func ); - -/** - * Get the current log output function that is used to write log messages. - * - * @return Current log output function. - */ -PJ_DECL(pj_log_func*) pj_log_get_log_func(void); - -/** - * Set maximum log level. Application can call this function to set - * the desired level of verbosity of the logging messages. The bigger the - * value, the more verbose the logging messages will be printed. However, - * the maximum level of verbosity can not exceed compile time value of - * PJ_LOG_MAX_LEVEL. - * - * @param level The maximum level of verbosity of the logging - * messages (6=very detailed..1=error only, 0=disabled) - */ -PJ_DECL(void) pj_log_set_level(int level); - -/** - * Get current maximum log verbositylevel. - * - * @return Current log maximum level. - */ -PJ_DECL(int) pj_log_get_level(void); - -/** - * Set log decoration. The log decoration flag controls what are printed - * to output device alongside the actual message. For example, application - * can specify that date/time information should be displayed with each - * log message. - * - * @param decor Bitmask combination of #pj_log_decoration to control - * the layout of the log message. - */ -PJ_DECL(void) pj_log_set_decor(unsigned decor); - -/** - * Get current log decoration flag. - * - * @return Log decoration flag. - */ -PJ_DECL(unsigned) pj_log_get_decor(void); - - -#else /* #if PJ_LOG_MAX_LEVEL >= 1 */ - -/** - * Change log output function. The front-end logging functions will call - * this function to write the actual message to the desired device. - * By default, the front-end functions use pj_log_write() to write - * the messages, unless it's changed by calling this function. - * - * @param func The function that will be called to write the log - * messages to the desired device. - */ -# define pj_log_set_log_func(func) - -/** - * Set maximum log level. Application can call this function to set - * the desired level of verbosity of the logging messages. The bigger the - * value, the more verbose the logging messages will be printed. However, - * the maximum level of verbosity can not exceed compile time value of - * PJ_LOG_MAX_LEVEL. - * - * @param level The maximum level of verbosity of the logging - * messages (6=very detailed..1=error only, 0=disabled) - */ -# define pj_log_set_level(level) - -/** - * Set log decoration. The log decoration flag controls what are printed - * to output device alongside the actual message. For example, application - * can specify that date/time information should be displayed with each - * log message. - * - * @param decor Bitmask combination of #pj_log_decoration to control - * the layout of the log message. - */ -# define pj_log_set_decor(decor) - -#endif /* #if PJ_LOG_MAX_LEVEL >= 1 */ - -/** - * @} - */ - -/////////////////////////////////////////////////////////////////////////////// -/* - * Log functions implementation prototypes. - * These functions are called by PJ_LOG macros according to verbosity - * level specified when calling the macro. Applications should not normally - * need to call these functions directly. - */ - -/** - * @def pj_log_wrapper_1(arg) - * Internal function to write log with verbosity 1. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 1. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 1 - #define pj_log_wrapper_1(arg) pj_log_1 arg - /** Internal function. */ - PJ_DECL(void) pj_log_1(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_1(arg) -#endif - -/** - * @def pj_log_wrapper_2(arg) - * Internal function to write log with verbosity 2. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 2. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 2 - #define pj_log_wrapper_2(arg) pj_log_2 arg - /** Internal function. */ - PJ_DECL(void) pj_log_2(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_2(arg) -#endif - -/** - * @def pj_log_wrapper_3(arg) - * Internal function to write log with verbosity 3. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 3. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 3 - #define pj_log_wrapper_3(arg) pj_log_3 arg - /** Internal function. */ - PJ_DECL(void) pj_log_3(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_3(arg) -#endif - -/** - * @def pj_log_wrapper_4(arg) - * Internal function to write log with verbosity 4. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 4. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 4 - #define pj_log_wrapper_4(arg) pj_log_4 arg - /** Internal function. */ - PJ_DECL(void) pj_log_4(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_4(arg) -#endif - -/** - * @def pj_log_wrapper_5(arg) - * Internal function to write log with verbosity 5. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 5. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 5 - #define pj_log_wrapper_5(arg) pj_log_5 arg - /** Internal function. */ - PJ_DECL(void) pj_log_5(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_5(arg) -#endif - -/** - * @def pj_log_wrapper_6(arg) - * Internal function to write log with verbosity 6. Will evaluate to - * empty expression if PJ_LOG_MAX_LEVEL is below 6. - * @param arg Log expression. - */ -#if PJ_LOG_MAX_LEVEL >= 6 - #define pj_log_wrapper_6(arg) pj_log_6 arg - /** Internal function. */ - PJ_DECL(void) pj_log_6(const char *src, const char *format, ...); -#else - #define pj_log_wrapper_6(arg) -#endif - - -PJ_END_DECL - -#endif /* __PJ_LOG_H__ */ - +/* $Id$
+ *
+ */
+/*
+ * PJLIB - PJ Foundation Library
+ * (C)2003-2005 Benny Prijono <bennylp@bulukucing.org>
+ *
+ * Author:
+ * Benny Prijono <bennylp@bulukucing.org>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#ifndef __PJ_LOG_H__
+#define __PJ_LOG_H__
+
+/**
+ * @file log.h
+ * @brief Logging Utility.
+ */
+
+#include <pj/types.h>
+
+
+PJ_BEGIN_DECL
+
+/**
+ * @defgroup PJ_MISC Miscelaneous
+ * @ingroup PJ
+ */
+
+/**
+ * @defgroup PJ_LOG Logging Facility
+ * @ingroup PJ_MISC
+ * @{
+ *
+ * The PJLIB logging facility is a configurable, flexible, and convenient
+ * way to write logging or trace information.
+ *
+ * To write to the log, one uses construct like below:
+ *
+ * <pre>
+ * ...
+ * PJ_LOG(3, ("main.c", "Starting hello..."));
+ * ...
+ * PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid()));
+ * ...
+ * </pre>
+ *
+ * In the above example, the number @b 3 controls the verbosity level of
+ * the information (which means "information", by convention). The string
+ * "main.c" specifies the source or sender of the message.
+ *
+ *
+ * \section pj_log_quick_sample_sec Examples
+ *
+ * For examples, see:
+ * - @ref page_pjlib_samples_log_c.
+ *
+ */
+
+/**
+ * Log decoration flag, to be specified with #pj_log_set_decor().
+ */
+enum pj_log_decoration
+{
+ PJ_LOG_HAS_DAY_NAME = 1, /**< Include day name [default: no]. */
+ PJ_LOG_HAS_YEAR = 2, /**< Include year digit [default: no] */
+ PJ_LOG_HAS_MONTH = 4, /**< Include month [default: no] */
+ PJ_LOG_HAS_DAY_OF_MON = 8, /**< Include day of month [default: no] */
+ PJ_LOG_HAS_TIME = 16, /**< Include time [default: yes]. */
+ PJ_LOG_HAS_MICRO_SEC = 32, /**< Include microseconds [yes] */
+ PJ_LOG_HAS_SENDER = 64, /**< Include sender in the log [yes]. */
+ PJ_LOG_HAS_NEWLINE = 128, /**< Terminate each call with newline [yes].*/
+};
+
+/**
+ * Write log message.
+ * This is the main macro used to write text to the logging backend.
+ *
+ * @param level The logging verbosity level. Lower number indicates higher
+ * importance, with level zero indicates fatal error. Only
+ * numeral argument is permitted (e.g. not variable).
+ * @param arg Enclosed 'printf' like arguments, with the first
+ * argument is the sender, the second argument is format
+ * string and the following arguments are variable number of
+ * arguments suitable for the format string.
+ *
+ * Sample:
+ * \verbatim
+ PJ_LOG(2, (__FILE__, "current value is %d", value));
+ \endverbatim
+ * @hideinitializer
+ */
+#define PJ_LOG(level,arg) pj_log_wrapper_##level(arg)
+
+/**
+ * Signature for function to be registered to the logging subsystem to
+ * write the actual log message to some output device.
+ *
+ * @param level Log level.
+ * @param data Log message.
+ * @param len Message length.
+ */
+typedef void pj_log_func(int level, const char *data, int len);
+
+/**
+ * Default logging writer function used by front end logger function.
+ * Application normally should NOT need to call this function, but
+ * rather use the PJ_LOG macro.
+ *
+ * @param level Log level.
+ * @param buffer Log message.
+ * @param len Message length.
+ */
+PJ_DECL(void) pj_log_write(int level, const char *buffer, int len);
+
+
+#if PJ_LOG_MAX_LEVEL >= 1
+
+/**
+ * Change log output function. The front-end logging functions will call
+ * this function to write the actual message to the desired device.
+ * By default, the front-end functions use pj_log_write() to write
+ * the messages, unless it's changed by calling this function.
+ *
+ * @param func The function that will be called to write the log
+ * messages to the desired device.
+ */
+PJ_DECL(void) pj_log_set_log_func( pj_log_func *func );
+
+/**
+ * Get the current log output function that is used to write log messages.
+ *
+ * @return Current log output function.
+ */
+PJ_DECL(pj_log_func*) pj_log_get_log_func(void);
+
+/**
+ * Set maximum log level. Application can call this function to set
+ * the desired level of verbosity of the logging messages. The bigger the
+ * value, the more verbose the logging messages will be printed. However,
+ * the maximum level of verbosity can not exceed compile time value of
+ * PJ_LOG_MAX_LEVEL.
+ *
+ * @param level The maximum level of verbosity of the logging
+ * messages (6=very detailed..1=error only, 0=disabled)
+ */
+PJ_DECL(void) pj_log_set_level(int level);
+
+/**
+ * Get current maximum log verbositylevel.
+ *
+ * @return Current log maximum level.
+ */
+PJ_DECL(int) pj_log_get_level(void);
+
+/**
+ * Set log decoration. The log decoration flag controls what are printed
+ * to output device alongside the actual message. For example, application
+ * can specify that date/time information should be displayed with each
+ * log message.
+ *
+ * @param decor Bitmask combination of #pj_log_decoration to control
+ * the layout of the log message.
+ */
+PJ_DECL(void) pj_log_set_decor(unsigned decor);
+
+/**
+ * Get current log decoration flag.
+ *
+ * @return Log decoration flag.
+ */
+PJ_DECL(unsigned) pj_log_get_decor(void);
+
+
+#else /* #if PJ_LOG_MAX_LEVEL >= 1 */
+
+/**
+ * Change log output function. The front-end logging functions will call
+ * this function to write the actual message to the desired device.
+ * By default, the front-end functions use pj_log_write() to write
+ * the messages, unless it's changed by calling this function.
+ *
+ * @param func The function that will be called to write the log
+ * messages to the desired device.
+ */
+# define pj_log_set_log_func(func)
+
+/**
+ * Set maximum log level. Application can call this function to set
+ * the desired level of verbosity of the logging messages. The bigger the
+ * value, the more verbose the logging messages will be printed. However,
+ * the maximum level of verbosity can not exceed compile time value of
+ * PJ_LOG_MAX_LEVEL.
+ *
+ * @param level The maximum level of verbosity of the logging
+ * messages (6=very detailed..1=error only, 0=disabled)
+ */
+# define pj_log_set_level(level)
+
+/**
+ * Set log decoration. The log decoration flag controls what are printed
+ * to output device alongside the actual message. For example, application
+ * can specify that date/time information should be displayed with each
+ * log message.
+ *
+ * @param decor Bitmask combination of #pj_log_decoration to control
+ * the layout of the log message.
+ */
+# define pj_log_set_decor(decor)
+
+#endif /* #if PJ_LOG_MAX_LEVEL >= 1 */
+
+/**
+ * @}
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+/*
+ * Log functions implementation prototypes.
+ * These functions are called by PJ_LOG macros according to verbosity
+ * level specified when calling the macro. Applications should not normally
+ * need to call these functions directly.
+ */
+
+/**
+ * @def pj_log_wrapper_1(arg)
+ * Internal function to write log with verbosity 1. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 1.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 1
+ #define pj_log_wrapper_1(arg) pj_log_1 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_1(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_1(arg)
+#endif
+
+/**
+ * @def pj_log_wrapper_2(arg)
+ * Internal function to write log with verbosity 2. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 2.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 2
+ #define pj_log_wrapper_2(arg) pj_log_2 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_2(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_2(arg)
+#endif
+
+/**
+ * @def pj_log_wrapper_3(arg)
+ * Internal function to write log with verbosity 3. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 3.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 3
+ #define pj_log_wrapper_3(arg) pj_log_3 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_3(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_3(arg)
+#endif
+
+/**
+ * @def pj_log_wrapper_4(arg)
+ * Internal function to write log with verbosity 4. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 4.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 4
+ #define pj_log_wrapper_4(arg) pj_log_4 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_4(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_4(arg)
+#endif
+
+/**
+ * @def pj_log_wrapper_5(arg)
+ * Internal function to write log with verbosity 5. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 5.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 5
+ #define pj_log_wrapper_5(arg) pj_log_5 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_5(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_5(arg)
+#endif
+
+/**
+ * @def pj_log_wrapper_6(arg)
+ * Internal function to write log with verbosity 6. Will evaluate to
+ * empty expression if PJ_LOG_MAX_LEVEL is below 6.
+ * @param arg Log expression.
+ */
+#if PJ_LOG_MAX_LEVEL >= 6
+ #define pj_log_wrapper_6(arg) pj_log_6 arg
+ /** Internal function. */
+ PJ_DECL(void) pj_log_6(const char *src, const char *format, ...);
+#else
+ #define pj_log_wrapper_6(arg)
+#endif
+
+
+PJ_END_DECL
+
+#endif /* __PJ_LOG_H__ */
+
|