qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/rtitest/test_log.h

/*
 * (c) Copyright, Real-Time Innovations, 2002-2022.
 * All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef rtitest_log_h
#define rtitest_log_h

#include "rtitest/test_types.h"
#include "rtitest/test_dll.h"
#include "rtitest/test_connext_interface.h"
#include <stdlib.h>

/**
 * @defgroup RTITestLogging Logging
 * @brief The tests themselves may output logging. When running a
 * test, the test logs use a separate, and simplified,
 * infrastructure from the modules being tested. It is up to the
 * unit test writer to use these APIs consistently.
 * RTITestLogger_log and derived macros are the main logging
 * APIs to be used in tests, but RTITestConnextLogger_log and
 * derived macros can be used instead if Connext logging's
 * features are needed within the test.
 * @see RTITestConnextClass.
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup RTITestLogBitmapClass Log Bitmap
 * @ingroup RTITestLogging
 * @brief Several definitions to handle Unit Test Framework verbosity with high
 * granularity.
 */

typedef unsigned int RTITestLogBitmap;

struct RTITestLogMessage {
    const char *format;
};

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log all fatal errors.
 */
#define RTI_TEST_LOG_BIT_FATAL_ERROR (0x00000001U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log all exceptions.
 */
#define RTI_TEST_LOG_BIT_EXCEPTION (0x00000002U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log all warnings.
 */
#define RTI_TEST_LOG_BIT_WARN (0x00000004U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log what is happening due to local object creation and destruction.
 */
#define RTI_TEST_LOG_BIT_LOCAL (0x00000008U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log what is happening due to what other applications (not necessarily
 * on another host, but in different address space) are creating and destroying.
 */

#define RTI_TEST_LOG_BIT_REMOTE (0x00000010U)
/**
 * @ingroup RTITestLogBitmapClass
 * @brief Log periodic activities. This bit is used for periodic activities,
 * such as sending a packet. Disabling this type of log message can
 * significantly reduce logging output.
 */
#define RTI_TEST_LOG_BIT_PERIODIC (0x00000020U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Default verbosity. Only fatal errors and exceptions will be printed.
 */
#define RTI_TEST_LOG_BITMAP_DEFAULT \
  (RTI_TEST_LOG_BIT_FATAL_ERROR | RTI_TEST_LOG_BIT_EXCEPTION)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Empty verbosity. Don't log anything.
 */
#define RTI_TEST_LOG_BITMAP_NONE (0x00000000U)

/**
 * @ingroup RTITestLogBitmapClass
 * @brief Current log bitmap.
 */
extern RTITestDllVariable RTITestLogBitmap RTITestLog_g_instrumentationMask;

#ifdef RTI_LINUX
  #define RTI_TEST_CHECK_FORMAT_STRING_PARAMETERS(mirrorFunc__, format__, args__) \
    __attribute__((format(mirrorFunc__, format__, args__)))
#else
  #define RTI_TEST_CHECK_FORMAT_STRING_PARAMETERS(mirrorFunc__, format__, args__)
#endif

/** @internal
 * @ingroup RTITestLogging
 * @brief Internal log function. It should be used from the macros that
 * calls it, not directly.
 */
extern RTITestDllExport void RTITestLogger_logMessage(
        const char *method,
        const struct RTITestLogMessage *logMessage,
        const char *parameterizedString,
        ...) RTI_TEST_CHECK_FORMAT_STRING_PARAMETERS(printf, 3, 4);

/**
 * @ingroup RTITestLogging
 * @brief Sets current log verbosity based on the provided 
 *        bitmap. See RTITestLog_setBitmapsFromVerbosity() as an
 *        alternative.
 *  
 * @details For example, to log error and warning logs: 
 * @code 
 * RTITestLog_setBitmaps( 
 *         RTI_TEST_LOG_BIT_EXCEPTION | RTI_TEST_LOG_BIT_WARN);
 * @endcode 
 *  
 * @param instrumentationMask \b In. RTITestLogBitmap that defines the desired
 * verbosity level. See @ref RTITestLogBitmapClass.
 */
extern RTITestDllExport void RTITestLog_setBitmaps(
        RTITestLogBitmap instrumentationMask);

/**
 * @ingroup RTITestLogging
 * @brief Gets current log verbosity.
 * @param instrumentationMask \b Out. Current log verbosity 
 *        level. See @ref RTITestLogBitmapClass.
 */
extern RTITestDllExport void RTITestLog_getBitmaps(
        RTITestLogBitmap *instrumentationMask);

/**
 * @defgroup RTITestLogVerbosityClass Log Verbosity
 * @ingroup RTITestLogging
 * @brief Several definitions to handle Unit Test Framework verbosity.
 */

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Nothing will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_NONE (0U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Only fatal errors will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_FATAL (1U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Fatal errors and exceptions will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_EXCEPTION (2U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Fatal errors, exceptions, and warnings will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_WARNING (3U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Fatal errors, exceptions, warnings, and local messages will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_LOCAL (4U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Fatal errors, exceptions, warnings, and local and remote messages will
 * be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_REMOTE (5U)

/**
 * @ingroup RTITestLogVerbosityClass
 * @brief Fatal errors, exceptions, warnings, and local, remote, and periodic
 * messages will be logged.
 */
#define RTI_TEST_LOG_VERBOSITY_PERIODIC (6U)

/**
 * @ingroup RTITestLogging
 * @brief Sets log verbosity from a number, enabling several bitmaps at
 * the same time. See the RTI_TEST_LOG_VERBOSITY macros in 
 * @ref RTITestLogVerbosityClass for mapping to the bitmaps. 
 * This is a convenience function that calls 
 * RTITestLog_setBitmaps() internally. 
 * @param verbosity \b In. Desired verbosity. Increment the verbosity by 1 to
 * enable the next instrumentation bit. See @ref 
 * RTITestLogVerbosityClass for possible values. 
 */
extern RTITestDllExport void RTITestLog_setBitmapsFromVerbosity(
        unsigned int verbosity);

/** @internal
 * @ingroup RTITestLogging
 * @brief Provides the functionality of snprintf by calling
 * va_start, vsnprintf, and va_end.
 * @param str \b Out. Pointer to a buffer where the resulting
 * C-string is stored. The buffer should have a size of at least
 * n characters.
 * @param n \b In. Maximum number of bytes to be used in the buffer.
 * The generated string has a length of at most n-1, leaving
 * space for the additional terminating NUL.
 * @param format \b In. C string that contains a format string.
 * @param ... \b In. Additional arguments.
 * @return the result of vsnprintf.
 */
extern RTITestDllExport int RTITestLog_snprintf(
        char *str,
        size_t size,
        const char *format,
        ...);

#ifdef __cplusplus
} /* extern "C" */
#endif

#include "rtitest/test_log_msg.h"
/* pick up hidden performance boosting macros */
#include "rtitest/test_log_impl.h"

#endif /* rtitest_log_h */