vaikene.ee Git - evaf/blob - src/libs/Common/ilogger.h

   1 /**
   2  * @file Common/ilogger.h
   3  * @brief Logger interface for eVaf
   4  * @author Enar Vaikene
   5  *
   6  * Copyright (c) 2011 Enar Vaikene
   7  *
   8  * This file is part of the eVaf C++ cross-platform application development framework.
   9  *
  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.
  15  *
  16  * Alternatively, this file may be used in accordance with the Commercial License
  17  * Agreement provided with the Software.
  18  */
  19
  20 #ifndef __COMMON_ILOGGER_H
  21 #  define __COMMON_ILOGGER_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QObject>
  26 #include <QString>
  27 #include <QByteArray>
  28
  29
  30 namespace eVaf {
  31 namespace Common {
  32
  33 /**
  34  * Prototype for custom fatal message handler.
  35  *
  36  * This is a typedef for a pointer to a function with the following signature:
  37  * @code
  38  * void myFatalMessageHandler(QString const & msg, QString const & source, QString const & where);
  39  * @endcode
  40  *
  41  * @sa iLogger::installFatalMsgHandler()
  42  */
  43 typedef void (*FatalMsgHandler)(QString const & msg, QString const & source, QString const & where);
  44
  45 /**
  46  * Logger interface for eVaf modules and applications.
  47  * @code#include <Common/iLogger>@endcode
  48  *
  49  */
  50 class COMMON_EXPORT iLogger : public QObject
  51 {
  52     Q_OBJECT
  53
  54 public:
  55
  56     /**
  57      * Severity levels for messages indicating the meaning and seriousness of the message.
  58      */
  59     enum Severity {
  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     };
  67
  68     /// Interface constructor
  69     iLogger() : QObject() {}
  70
  71     /// Empty virtual destructor
  72     virtual ~iLogger() {}
  73
  74     /**
  75      * Returns the iLogger interface instance.
  76      * @return The iLogger interface
  77      *
  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.
  81      */
  82     static iLogger * instance();
  83
  84     /**
  85      * Returns the current default source name.
  86      */
  87     virtual QString defaultSource() const = 0;
  88
  89     /**
  90      * Sets the default source.
  91      * @param source The new default source name.
  92      *
  93      * Use the setDefaultSource() function to change the default source name. If not set, then
  94      * uses the default source name "common".
  95      */
  96     virtual void setDefaultSource(QString const & source) = 0;
  97
  98     /**
  99      * Returns the current severity level
 100      * @param source Name of the source or default if omitted.
 101      */
 102     virtual Severity severity(QString const & source = 0) = 0;
 103
 104     /**
 105      * Changes the current severity level.
 106      * @param severity The new severity level
 107      * @param source Name of the source or default if omitted.
 108      *
 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.
 112      */
 113     virtual void setSeverity(Severity severity, QString const & source = 0) = 0;
 114
 115     /**
 116      * Returns the current maximum size of log files in KiB.
 117      * @param source Name of the source or default if omitted.
 118      */
 119     virtual uint maxSize(QString const & source = 0) = 0;
 120
 121     /**
 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.
 125      *
 126      * This function changes the maximum size of log files. Log files larger than this value
 127      * will be renamed to backup files.
 128      *
 129      * The default value for all the sources is usually 100 KiB.
 130      *
 131      * Set the maximum size to 0 for no limits (dangerous!).
 132      */
 133     virtual void setMaxSize(uint maxSize, QString const & source = 0) = 0;
 134
 135     /**
 136      * Returns the maximum number of log files.
 137      * @param source Name of the source or default if omitted.
 138      */
 139     virtual uint maxCount(QString const & source = 0) = 0;
 140
 141     /**
 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
 145      *
 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.
 149      *
 150      * The default value for all the sources is usually 3 (the current log file plus 2
 151      * backup files).
 152      *
 153      * Set the maximum number of log files to 0 for no limits (dangerous!).
 154      */
 155     virtual void setMaxCount(uint maxCount, QString const & source = 0) = 0;
 156
 157     /**
 158      * Returns the current console severity level.
 159      */
 160     virtual Severity consoleSeverity() const = 0;
 161
 162     /**
 163      * Changes the console severity level.
 164      * @param severity The new console severity level
 165      *
 166      * This function changes the console severity level. By default, only fatal errors are output to
 167      * the console.
 168      */
 169     virtual void setConsoleSeverity(Severity severity) = 0;
 170
 171     /**
 172      * Outputs a message.
 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.
 177      *
 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.
 180      *
 181      * If the source parameter is given, then uses the specified source. Otherwise writes
 182      * to the default log file.
 183      *
 184      * The where parameter can be used to indicate the location in the source file where
 185      * the message was generated.
 186      *
 187      * Messages for the default source are also output to the console if the console severity
 188      * level is high enough.
 189      */
 190     virtual void write(Severity severity, QString const & msg, QString const & source = 0, QString const & where = 0) = 0;
 191
 192     /**
 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
 197      */
 198     virtual QString printf(char const * const fmt, ...) const
 199 #ifdef Q_OS_LINUX
 200             __attribute__((format(printf, 2, 3)))
 201 #endif
 202             = 0;
 203
 204     /**
 205      * Replaces non-printable characters in the input string with human-readable strings.
 206      * @param msg The input string
 207      * @return Human-readable string
 208      *
 209      * This function replaces all the non-printable characters with human-readable strings, like
 210      * ASCII symbol names or HEX codes.
 211      *
 212      * For example, the Line Feed character will be replaced with "[LF]".
 213      */
 214     virtual QString printable(QByteArray const & msg) const = 0;
 215
 216     /**
 217      * Installs a fatal error message handler.
 218      * @param newHandler The new fatal error message handler
 219      * @return The old fatal error message handler
 220      *
 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.
 223      *
 224      * The default fatal error message handler outputs the message to stderr and terminates the
 225      * application.
 226      */
 227     virtual FatalMsgHandler installFatalMsgHandler(FatalMsgHandler newHandler) = 0;
 228
 229
 230 signals:
 231
 232     /**
 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
 238      *
 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.
 242      */
 243     void loggerEvent(eVaf::Common::iLogger::Severity severity, QString const & text, QString const & source, QString const & where);
 244
 245 };
 246
 247 } // namespace eVaf::Common
 248 } // namespace eVaf
 249
 250 /**
 251  * Outputs info messages
 252  * @param msg The format string
 253  * @param ... Variable list of arguments
 254  *
 255  * The qInfo() function adds info messages to the Qt family of functions qDebug(), qWarning(), qError() and qFatal().
 256  */
 257 void COMMON_EXPORT qInfo(char const * const msg, ...)
 258 #ifdef Q_OS_LINUX
 259             __attribute__((format(printf, 1, 2)))
 260 #endif
 261 ;
 262
 263 /**
 264  * Macro for fatal error messages.
 265  *
 266  * This macro expands to a fatal error message output with the location in the source code where the error
 267  * occurred.
 268  */
 269 #define EVAF_FATAL_ERROR(...) \
 270     do { \
 271         eVaf::Common::iLogger::instance()->write( \
 272             eVaf::Common::iLogger::Fatal, \
 273             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 274             0, \
 275             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 276         ); \
 277     } while (0)
 278
 279 /**
 280  * Macro for error messages.
 281  *
 282  * This macro expands to an error message output with the location in the source code where the error
 283  * occurred.
 284  */
 285 #define EVAF_ERROR(...) \
 286     do { \
 287         eVaf::Common::iLogger::instance()->write( \
 288             eVaf::Common::iLogger::Error, \
 289             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 290             0, \
 291             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 292         ); \
 293     } while (0)
 294
 295 /**
 296  * Macro for warning messages.
 297  *
 298  * This macro expands to a warning message output with the location in the source code where the warning
 299  * occurred.
 300  */
 301 #define EVAF_WARNING(...) \
 302     do { \
 303         eVaf::Common::iLogger::instance()->write( \
 304             eVaf::Common::iLogger::Warning, \
 305             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 306             0, \
 307             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 308         ); \
 309     } while (0)
 310
 311 /**
 312  * Macro for info messages.
 313  *
 314  * This macro expands to an info message output with the location in the source code where the message
 315  * is output.
 316  */
 317 #define EVAF_INFO(...) \
 318     do { \
 319         eVaf::Common::iLogger::instance()->write( \
 320             eVaf::Common::iLogger::Info, \
 321             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 322             0, \
 323             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 324         ); \
 325     } while (0)
 326
 327 /**
 328  * Macro for debug messages.
 329  *
 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.
 332  */
 333 #ifndef NDEBUG
 334 #  define EVAF_DEBUG(...) \
 335     do { \
 336         eVaf::Common::iLogger::instance()->write( \
 337             eVaf::Common::iLogger::Debug, \
 338             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 339             0, \
 340             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 341         ); \
 342     } while (0)
 343 #else
 344 #  define EVAF_DEBUG(...) \
 345     do { } while (0)
 346 #endif
 347
 348 #endif // ilogger.h