308 lines
15 KiB
C
308 lines
15 KiB
C
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
/// \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
|