2 * @file Common/ilogger.h
3 * @brief Logger interface for eVaf
6 * Copyright (c) 2011 Enar Vaikene
8 * This file is part of the eVaf C++ cross-platform application development framework.
10 * This file can be used under the terms of the GNU General Public License
11 * version 3.0 as published by the Free Software Foundation and appearing in
12 * the file LICENSE included in the packaging of this file. Please review the
13 * the following information to ensure the GNU General Public License version
14 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
16 * Alternatively, this file may be used in accordance with the Commercial License
17 * Agreement provided with the Software.
20 #ifndef __COMMON_ILOGGER_H
21 # define __COMMON_ILOGGER_H
23 #include "libcommon.h"
34 * Prototype for custom fatal message handler.
36 * This is a typedef for a pointer to a function with the following signature:
38 * void myFatalMessageHandler(QString const & msg, QString const & source, QString const & where);
41 * @sa iLogger::installFatalMsgHandler()
43 typedef void (*FatalMsgHandler
)(QString
const & msg
, QString
const & source
, QString
const & where
);
46 * Logger interface for eVaf modules and applications.
47 * @code#include <Common/iLogger>@endcode
50 class COMMON_EXPORT iLogger
: public QObject
57 * Severity levels for messages indicating the meaning and seriousness of the message.
60 None
= 0, ///< For disabling logging completely (to be not used with messages).
61 Fatal
, ///< Fatal error that causes the application to stop functioning.
62 Error
, ///< Unexpected issues in the software that could be solved automatically.
63 Warning
, ///< Expected issues in the software that will be solved automatically.
64 Info
, ///< General information output by the application or modules.
65 Debug
, ///< Information for debugging purposes.
66 Count
///< Number of severity levels
69 /// Interface constructor
70 iLogger() : QObject() {}
72 /// Empty virtual destructor
76 * Returns the iLogger interface instance.
77 * @return The iLogger interface
79 * The instance() function returns the global iLogger interface instance. As all the modules and applications
80 * are expected to be linked against the Common library, then this is the preferred method of obtaining
81 * the iLogger interface. The other method is by using the iRegistry interface.
83 static iLogger
* instance();
86 * Returns the current default source name.
88 virtual QString
defaultSource() const = 0;
91 * Sets the default source.
92 * @param source The new default source name.
94 * Use the setDefaultSource() function to change the default source name. If not set, then
95 * uses the default source name "common".
97 virtual void setDefaultSource(QString
const & source
) = 0;
100 * Returns the current severity level
101 * @param source Name of the source or default if omitted.
103 virtual Severity
severity(QString
const & source
= 0) = 0;
106 * Changes the current severity level.
107 * @param severity The new severity level
108 * @param source Name of the source or default if omitted.
110 * This function changes the severity level of the given logger source. By default, only fatal errors
111 * are output. With this function the severity level can be changed so that also less important
112 * messages are output.
114 virtual void setSeverity(Severity severity
, QString
const & source
= 0) = 0;
117 * Returns the current maximum size of log files in KiB.
118 * @param source Name of the source or default if omitted.
120 virtual uint
maxSize(QString
const & source
= 0) = 0;
123 * Changes the maximum size of log files for the given source
124 * @param maxSize The new maximum size in KiB
125 * @param source Name of the source of default if omitted.
127 * This function changes the maximum size of log files. Log files larger than this value
128 * will be renamed to backup files.
130 * The default value for all the sources is usually 100 KiB.
132 * Set the maximum size to 0 for no limits (dangerous!).
134 virtual void setMaxSize(uint maxSize
, QString
const & source
= 0) = 0;
137 * Returns the maximum number of log files.
138 * @param source Name of the source or default if omitted.
140 virtual uint
maxCount(QString
const & source
= 0) = 0;
143 * Changes the maximum number of log files
144 * @param maxCount The new maximum number
145 * @param source Name of the source or default if omitted
147 * This function sets the maximum number of log files including the current log file
148 * and any backup files. Older backup files are deleted to keep the number of log
149 * files at the maximum.
151 * The default value for all the sources is usually 3 (the current log file plus 2
154 * Set the maximum number of log files to 0 for no limits (dangerous!).
156 virtual void setMaxCount(uint maxCount
, QString
const & source
= 0) = 0;
159 * Returns the current console severity level.
161 virtual Severity
consoleSeverity() const = 0;
164 * Changes the console severity level.
165 * @param severity The new console severity level
167 * This function changes the console severity level. By default, only fatal errors are output to
170 virtual void setConsoleSeverity(Severity severity
) = 0;
174 * @param severity Severity of the message, ie how important it is.
175 * @param msg The message to be output
176 * @param source Source of the message or default if omitted.
177 * @param where Location in the source file where the message was output.
179 * This function writes a message to the log file if the severity is high enough. If the
180 * severity is lower than the current severity level, then does nothing.
182 * If the source parameter is given, then uses the specified source. Otherwise writes
183 * to the default log file.
185 * The where parameter can be used to indicate the location in the source file where
186 * the message was generated.
188 * Messages for the default source are also output to the console if the console severity
189 * level is high enough.
191 virtual void write(Severity severity
, QString
const & msg
, QString
const & source
= 0, QString
const & where
= 0) = 0;
194 * Helper function for formatting messages using the standard printf() function.
195 * @param fmt The format string
196 * @param ... Variable number of arguments
197 * @return The formatted string
199 virtual QString
printf(char const * const fmt
, ...) const
201 __attribute__((format(printf
, 2, 3)))
206 * Replaces non-printable characters in the input string with human-readable strings.
207 * @param msg The input string
208 * @return Human-readable string
210 * This function replaces all the non-printable characters with human-readable strings, like
211 * ASCII symbol names or HEX codes.
213 * For example, the Line Feed character will be replaced with "[LF]".
215 virtual QString
printable(QByteArray
const & msg
) const = 0;
218 * Installs a fatal error message handler.
219 * @param newHandler The new fatal error message handler
220 * @return The old fatal error message handler
222 * This function installs a custom fatal error message handler. The custom fatal error message
223 * handler is responsible for giving feedback to the user and terminating the application.
225 * The default fatal error message handler outputs the message to stderr and terminates the
228 virtual FatalMsgHandler
installFatalMsgHandler(FatalMsgHandler newHandler
) = 0;
234 * Logger event signal
235 * @param severity Severity of the message
236 * @param text The message
237 * @param source Source of the message
238 * @param where Where the message was output
240 * This signal is emitted for every message output with the iLogger interface. Connect
241 * your receiver to this signal if you want to add your own message handling. For example,
242 * use this signal to show messages in a log window etc.
244 void loggerEvent(eVaf::Common::iLogger::Severity severity
, QString
const & text
, QString
const & source
, QString
const & where
);
248 } // namespace eVaf::Common
252 * Outputs info messages
253 * @param msg The format string
254 * @param ... Variable list of arguments
256 * The qInfo() function adds info messages to the Qt family of functions qDebug(), qWarning(), qError() and qFatal().
258 void COMMON_EXPORT
qInfo(char const * const msg
, ...)
260 __attribute__((format(printf
, 1, 2)))
265 * Macro for fatal error messages.
267 * This macro expands to a fatal error message output with the location in the source code where the error
270 #define EVAF_FATAL_ERROR(...) \
272 eVaf::Common::iLogger::instance()->write( \
273 eVaf::Common::iLogger::Fatal, \
274 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
276 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
281 * Macro for error messages.
283 * This macro expands to an error message output with the location in the source code where the error
286 #define EVAF_ERROR(...) \
288 eVaf::Common::iLogger::instance()->write( \
289 eVaf::Common::iLogger::Error, \
290 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
292 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
297 * Macro for warning messages.
299 * This macro expands to a warning message output with the location in the source code where the warning
302 #define EVAF_WARNING(...) \
304 eVaf::Common::iLogger::instance()->write( \
305 eVaf::Common::iLogger::Warning, \
306 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
308 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
313 * Macro for info messages.
315 * This macro expands to an info message output with the location in the source code where the message
318 #define EVAF_INFO(...) \
320 eVaf::Common::iLogger::instance()->write( \
321 eVaf::Common::iLogger::Info, \
322 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
324 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
329 * Macro for debug messages.
331 * This macro expands to a debug message output with the location in the source code where the message
332 * is output. All the debug messages are supressed when the NDEBUG directive is defined.
335 # define EVAF_DEBUG(...) \
337 eVaf::Common::iLogger::instance()->write( \
338 eVaf::Common::iLogger::Debug, \
339 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
341 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
345 # define EVAF_DEBUG(...) \