/*---------------------------------------------------------------------------*

  Copyright (C) Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

// gx2Verify.h
//

#ifndef _CAFE_GX2_VERIFY_H_
#define _CAFE_GX2_VERIFY_H_

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

/// @addtogroup GX2VerifyGroup
/// @{

/// \brief  Specifies level of severity of runtime warnings.
///

typedef enum {
    GX2_VERIFY_WARNING_NONE,       ///< Disables runtime warnings.
    GX2_VERIFY_WARNING_SEVERE,     ///< Checks and reports only on critical warnings.
    GX2_VERIFY_WARNING_MEDIUM,     ///< Checks and reports only on critical and medium-level warnings.
    GX2_VERIFY_WARNING_ALL         ///< Checks and reports on all warnings.
} GX2VerifyLevel;

/// \brief Typedef for GX2VerifyCallback.
///
/// \param file   File name where warning occurred.
/// \param level  Warning level.
/// \param line   Line number where warning is triggered.
/// \param format Format string.
///
typedef void (*GX2VerifyCallback)(const char*    file,
                                  GX2VerifyLevel level,
                                  u32            line,
                                  const char*    format,
                                                 ...);

/// \brief Used with the debug GX2 library to control the types of warnings generated at runtime.
///
/// This function is used with the debug GX2 library to control the types of warnings generated at runtime.
///
/// \param level Setting level to GX2_VERIFY_WARNING_NONE will disable all runtime warnings. <br>
///              Setting level to GX2_VERIFY_WARNING_SEVERE will print only fatal errors. <br>
///              Setting level to GX2_VERIFY_WARNING_MEDIUM will print out moderate warnings and all fatal errors. <br>
///              Setting level to GX2_VERIFY_WARNING_ALL will print out all the advice that the system has to offer. <br>
///
/// Severe warnings represent existence of illegal or unsupported GX2 setting in your code.
/// Therefore, it is recommended that you eliminate all fatal errors. Regarding other levels of warning,
/// you don't always have to take notice because some of them are generated just for reference,
/// though they might still provide useful information to debug your code.
///
/// By default, GX2Init will set level to GX2_VERIFY_WARNING_ALL in the debug version of the library.
///
/// \donotcall \fgonly \notthreadsafe \devonly \enddonotcall
///
void GX2API GX2SetVerifyLevel( GX2VerifyLevel level );

/// \brief Registers a callback that is invoked whenever a verify warning is encountered by the GX2 API (only for debug builds)
///
/// This function installs a callback that is invoked whenever a verify warning is encountered by the GX2 API (only in debug builds).
///
/// \param cb Pointer to the warning callback function.
/// \returns Pointer to a previously set callback function.
///
/// GX2 verification is enabled using GX2SetVerifyLevel. A default callback is installed by GX2Init as shown below:
/// \verbatim
//    void __GX2VerifyDefaultCallback(const char*    file,
//                                    GX2VerifyLevel level,
//                                    u32            line,
//                                    const char*    format,
//                                                   ...)
//    {
//        va_list list;
//        va_start(list, format);
//        OSReport("*** LEVEL %d WARNING at line %04d in %s: ", level, line, file);
//        vprintf(format, list);
//        va_end(list);
//        ASSERT(level != GX2_VERIFY_WARNING_SEVERE);
//    }
/// \endverbatim
/// The callback's argument file is used to specify the file in which the warning occurred. Line is the line number. Level is the level of the warning encountered.
/// Level 1 represents severe warnings, level 2 signifies medium warnings, and level 3 denotes minor warnings.
/// The argument format is a pointer to the warning format string. Be aware that the message strings are subject to change as GX2 is revised.
///
/// \donotcall \fgonly \notthreadsafe \devonly \enddonotcall
///
GX2VerifyCallback GX2API GX2SetVerifyCallback( GX2VerifyCallback cb );

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _CAFE_GX2_VERIFY_H_