+/**
+ * @file Common/ilogger.h
+ * @brief Logger interface for eVaf
+ * @author Enar Vaikene
+ *
+ * Copyright (c) 2011 Enar Vaikene
+ *
+ * This file is part of the eVaf C++ cross-platform application development framework.
+ *
+ * This file can be used under the terms of the GNU General Public License
+ * version 3.0 as published by the Free Software Foundation and appearing in
+ * the file LICENSE included in the packaging of this file. Please review the
+ * the following information to ensure the GNU General Public License version
+ * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
+ *
+ * Alternatively, this file may be used in accordance with the Commercial License
+ * Agreement provided with the Software.
+ */
+
+#ifndef __COMMON_ILOGGER_H
+# define __COMMON_ILOGGER_H
+
+#include "libcommon.h"
+
+#include <QObject>
+#include <QString>
+#include <QByteArray>
+
+
+namespace eVaf {
+namespace Common {
+
+/**
+ * Prototype for custom fatal message handler.
+ *
+ * This is a typedef for a pointer to a function with the following signature:
+ * @code
+ * void myFatalMessageHandler(QString const & msg, QString const & source, QString const & where);
+ * @endcode
+ *
+ * @sa iLogger::installFatalMsgHandler()
+ */
+typedef void (*FatalMsgHandler)(QString const & msg, QString const & source, QString const & where);
+
+/**
+ * Logger interface for eVaf modules and applications.
+ * @code#include <Common/iLogger>@endcode
+ *
+ */
+class COMMON_EXPORT iLogger : public QObject
+{
+ Q_OBJECT
+
+public:
+
+ /**
+ * Severity levels for messages indicating the meaning and seriousness of the message.
+ */
+ enum Severity {
+ None = 0, ///< For disabling logging completely (to be not used with messages).
+ Fatal, ///< Fatal error that causes the application to stop functioning.
+ Error, ///< Unexpected issues in the software that could be solved automatically.
+ Warning, ///< Expected issues in the software that will be solved automatically.
+ Info, ///< General information output by the application or modules.
+ Debug ///< Information for debugging purposes.
+ };
+
+ /// Interface constructor
+ iLogger() : QObject() {}
+
+ /// Empty virtual destructor
+ virtual ~iLogger() {}
+
+ /**
+ * Returns the iLogger interface instance.
+ * @return The iLogger interface
+ *
+ * The instance() function returns the global iLogger interface instance. As all the modules and applications
+ * are expected to be linked against the Common library, then this is the preferred method of obtaining
+ * the iLogger interface. The other method is by using the iRegistry interface.
+ */
+ static iLogger::instance();
+
+ /**
+ * Returns the current default source name.
+ */
+ virtual QString defaultSource() const = 0;
+
+ /**
+ * Sets the default source.
+ * @param source The new default source name.
+ *
+ * Use the setDefaultSource() function to change the default source name. If not set, then
+ * uses the default source name "common".
+ */
+ virtual void setDefaultSource(QString const & source) = 0;
+
+ /**
+ * Returns the current severity level
+ * @param source Name of the source or default if omitted.
+ */
+ virtual Severity severity(QString const & source = 0) const = 0;
+
+ /**
+ * Changes the current severity level.
+ * @param severity The new severity level
+ * @param source Name of the source or default if omitted.
+ *
+ * This function changes the severity level of the given logger source. By default, only fatal errors
+ * are output. With this function the severity level can be changed so that also less important
+ * messages are output.
+ */
+ virtual void setSeverity(Severity severity, QString const & source) = 0;
+
+ /**
+ * Returns the current maximum size of log files in KiB.
+ * @param source Name of the source or default if omitted.
+ */
+ virtual uint maxSize(QString const & source = 0) const = 0;
+
+ /**
+ * Changes the maximum size of log files for the given source
+ * @param maxSize The new maximum size in KiB
+ * @param source Name of the source of default if omitted.
+ *
+ * This function changes the maximum size of log files. Log files larger than this value
+ * will be renamed to backup files.
+ *
+ * The default value for all the sources is usually 100 KiB.
+ *
+ * Set the maximum size to 0 for no limits (dangerous!).
+ */
+ virtual void setMaxSize(uint maxSize, QString const & source = 0) = 0;
+
+ /**
+ * Returns the maximum number of log files.
+ * @param source Name of the source or default if omitted.
+ */
+ virtual uint maxCount(QString const & source = 0) const = 0;
+
+ /**
+ * Changes the maximum number of log files
+ * @param maxCount The new maximum number
+ * @param source Name of the source or default if omitted
+ *
+ * This function sets the maximum number of log files including the current log file
+ * and any backup files. Older backup files are deleted to keep the number of log
+ * files at the maximum.
+ *
+ * The default value for all the sources is usually 3 (the current log file plus 2
+ * backup files).
+ *
+ * Set the maximum number of log files to 0 for no limits (dangerous!).
+ */
+ virtual void setMaxCount(uint maxCount, QString const & source = 0) = 0;
+
+ /**
+ * Returns the current console severity level.
+ */
+ virtual Severity consoleSeverity() const = 0;
+
+ /**
+ * Changes the console severity level.
+ * @param severity The new console severity level
+ *
+ * This function changes the console severity level. By default, only fatal errors are output to
+ * the console.
+ */
+ virtual void setConsoleSeverity(Severity severity) = 0;
+
+ /**
+ * Outputs a message.
+ * @param severity Severity of the message, ie how important it is.
+ * @param msg The message to be output
+ * @param source Source of the message or default if omitted.
+ * @param where Location in the source file where the message was output.
+ *
+ * This function writes a message to the log file if the severity is high enough. If the
+ * severity is lower than the current severity level, then does nothing.
+ *
+ * If the source parameter is given, then uses the specified source. Otherwise writes
+ * to the default log file.
+ *
+ * The where parameter can be used to indicate the location in the source file where
+ * the message was generated.
+ *
+ * Messages for the default source are also output to the console if the console severity
+ * level is high enough.
+ */
+ virtual void write(Severity severity, QString const & msg, QString const & source = 0, QString const & where = 0) = 0;
+
+ /**
+ * Helper function for formatting messages using the standard printf() function.
+ * @param fmt The format string
+ * @param ... Variable number of arguments
+ * @return The formatted string
+ */
+ virtual QString printf(char const * const fmt, ...) const
+#ifdef Q_OS_LINUX
+ __attribute__((format(printf, 2, 3)))
+#endif
+ = 0;
+
+ /**
+ * Replaces non-printable characters in the input string with human-readable strings.
+ * @param msg The input string
+ * @return Human-readable string
+ *
+ * This function replaces all the non-printable characters with human-readable strings, like
+ * ASCII symbol names or HEX codes.
+ *
+ * For example, the Line Feed character will be replaced with "[LF]".
+ */
+ virtual QString printable(QByteArray const & msg) const = 0;
+
+ /**
+ * Installs a fatal error message handler.
+ * @param newHandler The new fatal error message handler
+ * @return The old fatal error message handler
+ *
+ * This function installs a custom fatal error message handler. The custom fatal error message
+ * handler is responsible for giving feedback to the user and terminating the application.
+ *
+ * The default fatal error message handler outputs the message to stderr and terminates the
+ * application.
+ */
+ virtual FatalMsgHandler installFatalMsgHandler(FatalMsgHandler newHandler) = 0;
+
+};
+
+} // namespace eVaf::Common
+} // namespace eVaf
+
+/**
+ * Outputs info messages
+ * @param msg The format string
+ * @param ... Variable list of arguments
+ *
+ * The qInfo() function adds info messages to the Qt family of functions qDebug(), qWarning(), qError() and qFatal().
+ */
+void COMMON_EXPORT qInfo(char const * const msg, ...)
+#ifdef Q_OS_LINUX
+ __attribute__((format(printf, 1, 2)))
+#endif
+;
+
+#endif // ilogger.h