////////////////////////////////////////////////////////////////////////////////////////////////////
//
/// \file eallog.h  Engine Abstraction Layer Logging Reference API
//
// For any questions/feedback please email gearsupport@ubisoft.com.
//
// See the ealdef.h file for details on how to use the various EAL APIs.
//
////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef __EALLOG_H_INCLUDED
#define __EALLOG_H_INCLUDED

#include <ealdef.h>
#include <cstdarg>

/// This module covers the logging reference API.
/*! \addtogroup Log
    @{
*/

////////////////////////////////////////////////////////////////////////////////////////////////////

/// Interface version.
/// The Format is an integer value equal to Major.Minor multiplied by 100 (Version 2.10 = 210)
/// See ealdef.h for more information.
#define EAL_LOG_VERSION             300

////////////////////////////////////////////////////////////////////////////////////////////////////

typedef eal_u32         eal_log_level;      ///< Logging levels

////////////////////////////////////////////////////////////////////////////////////////////////////
/// Logging levels
enum eal_log_levels
{
    EAL_LOG_NONE        = 0x00000000,       ///< No logging
    EAL_LOG_INFO        = 0x00000001,       ///< Used to display informative logs (debug)
    EAL_LOG_WARNING     = 0x00000002,       ///< Use to display warnings
    EAL_LOG_ERROR       = 0x00000004        ///< Use to display errors
};

////////////////////////////////////////////////////////////////////////////////////////////////////
/// Assert options
enum eal_log_assert_opt
{
    EAL_LOG_ASSERT_NORMAL       = 0x00000000,   ///< Normal assert (always display, can be skipped)
    EAL_LOG_ASSERT_ONCE         = 0x00000001,   ///< Caller recommend showing the assert only once
    EAL_LOG_ASSERT_DO_NOT_SKIP  = 0x00000002    ///< Caller recommend never skipping the assert
};

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Initializes the library.
    \return true if initialization succeeded

    \param Version      Must be equal to current version = EAL_LOG_VERSION

    \PRECONDITIONS
    - Must be called before any other API call.
    - The client must keep track of the number of successful calls to EalLogLibInit(), so
      EalLogLibShutdown() is called the exact same number of times.
    - Implementation version must be no more than 3 versions higher.

    \POSTCONDITIONS
    - The library will be initialized and all APIs calls will be allowed.
    - EallogLibShutdown() must be called only if initialization succeeded.

    \sa EalLogLibShutdown
*/
EAL_DLL_ENTRY bool EalLogLibInit(eal_u32 Version = EAL_LOG_VERSION);

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Shuts down the library after usage.
    \PRECONDITIONS
    - Must be called once for every call to EalLogLibInit().

    \POSTCONDITIONS
    - You are not allowed to call any other library member after calling EalLogLibShutdown().

    \sa EalLogLibInit
*/
EAL_DLL_ENTRY void EalLogLibShutdown();

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Queries if a log will be displayed or not based on its Tag & Log Level.
    This function is used for optimization purpose. Log that does not need to be displayed, will
    not build up its string, which may be costly when snprintf or similar functions are used.

    \return true    If the caller should call EalLogOutput to display the log, or false if it is
                    100% that EalLogOutput would discard the log.

    \param Tag      The tag identifying the origin of the call. See ealdef.h.
    \param Level    The level of importance of the output.

    \PRECONDITIONS
    - Level must be equal to EAL_LOG_INFO, EAL_LOG_WARNING, or EAL_LOG_ERROR.
*/
EAL_DLL_ENTRY bool EalLogIsEnabled(eal_id Tag, eal_log_level Level);

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Sends an output to the logging subsystem.
    \param Tag      The tag identifying the origin of the call. See ealdef.h.
    \param Level    The level of importance of the output, see \ref eal_log_levels for valid values
    \param pMessage A valid string containing the message to print. Can be a dynamic string.
                    String can contain the '\n' character for EOL.
    \param pFile    A string containing the filename (can be NULL)
    \param Line     The line number of the log line in the calling file

    \PRECONDITIONS
    - pMessage cannot be NULL

    \sa EalLogOutputWithFormatVa, EalLogIsEnabled
*/
EAL_DLL_ENTRY void EalLogOutput(eal_id          Tag,
                                eal_log_level   Level,
                                const char*     pMessage,
                                const char*     pFile,
                                eal_u32         Line);


EAL_DLL_ENTRY void EalLogSetTagName(eal_id        Tag,
                                    const char*   pTagName);

EAL_DLL_ENTRY const char* EalLogGetTagName(eal_id Tag);

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Sends an output to the logging subsystem using a vprintf-style format string and an argument list.
    \param Tag      The tag identifying the origin of the call. See ealdef.h.
    \param Level    The level of importance of the output, see \ref eal_log_levels for valid values
    \param pFile    A string containing the filename (can be NULL)
    \param Line     The line number of the log line in the calling file
    \param pMessageFormat   A valid string containing the message format to print. Can be a dynamic string.
                            String can contain the '\n' character for EOL.
    \param MessageArgs      Additional arguments to be sent to the output device

    \PRECONDITIONS
    - pFormat cannot be NULL

    \sa EalLogOutput, EalLogIsEnabled
*/

EAL_DLL_ENTRY void EalLogOutputWithFormatVa(eal_id Tag,
                                            eal_log_level Level,
                                            const char* pFile,
                                            eal_u32 Line,
                                            const char* pMessageFormat,
                                            va_list MessageArgs);

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Assert handler (deprecated).
    \deprecated DEPRECATED since version 2.00. Please use \ref EalLogAssert2 instead.
    This function will be removed in version 5.00.
    Implementers must still support this function until then, while clients should avoid it as soon as possible.
    Please contact mailto:gearsupport@ubisoft.com if you think this will be a problem.

    \return true if the caller should BREAK in the debugger
    \return false if the assert should be ignored. In that case, do not break.

    \param Tag          The tag identifying the origin of the call. See ealdef.h.
    \param pCondition   A string containing the condition that failed (can be NULL).
    \param pMessage     A string containing extra information on the error (can be NULL).
    \param pFile        A string containing the faulty filename (can be NULL)
    \param Line         The line number of the assert line in the calling file
    \param pStatic      Pointer to a static variable of type eal_u32. This variable should be
                        set by default to 0 and never modified. There should be a unique variable
                        per assert function in the code (we recommend declaring a static variable
                        in a macro before calling \ref EalLogAssert).
                        This variable is used by the supplier to implement "always skip features".
                        This variable can be NULL. In that case, the supplier "always skip" feature
                        will not work for that specific assert.

    \POSTCONDITIONS
    - This function will inform the user of the assert and potentially prompt him on the action to
      be taken.
    - This function SHOULD NOT HALT. Halt should be done on the caller side (we want the
      debugger to stop at the line causing the assert, and that can only be done using a macro)

    \sa EalLogAssert2
*/
EAL_DLL_ENTRY bool EalLogAssert(eal_id      Tag,
                                const char* pCondition,
                                const char* pMessage,
                                const char* pFile,
                                eal_u32     Line,
                                eal_u32*    pStatic);

////////////////////////////////////////////////////////////////////////////////////////////////////

/*! Assert handler.
    This function is an assert handler that takes care of informing the user that an assert with
    a failing condition was hit. The handler will then request to the user if the code should
    break or not. The break instruction itself must be called on the client side if the function
    return true.

    \return true if the caller should BREAK in the debugger
    \return false if the assert should be ignored. In that case, do not break.

    \param Tag          The tag identifying the origin of the call. See ealdef.h.
    \param pCondition   A string containing the condition that failed (can be NULL).
    \param pMessage     A string containing extra information on the error (can be NULL).
    \param pFile        A string containing the faulty filename (can be NULL)
    \param Line         The line number of the assert line in the calling file
    \param Options      0 by default. Can be used to inform the handler that the assert should
                        wither be displayed once (\ref EAL_LOG_ASSERT_ONCE) or never skipped
                        (\ref EAL_LOG_ASSERT_DO_NOT_SKIP).
    \param pStatic      Pointer to a static variable of type eal_u32. This variable should be
                        set by default to 0 and never modified. There should be a unique variable
                        per assert function in the code (we recommend declaring a static variable
                        in a macro before calling \ref EalLogAssert2).
                        This variable is used by the supplier to implement "always skip features".
                        This variable can be NULL. In that case, the supplier "always skip" feature
                        will not work for that specific assert.

    \POSTCONDITIONS
    - This function will inform the user of the assert and potentially prompt him on the action to
      be taken.
    - This function SHOULD NOT HALT. Halt should be done on the caller side (we want the
      debugger to stop at the line causing the assert, and that can only be done using a macro)
*/
EAL_DLL_ENTRY bool EalLogAssert2(eal_id             Tag,
                                 const char*        pCondition,
                                 const char*        pMessage,
                                 const char*        pFile,
                                 eal_u32            Line,
                                 eal_log_assert_opt Options,
                                 eal_u32*           pStatic);

////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////////
// The next section is only used if you are using Dynamic Linking (DLL).                          //
// If not, simply ignore this section. All the code declared in the next section is               //
// implemented in the corresponding CPP file (ealxxxdll.cpp).                                     //
////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////////

/// This structure contains a pointer to all EAL Log functions.
struct eal_log_dll_interface
{
    bool (*pEalLogLibInit)              (eal_u32            Version);
    void (*pEalLogLibShutdown)          ();
    void (*pEalLogOutput)               (eal_id             Tag,
                                        eal_log_level       Level,
                                        const char*         pMessage,
                                        const char*         pFile,
                                        eal_u32             Line);
    bool (*pEalLogAssert)               (eal_id             Tag,
                                        const char*         pCondition,
                                        const char*         pMessage,
                                        const char*         pFile,
                                        eal_u32             Line,
                                        eal_u32*            pStatic);
    bool (*pEalLogIsEnabled)            (eal_id             Tag,
                                        eal_log_level       Level);
    bool (*pEalLogAssert2)              (eal_id             Tag,
                                        const char*         pCondition,
                                        const char*         pMessage,
                                        const char*         pFile,
                                        eal_u32             Line,
                                        eal_log_assert_opt  Options,
                                        eal_u32*            pStatic);
    void (*pEalLogOutputWithFormatVa)   (eal_id             Tag,
                                        eal_log_level       Level,
                                        const char*         pFile,
                                        eal_u32             Line,
                                        const char*         pFormat,
                                        va_list             Args);
	void(*pEalLogSetTagName)           (eal_id             Tag,
		const char*         pTagName);
	const char* (*pEalLogGetTagName)    (eal_id Tag);
};

#if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)

////////////////////////////////////////////////////////////////////////////////////////////////////

/*!  Only defined on the DLL side. It is used to resolve dynamic functions.
    This function should be called by the DLL initalization code and must be done before any
    call to any EAL function.
    \param Interface    Structure containing valid pointers to the engine EAL functions.
    \sa EalLogDllPopulateInterface
*/
void EalLogDllInitInterface(const eal_log_dll_interface& Interface);

#else // #if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)

////////////////////////////////////////////////////////////////////////////////////////////////////

/*!  Only defined on the engine side. It is used to fill up the Interface structure.
    This function is provided by the ealdll package. It fills up the interface structure
    with pointers to the current EAL functions implemented in the engine. You can then
    pass this structure to the DLL so it will dynamicaly connect its internal EAL
    function calls to the one in your engine.
    \param Interface    A structure that will be filled up with pointers to local EAL functions.
    \sa EalFileDllMemInterface
*/
void EalLogDllPopulateInterface(eal_log_dll_interface& Interface);

#endif // #if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)

/*! @} */

#endif // #ifdef __EALLOG_H_INCLUDED