/**
 * @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