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         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     virtual void setDefaultSource(QString const & source) = 0;
  98
  99     /**
 100      * Returns the current severity level
 101      * @param source Name of the source or default if omitted.
 102      */
 103     virtual Severity severity(QString const & source = 0) = 0;
 104
 105     /**
 106      * Changes the current severity level.
 107      * @param severity The new severity level
 108      * @param source Name of the source or default if omitted.
 109      *
 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.
 113      */
 114     virtual void setSeverity(Severity severity, QString const & source = 0) = 0;
 115
 116     /**
 117      * Returns the current maximum size of log files in KiB.
 118      * @param source Name of the source or default if omitted.
 119      */
 120     virtual uint maxSize(QString const & source = 0) = 0;
 121
 122     /**
 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.
 126      *
 127      * This function changes the maximum size of log files. Log files larger than this value
 128      * will be renamed to backup files.
 129      *
 130      * The default value for all the sources is usually 100 KiB.
 131      *
 132      * Set the maximum size to 0 for no limits (dangerous!).
 133      */
 134     virtual void setMaxSize(uint maxSize, QString const & source = 0) = 0;
 135
 136     /**
 137      * Returns the maximum number of log files.
 138      * @param source Name of the source or default if omitted.
 139      */
 140     virtual uint maxCount(QString const & source = 0) = 0;
 141
 142     /**
 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
 146      *
 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.
 150      *
 151      * The default value for all the sources is usually 3 (the current log file plus 2
 152      * backup files).
 153      *
 154      * Set the maximum number of log files to 0 for no limits (dangerous!).
 155      */
 156     virtual void setMaxCount(uint maxCount, QString const & source = 0) = 0;
 157
 158     /**
 159      * Returns the current console severity level.
 160      */
 161     virtual Severity consoleSeverity() const = 0;
 162
 163     /**
 164      * Changes the console severity level.
 165      * @param severity The new console severity level
 166      *
 167      * This function changes the console severity level. By default, only fatal errors are output to
 168      * the console.
 169      */
 170     virtual void setConsoleSeverity(Severity severity) = 0;
 171
 172     /**
 173      * Outputs a message.
 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.
 178      *
 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.
 181      *
 182      * If the source parameter is given, then uses the specified source. Otherwise writes
 183      * to the default log file.
 184      *
 185      * The where parameter can be used to indicate the location in the source file where
 186      * the message was generated.
 187      *
 188      * Messages for the default source are also output to the console if the console severity
 189      * level is high enough.
 190      */
 191     virtual void write(Severity severity, QString const & msg, QString const & source = 0, QString const & where = 0) = 0;
 192
 193     /**
 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
 198      */
 199     virtual QString printf(char const * const fmt, ...) const
 200 #ifdef Q_OS_LINUX
 201             __attribute__((format(printf, 2, 3)))
 202 #endif
 203             = 0;
 204
 205     /**
 206      * Replaces non-printable characters in the input string with human-readable strings.
 207      * @param msg The input string
 208      * @return Human-readable string
 209      *
 210      * This function replaces all the non-printable characters with human-readable strings, like
 211      * ASCII symbol names or HEX codes.
 212      *
 213      * For example, the Line Feed character will be replaced with "[LF]".
 214      */
 215     virtual QString printable(QByteArray const & msg) const = 0;
 216
 217     /**
 218      * Installs a fatal error message handler.
 219      * @param newHandler The new fatal error message handler
 220      * @return The old fatal error message handler
 221      *
 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.
 224      *
 225      * The default fatal error message handler outputs the message to stderr and terminates the
 226      * application.
 227      */
 228     virtual FatalMsgHandler installFatalMsgHandler(FatalMsgHandler newHandler) = 0;
 229
 230
 231 signals:
 232
 233     /**
 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
 239      *
 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.
 243      */
 244     void loggerEvent(eVaf::Common::iLogger::Severity severity, QString const & text, QString const & source, QString const & where);
 245
 246 };
 247
 248 } // namespace eVaf::Common
 249 } // namespace eVaf
 250
 251 /**
 252  * Outputs info messages
 253  * @param msg The format string
 254  * @param ... Variable list of arguments
 255  *
 256  * The qInfo() function adds info messages to the Qt family of functions qDebug(), qWarning(), qError() and qFatal().
 257  */
 258 void COMMON_EXPORT qInfo(char const * const msg, ...)
 259 #ifdef Q_OS_LINUX
 260             __attribute__((format(printf, 1, 2)))
 261 #endif
 262 ;
 263
 264 /**
 265  * Macro for fatal error messages.
 266  *
 267  * This macro expands to a fatal error message output with the location in the source code where the error
 268  * occurred.
 269  */
 270 #define EVAF_FATAL_ERROR(...) \
 271     do { \
 272         eVaf::Common::iLogger::instance()->write( \
 273             eVaf::Common::iLogger::Fatal, \
 274             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 275             0, \
 276             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 277         ); \
 278     } while (0)
 279
 280 /**
 281  * Macro for error messages.
 282  *
 283  * This macro expands to an error message output with the location in the source code where the error
 284  * occurred.
 285  */
 286 #define EVAF_ERROR(...) \
 287     do { \
 288         eVaf::Common::iLogger::instance()->write( \
 289             eVaf::Common::iLogger::Error, \
 290             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 291             0, \
 292             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 293         ); \
 294     } while (0)
 295
 296 /**
 297  * Macro for warning messages.
 298  *
 299  * This macro expands to a warning message output with the location in the source code where the warning
 300  * occurred.
 301  */
 302 #define EVAF_WARNING(...) \
 303     do { \
 304         eVaf::Common::iLogger::instance()->write( \
 305             eVaf::Common::iLogger::Warning, \
 306             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 307             0, \
 308             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 309         ); \
 310     } while (0)
 311
 312 /**
 313  * Macro for info messages.
 314  *
 315  * This macro expands to an info message output with the location in the source code where the message
 316  * is output.
 317  */
 318 #define EVAF_INFO(...) \
 319     do { \
 320         eVaf::Common::iLogger::instance()->write( \
 321             eVaf::Common::iLogger::Info, \
 322             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 323             0, \
 324             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 325         ); \
 326     } while (0)
 327
 328 /**
 329  * Macro for debug messages.
 330  *
 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.
 333  */
 334 #ifndef NDEBUG
 335 #  define EVAF_DEBUG(...) \
 336     do { \
 337         eVaf::Common::iLogger::instance()->write( \
 338             eVaf::Common::iLogger::Debug, \
 339             eVaf::Common::iLogger::instance()->printf(__VA_ARGS__), \
 340             0, \
 341             eVaf::Common::iLogger::instance()->printf("%s:%s:%d", __FILE__, __FUNCTION__, __LINE__) \
 342         ); \
 343     } while (0)
 344 #else
 345 #  define EVAF_DEBUG(...) \
 346     do { } while (0)
 347 #endif
 348
 349 #endif // ilogger.h