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.
68 /// Interface constructor
69 iLogger() : QObject() {}
71 /// Empty virtual destructor
75 * Returns the iLogger interface instance.
76 * @return The iLogger interface
78 * The instance() function returns the global iLogger interface instance. As all the modules and applications
79 * are expected to be linked against the Common library, then this is the preferred method of obtaining
80 * the iLogger interface. The other method is by using the iRegistry interface.
82 static iLogger
* instance();
85 * Returns the current default source name.
87 virtual QString
defaultSource() const = 0;
90 * Sets the default source.
91 * @param source The new default source name.
93 * Use the setDefaultSource() function to change the default source name. If not set, then
94 * uses the default source name "common".
96 virtual void setDefaultSource(QString
const & source
) = 0;
99 * Returns the current severity level
100 * @param source Name of the source or default if omitted.
102 virtual Severity
severity(QString
const & source
= 0) = 0;
105 * Changes the current severity level.
106 * @param severity The new severity level
107 * @param source Name of the source or default if omitted.
109 * This function changes the severity level of the given logger source. By default, only fatal errors
110 * are output. With this function the severity level can be changed so that also less important
111 * messages are output.
113 virtual void setSeverity(Severity severity
, QString
const & source
= 0) = 0;
116 * Returns the current maximum size of log files in KiB.
117 * @param source Name of the source or default if omitted.
119 virtual uint
maxSize(QString
const & source
= 0) = 0;
122 * Changes the maximum size of log files for the given source
123 * @param maxSize The new maximum size in KiB
124 * @param source Name of the source of default if omitted.
126 * This function changes the maximum size of log files. Log files larger than this value
127 * will be renamed to backup files.
129 * The default value for all the sources is usually 100 KiB.
131 * Set the maximum size to 0 for no limits (dangerous!).
133 virtual void setMaxSize(uint maxSize
, QString
const & source
= 0) = 0;
136 * Returns the maximum number of log files.
137 * @param source Name of the source or default if omitted.
139 virtual uint
maxCount(QString
const & source
= 0) = 0;
142 * Changes the maximum number of log files
143 * @param maxCount The new maximum number
144 * @param source Name of the source or default if omitted
146 * This function sets the maximum number of log files including the current log file
147 * and any backup files. Older backup files are deleted to keep the number of log
148 * files at the maximum.
150 * The default value for all the sources is usually 3 (the current log file plus 2
153 * Set the maximum number of log files to 0 for no limits (dangerous!).
155 virtual void setMaxCount(uint maxCount
, QString
const & source
= 0) = 0;
158 * Returns the current console severity level.
160 virtual Severity
consoleSeverity() const = 0;
163 * Changes the console severity level.
164 * @param severity The new console severity level
166 * This function changes the console severity level. By default, only fatal errors are output to
169 virtual void setConsoleSeverity(Severity severity
) = 0;
173 * @param severity Severity of the message, ie how important it is.
174 * @param msg The message to be output
175 * @param source Source of the message or default if omitted.
176 * @param where Location in the source file where the message was output.
178 * This function writes a message to the log file if the severity is high enough. If the
179 * severity is lower than the current severity level, then does nothing.
181 * If the source parameter is given, then uses the specified source. Otherwise writes
182 * to the default log file.
184 * The where parameter can be used to indicate the location in the source file where
185 * the message was generated.
187 * Messages for the default source are also output to the console if the console severity
188 * level is high enough.
190 virtual void write(Severity severity
, QString
const & msg
, QString
const & source
= 0, QString
const & where
= 0) = 0;
193 * Helper function for formatting messages using the standard printf() function.
194 * @param fmt The format string
195 * @param ... Variable number of arguments
196 * @return The formatted string
198 virtual QString
printf(char const * const fmt
, ...) const
200 __attribute__((format(printf
, 2, 3)))
205 * Replaces non-printable characters in the input string with human-readable strings.
206 * @param msg The input string
207 * @return Human-readable string
209 * This function replaces all the non-printable characters with human-readable strings, like
210 * ASCII symbol names or HEX codes.
212 * For example, the Line Feed character will be replaced with "[LF]".
214 virtual QString
printable(QByteArray
const & msg
) const = 0;
217 * Installs a fatal error message handler.
218 * @param newHandler The new fatal error message handler
219 * @return The old fatal error message handler
221 * This function installs a custom fatal error message handler. The custom fatal error message
222 * handler is responsible for giving feedback to the user and terminating the application.
224 * The default fatal error message handler outputs the message to stderr and terminates the
227 virtual FatalMsgHandler
installFatalMsgHandler(FatalMsgHandler newHandler
) = 0;
233 * Logger event signal
234 * @param severity Severity of the message
235 * @param text The message
236 * @param source Source of the message
237 * @param where Where the message was output
239 * This signal is emitted for every message output with the iLogger interface. Connect
240 * your receiver to this signal if you want to add your own message handling. For example,
241 * use this signal to show messages in a log window etc.
243 void loggerEvent(Severity severity
, QString
const & text
, QString
const & source
, QString
const & where
);
247 } // namespace eVaf::Common
251 * Outputs info messages
252 * @param msg The format string
253 * @param ... Variable list of arguments
255 * The qInfo() function adds info messages to the Qt family of functions qDebug(), qWarning(), qError() and qFatal().
257 void COMMON_EXPORT
qInfo(char const * const msg
, ...)
259 __attribute__((format(printf
, 1, 2)))
264 * Macro for fatal error messages.
266 * This macro expands to a fatal error message output with the location in the source code where the error
269 #define EVAF_FATAL_ERROR(...) \
271 eVaf::Common::iLogger::instance()->write( \
272 eVaf::Common::iLogger::Fatal, \
273 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
275 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
280 * Macro for error messages.
282 * This macro expands to an error message output with the location in the source code where the error
285 #define EVAF_ERROR(...) \
287 eVaf::Common::iLogger::instance()->write( \
288 eVaf::Common::iLogger::Error, \
289 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
291 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
296 * Macro for warning messages.
298 * This macro expands to a warning message output with the location in the source code where the warning
301 #define EVAF_WARNING(...) \
303 eVaf::Common::iLogger::instance()->write( \
304 eVaf::Common::iLogger::Warning, \
305 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
307 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
312 * Macro for info messages.
314 * This macro expands to an info message output with the location in the source code where the message
317 #define EVAF_INFO(...) \
319 eVaf::Common::iLogger::instance()->write( \
320 eVaf::Common::iLogger::Info, \
321 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
323 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
328 * Macro for debug messages.
330 * This macro expands to a debug message output with the location in the source code where the message
331 * is output. All the debug messages are supressed when the NDEBUG directive is defined.
334 # define EVAF_DEBUG(...) \
336 eVaf::Common::iLogger::instance()->write( \
337 eVaf::Common::iLogger::Debug, \
338 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
340 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
344 # define EVAF_DEBUG(...) \