2 * @file Common/ilogger.h
3 * @brief Logger interface for eVaf
6 * Copyright (c) 2011-2019 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 * Changing the name of the default source resets any other settings set for the default source.
99 virtual void setDefaultSource(QString
const & source
) = 0;
102 * Returns the current severity level
103 * @param source Name of the source or default if omitted.
105 virtual Severity
severity(QString
const & source
= QString()) = 0;
108 * Changes the current severity level.
109 * @param severity The new severity level
110 * @param source Name of the source or default if omitted.
112 * This function changes the severity level of the given logger source. By default, only fatal errors
113 * are output. With this function the severity level can be changed so that also less important
114 * messages are output.
116 virtual void setSeverity(Severity severity
, QString
const & source
= QString()) = 0;
119 * Returns the current maximum size of log files in KiB.
120 * @param source Name of the source or default if omitted.
122 virtual uint
maxSize(QString
const & source
= QString()) = 0;
125 * Changes the maximum size of log files for the given source
126 * @param maxSize The new maximum size in KiB
127 * @param source Name of the source of default if omitted.
129 * This function changes the maximum size of log files. Log files larger than this value
130 * will be renamed to backup files.
132 * The default value for all the sources is usually 100 KiB.
134 * Set the maximum size to 0 for no limits (dangerous!).
136 virtual void setMaxSize(uint maxSize
, QString
const & source
= QString()) = 0;
139 * Returns the maximum number of log files.
140 * @param source Name of the source or default if omitted.
142 virtual uint
maxCount(QString
const & source
= QString()) = 0;
145 * Changes the maximum number of log files
146 * @param maxCount The new maximum number
147 * @param source Name of the source or default if omitted
149 * This function sets the maximum number of log files including the current log file
150 * and any backup files. Older backup files are deleted to keep the number of log
151 * files at the maximum.
153 * The default value for all the sources is usually 3 (the current log file plus 2
156 * Set the maximum number of log files to 0 for no limits (dangerous!).
158 virtual void setMaxCount(uint maxCount
, QString
const & source
= QString()) = 0;
161 * Returns the current console severity level.
163 virtual Severity
consoleSeverity() const = 0;
166 * Changes the console severity level.
167 * @param severity The new console severity level
169 * This function changes the console severity level. By default, only fatal errors are output to
172 virtual void setConsoleSeverity(Severity severity
) = 0;
176 * @param severity Severity of the message, ie how important it is.
177 * @param msg The message to be output
178 * @param source Source of the message or default if omitted.
179 * @param where Location in the source file where the message was output.
181 * This function writes a message to the log file if the severity is high enough. If the
182 * severity is lower than the current severity level, then does nothing.
184 * If the source parameter is given, then uses the specified source. Otherwise writes
185 * to the default log file.
187 * The where parameter can be used to indicate the location in the source file where
188 * the message was generated.
190 * Messages for the default source are also output to the console if the console severity
191 * level is high enough.
193 virtual void write(Severity severity
, QString
const & msg
, QString
const & source
= QString(), QString
const & where
= QString()) = 0;
196 * Helper function for formatting messages using the standard printf() function.
197 * @param fmt The format string
198 * @param ... Variable number of arguments
199 * @return The formatted string
201 virtual QString
printf(char const * const fmt
, ...) const
202 #if defined(Q_OS_LINUX) || defined(Q_OS_MACOS)
203 __attribute__((format(printf
, 2, 3)))
208 * Replaces non-printable characters in the input string with human-readable strings.
209 * @param msg The input string
210 * @return Human-readable string
212 * This function replaces all the non-printable characters with human-readable strings, like
213 * ASCII symbol names or HEX codes.
215 * For example, the Line Feed character will be replaced with "[LF]".
217 virtual QString
printable(QByteArray
const & msg
) const = 0;
220 * Installs a fatal error message handler.
221 * @param newHandler The new fatal error message handler
222 * @return The old fatal error message handler
224 * This function installs a custom fatal error message handler. The custom fatal error message
225 * handler is responsible for giving feedback to the user and terminating the application.
227 * The default fatal error message handler outputs the message to stderr and terminates the
230 virtual FatalMsgHandler
installFatalMsgHandler(FatalMsgHandler newHandler
) = 0;
236 * Logger event signal
237 * @param severity Severity of the message
238 * @param text The message
239 * @param source Source of the message
240 * @param where Where the message was output
242 * This signal is emitted for every message output with the iLogger interface. Connect
243 * your receiver to this signal if you want to add your own message handling. For example,
244 * use this signal to show messages in a log window etc.
246 void loggerEvent(Common::iLogger::Severity severity
, QString
const & text
, QString
const & source
, QString
const & where
);
250 } // namespace eVaf::Common
254 * Macro for fatal error messages.
256 * This macro expands to a fatal error message output with the location in the source code where the error
259 #define EVAF_FATAL_ERROR(...) \
261 eVaf::Common::iLogger::instance()->write( \
262 eVaf::Common::iLogger::Fatal, \
263 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
265 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
270 * Macro for error messages.
272 * This macro expands to an error message output with the location in the source code where the error
275 #define EVAF_ERROR(...) \
277 eVaf::Common::iLogger::instance()->write( \
278 eVaf::Common::iLogger::Error, \
279 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
281 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
286 * Macro for warning messages.
288 * This macro expands to a warning message output with the location in the source code where the warning
291 #define EVAF_WARNING(...) \
293 eVaf::Common::iLogger::instance()->write( \
294 eVaf::Common::iLogger::Warning, \
295 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
297 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
302 * Macro for info messages.
304 * This macro expands to an info message output with the location in the source code where the message
307 #define EVAF_INFO(...) \
309 eVaf::Common::iLogger::instance()->write( \
310 eVaf::Common::iLogger::Info, \
311 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
313 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
318 * Macro for debug messages.
320 * This macro expands to a debug message output with the location in the source code where the message
321 * is output. All the debug messages are supressed when the NDEBUG directive is defined.
324 # define EVAF_DEBUG(...) \
326 eVaf::Common::iLogger::instance()->write( \
327 eVaf::Common::iLogger::Debug, \
328 eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
330 eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
334 # define EVAF_DEBUG(...) \