1 /***************************************************************** 2 * gmerlin - a general purpose multimedia framework and applications 3 * 4 * Copyright (c) 2001 - 2011 Members of the Gmerlin project 5 * gmerlin-general@lists.sourceforge.net 6 * http://gmerlin.sourceforge.net 7 * 8 * This program is free software: you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation, either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program. If not, see <http://www.gnu.org/licenses/>. 20 * *****************************************************************/ 21 22 #ifndef __BG_LOG_H_ 23 #define __BG_LOG_H_ 24 25 /* Gmerlin log facilities */ 26 27 #include <gmerlin/parameter.h> 28 #include <gmerlin/msgqueue.h> 29 30 #include <libintl.h> 31 32 /** \defgroup log Logging 33 * \brief Global logging facilities 34 * 35 * The logging mechanism is used for everything, 36 * which would be done with fprintf(stderr, ...) in 37 * simpler applications. It is the only mechanism, which 38 * used global variables, i.e. the functions \ref bg_log_set_dest 39 * and \ref bg_log_set_verbose. They should be called just once during 40 * application startup. The function \ref bg_log can, of course, be 41 * called from multiple threads simultaneously. 42 */ 43 44 /** \ingroup log 45 * \brief Log levels 46 * 47 * These specify the type and severity of a message. They can also be 48 * ORed for a call to \ref bg_log_set_verbose. 49 **/ 50 51 typedef enum 52 { 53 BG_LOG_DEBUG = 1<<0, //!< Only for programmers, useless for users 54 BG_LOG_WARNING = 1<<1, //!< Something went wrong, but is not fatal 55 BG_LOG_ERROR = 1<<2, //!< Something went wrong, cannot continue 56 BG_LOG_INFO = 1<<3 //!< Something interesting the user might want to know 57 } bg_log_level_t; 58 59 #define BG_LOG_LEVEL_MAX (1<<3) 60 61 /** \ingroup log 62 * \brief Send a message to the logger without translating it. 63 * \param level Level 64 * \param domain The name of the volume 65 * \param format Format like for printf 66 * 67 * All other arguments must match the format string. 68 * 69 * This function either prints a message to stderr (if you didn't case 70 * \ref bg_log_set_dest and level is contained in the mask you passed to 71 * bg_log_set_verbose) or puts a message into the queue you passed to 72 * bg_log_set_dest. 73 **/ 74 75 void bg_log_notranslate(bg_log_level_t level, const char * domain, 76 const char * format, ...) __attribute__ ((format (printf, 3, 4))); 77 78 /** \ingroup log 79 * \brief Send a message (as complete string) to the logger without translating it. 80 * \param level Level 81 * \param domain The name of the volume 82 * \param str Message string 83 * 84 * All other arguments must match the format string. 85 * 86 * This function either prints a message to stderr (if you didn't case 87 * \ref bg_log_set_dest and level is contained in the mask you passed to 88 * bg_log_set_verbose) or puts a message into the queue you passed to 89 * bg_log_set_dest. 90 **/ 91 92 void bg_logs_notranslate(bg_log_level_t level, const char * domain, 93 const char * str); 94 95 96 97 /** \ingroup log 98 * \brief Translate a message and send it to the logger. 99 * \param translation_domain Gettext domain (usually package name) 100 * \param level Level 101 * \param domain The name of the volume 102 * \param format Format like for printf 103 * 104 * All other arguments must match the format string. 105 * 106 * This function either prints a message to stderr (if you didn't case 107 * \ref bg_log_set_dest and level is contained in the mask you passed to 108 * bg_log_set_verbose) or puts a message into the queue you passed to 109 * bg_log_set_dest. 110 **/ 111 112 void bg_log_translate(const char * translation_domain, 113 bg_log_level_t level, const char * domain, 114 const char * format, ...) __attribute__ ((format (printf, 4, 5))); 115 116 /** \ingroup log 117 * \brief Translate a message and send it to the logger 118 */ 119 120 #define bg_log(level, domain, ...) \ 121 bg_log_translate(PACKAGE, level, domain, __VA_ARGS__) 122 123 124 /** \ingroup log 125 * \brief Set the log destination 126 * \param q Message queue 127 * 128 * This sets a global message queue to which log messages will be sent. 129 * The format of the logging messages is simple: The message id is equal 130 * to the log level (see \ref bg_msg_get_id). 131 * The first two arguments are strings for the domain and the actual message 132 * respectively (see \ref bg_msg_get_arg_string). 133 * 134 * Note, that logging will become asynchronous with this method. Also, single threaded 135 * applications always must remember to handle messages from the log queue 136 * after they did something critical. 137 */ 138 139 void bg_log_set_dest(bg_msg_queue_t * q); 140 141 /** \ingroup log 142 * \brief Convert a log level to a human readable string 143 * \param level Log level 144 * \returns A human readable string describing the log level 145 */ 146 147 const char * bg_log_level_to_string(bg_log_level_t level); 148 149 /** \ingroup log 150 * \brief Set verbosity mask 151 * \param mask ORed log levels, which should be printed 152 * 153 * Note, that this function is not thread save and has no effect 154 * if logging is done with a message queue. 155 */ 156 157 void bg_log_set_verbose(int mask); 158 159 /** \ingroup log 160 * \brief Get last error message 161 * \returns The last error message, must be freed 162 * 163 * Use this only if you didn't set an log destination and you 164 * can make sure, that only your thread can trigger an error. 165 */ 166 167 char * bg_log_last_error(); 168 169 /** \ingroup log 170 * \brief Initialize syslog logging 171 * \param name Application name 172 */ 173 174 void bg_log_syslog_init(const char * name); 175 176 /** \ingroup log 177 * Flush the log queue, must be done periodically by the 178 * application 179 */ 180 181 void bg_log_syslog_flush(); 182 183 184 185 #endif // __BG_LOG_H_ 186