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-2012 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         Count       ///< Number of severity levels
  67     };
  68
  69     /// Interface constructor
  70     iLogger() : QObject() {}
  71
  72     /// Empty virtual destructor
  73     virtual ~iLogger() {}
  74
  75     /**
  76      * Returns the iLogger interface instance.
  77      * @return The iLogger interface
  78      *
  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.
  82      */
  83     static iLogger * instance();
  84
  85     /**
  86      * Returns the current default source name.
  87      */
  88     virtual QString defaultSource() const = 0;
  89
  90     /**
  91      * Sets the default source.
  92      * @param source The new default source name.
  93      *
  94      * Use the setDefaultSource() function to change the default source name. If not set, then
  95      * uses the default source name "common".
  96      *
  97      * Changing the name of the default source resets any other settings set for the default source.
  98      */
  99     virtual void setDefaultSource(QString const & source) = 0;
 100
 101     /**
 102      * Returns the current severity level
 103      * @param source Name of the source or default if omitted.
 104      */
 105     virtual Severity severity(QString const & source = 0) = 0;
 106
 107     /**
 108      * Changes the current severity level.
 109      * @param severity The new severity level
 110      * @param source Name of the source or default if omitted.
 111      *
 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.
 115      */
 116     virtual void setSeverity(Severity severity, QString const & source = 0) = 0;
 117
 118     /**
 119      * Returns the current maximum size of log files in KiB.
 120      * @param source Name of the source or default if omitted.
 121      */
 122     virtual uint maxSize(QString const & source = 0) = 0;
 123
 124     /**
 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.
 128      *
 129      * This function changes the maximum size of log files. Log files larger than this value
 130      * will be renamed to backup files.
 131      *
 132      * The default value for all the sources is usually 100 KiB.
 133      *
 134      * Set the maximum size to 0 for no limits (dangerous!).
 135      */
 136     virtual void setMaxSize(uint maxSize, QString const & source = 0) = 0;
 137
 138     /**
 139      * Returns the maximum number of log files.
 140      * @param source Name of the source or default if omitted.
 141      */
 142     virtual uint maxCount(QString const & source = 0) = 0;
 143
 144     /**
 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
 148      *
 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.
 152      *
 153      * The default value for all the sources is usually 3 (the current log file plus 2
 154      * backup files).
 155      *
 156      * Set the maximum number of log files to 0 for no limits (dangerous!).
 157      */
 158     virtual void setMaxCount(uint maxCount, QString const & source = 0) = 0;
 159
 160     /**
 161      * Returns the current console severity level.
 162      */
 163     virtual Severity consoleSeverity() const = 0;
 164
 165     /**
 166      * Changes the console severity level.
 167      * @param severity The new console severity level
 168      *
 169      * This function changes the console severity level. By default, only fatal errors are output to
 170      * the console.
 171      */
 172     virtual void setConsoleSeverity(Severity severity) = 0;
 173
 174     /**
 175      * Outputs a message.
 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.
 180      *
 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.
 183      *
 184      * If the source parameter is given, then uses the specified source. Otherwise writes
 185      * to the default log file.
 186      *
 187      * The where parameter can be used to indicate the location in the source file where
 188      * the message was generated.
 189      *
 190      * Messages for the default source are also output to the console if the console severity
 191      * level is high enough.
 192      */
 193     virtual void write(Severity severity, QString const & msg, QString const & source = 0, QString const & where = 0) = 0;
 194
 195     /**
 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
 200      */
 201     virtual QString printf(char const * const fmt, ...) const
 202 #ifdef Q_OS_LINUX
 203             __attribute__((format(printf, 2, 3)))
 204 #endif
 205             = 0;
 206
 207     /**
 208      * Replaces non-printable characters in the input string with human-readable strings.
 209      * @param msg The input string
 210      * @return Human-readable string
 211      *
 212      * This function replaces all the non-printable characters with human-readable strings, like
 213      * ASCII symbol names or HEX codes.
 214      *
 215      * For example, the Line Feed character will be replaced with "[LF]".
 216      */
 217     virtual QString printable(QByteArray const & msg) const = 0;
 218
 219     /**
 220      * Installs a fatal error message handler.
 221      * @param newHandler The new fatal error message handler
 222      * @return The old fatal error message handler
 223      *
 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.
 226      *
 227      * The default fatal error message handler outputs the message to stderr and terminates the
 228      * application.
 229      */
 230     virtual FatalMsgHandler installFatalMsgHandler(FatalMsgHandler newHandler) = 0;
 231
 232
 233 signals:
 234
 235     /**
 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
 241      *
 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.
 245      */
 246     void loggerEvent(Common::iLogger::Severity severity, QString const & text, QString const & source, QString const & where);
 247
 248 };
 249
 250 } // namespace eVaf::Common
 251 } // namespace eVaf
 252
 253 /**
 254  * Macro for fatal error messages.
 255  *
 256  * This macro expands to a fatal error message output with the location in the source code where the error
 257  * occurred.
 258  */
 259 #define EVAF_FATAL_ERROR(...) \
 260     do { \
 261         eVaf::Common::iLogger::instance()->write( \
 262             eVaf::Common::iLogger::Fatal, \
 263             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 264             0, \
 265             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 266         ); \
 267     } while (0)
 268
 269 /**
 270  * Macro for error messages.
 271  *
 272  * This macro expands to an error message output with the location in the source code where the error
 273  * occurred.
 274  */
 275 #define EVAF_ERROR(...) \
 276     do { \
 277         eVaf::Common::iLogger::instance()->write( \
 278             eVaf::Common::iLogger::Error, \
 279             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 280             0, \
 281             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 282         ); \
 283     } while (0)
 284
 285 /**
 286  * Macro for warning messages.
 287  *
 288  * This macro expands to a warning message output with the location in the source code where the warning
 289  * occurred.
 290  */
 291 #define EVAF_WARNING(...) \
 292     do { \
 293         eVaf::Common::iLogger::instance()->write( \
 294             eVaf::Common::iLogger::Warning, \
 295             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 296             0, \
 297             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 298         ); \
 299     } while (0)
 300
 301 /**
 302  * Macro for info messages.
 303  *
 304  * This macro expands to an info message output with the location in the source code where the message
 305  * is output.
 306  */
 307 #define EVAF_INFO(...) \
 308     do { \
 309         eVaf::Common::iLogger::instance()->write( \
 310             eVaf::Common::iLogger::Info, \
 311             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 312             0, \
 313             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 314         ); \
 315     } while (0)
 316
 317 /**
 318  * Macro for debug messages.
 319  *
 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.
 322  */
 323 #ifndef NDEBUG
 324 #  define EVAF_DEBUG(...) \
 325     do { \
 326         eVaf::Common::iLogger::instance()->write( \
 327             eVaf::Common::iLogger::Debug, \
 328             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 329             0, \
 330             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 331         ); \
 332     } while (0)
 333 #else
 334 #  define EVAF_DEBUG(...) \
 335     do { } while (0)
 336 #endif
 337
 338 #endif // ilogger.h