qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/rtitest/test_setting.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_setting_h
#define rtitest_setting_h

/**
 * @mainpage Unit Test Framework (C and Traditional C++)
 * @brief Unit Test Framework module used to test Connext Professional. Its
 * main features are:
 * \li Provide common API for running Testers.
 * \li Simplify creating recursive TestSuites and TestCases.
 * \li Provide a suite of test asserts that can be used to write TestCases.
 */

#include "rtitest/test_log.h"
#include "rtitest/test_dll.h"
#include "rtitest/test_assert.h"
#include "rtitest/test_types.h"
#include "rtitest/test_time.h"

#define RTI_TEST_MAX_FILE_NAME_LENGTH (1024)
#define RTI_TEST_MAX_USER_LENGTH (128)

#if defined(RTI_WIN32) || defined(RTI_WINCE)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (1)
#elif defined(RTI_VXWORKS)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (99)
#elif defined(RTI_LYNX)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (18)
#elif defined(RTI_PSOS)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (101)
#elif defined(RTI_NETOS)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (16)
#elif defined(RTI_INTY)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (17)
#elif defined(RTI_QNX)
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (10)
#else
  #define RTI_TEST_RECEIVE_THREAD_PRIORITY (-9999999)
#endif /* defined(RTI_WIN32) || defined(RTI_WINCE) */

#include <stdio.h>
#ifdef __cplusplus
extern "C" {
#endif

#if defined(RTI_WINCE)
  #include <windows.h>
#endif /*#if defined(RTI_WINCE)*/


/**
 * @defgroup RTITestSetting Setup
 * @ingroup RTITest
 *
 * @brief Provides the infrastructure to set up recursive
 * module testing. See the
 * <a href="../../../manuals/unit_test_framework_users_manual/index.html">user's
 * manual</a> for examples of how to use most of these APIs.
 *
 * @details Many of the functions documented here are required to be called in
 * the main Tester and TestSuite run methods; a deep understanding of exactly
 * what they do is not needed. An example skeleton of a Tester
 * run method is as follows:
@code
RTITestReturnCode tester_run(const struct RTITestSetting *setting) {
    const char *METHOD_NAME = RTI_FUNCTION_NAME;
    RTITestReturnCode result = RTI_TEST_RETCODE_FAILED;
    RTIBool ok;
    int begin, end;
    RTITestFunction test[] = {
      // an array of test suite functions
    }

    RTITestLog_printTestName();

    // Setup
    RTITestSetting_setupWithConnext();

    if (setting->enableHeapMonitoring) {
        // Make sure this is done before any memory allocation
        RTITest_assert(RTITestSetting_enableHeapMonitoringSupport());
    }

    RTITestSetting_getRange(setting, &begin,result &end,
RTI_TEST_LEVEL_SUBMODULE);

    RTITest_assert(
            RTITestSetting_runTests(
                    setting,
                    METHOD_NAME,
                    test,
                    RTITestSetting_getTestCount(test),
                    begin,
                    end));

    result = RTI_TEST_RETCODE_PASSED;
done:

    if (setting->enableHeapMonitoring) {
        RTITestSetting_disableHeapMonitoringSupport(&ok);
        RTITest_assertAfterDone(ok);
    }

    RTITestSetting_printComplete(METHOD_NAME);
    return result;
}
@endcode
 *
 * The only difference between the above method and a TestSuite run method is
 * that a TestSuite method should not call RTITestSetting_printComplete() and
 * the fourth argument passed to RTITestSetting_getRange() should be
 * RTI_TEST_LEVEL_UNIT.
 */

/** @internal
 * \ingroup RTITestSetting
 * @brief Unique test number for describing a unit test.
 *
 * The test number of a unit test is described by both:
 * \li the number of the submodule that contains the unit test,
 * \li the number that identifies the unit test within that submodule.
 */
struct RTITestNumber {
    /* The number of the submodule that contains the unit test.  */
    int submoduleTestNumber;
    /* The number that identifies the unit test within the submodule. */
    int unitTestNumber;
};

/** @internal
 * \ingroup RTITestSetting
 * @brief The test setting specifies what tests to run and how.
 *
 * Use this structure to define the recursive behavior of a module test.
 * The \c begin and \c end fields determine the range of tests to run, the
 * remaining fields how to run them.
 *
 * Usage example:
 * \code
 * ...
 *
 * struct RTITestSetting setting;
 *
 * //run unit tests for submodules 2 -> 4 only
 * setting.begin.submoduleTestNumber = 2;
 * setting.end.submoduleTestNumber   = 4;
 *
 * //within these submodules, run all available unit tests
 * setting.begin.unitTestNumber = 0;
 * setting.end.unitTestNumber   = -1; //negative number selects all tests
 *
 * //&&& needs work
 * setting.instrumentationMask
 *
 * //Stop testing as soon as one of the unit tests fails
 * setting.ignoreFailure = 0;
 *
 * //Start the module test
 * COMMENDTester_run(&setting);
 *
 * ...
 * \endcode
 *
 * \note
 * All tests use the \c RTITestFunction function prototype and
 * are passed the same test setting information during a recursive test.
 * In order to pass additional information, derive from this class and
 * optionally provide a new implementation for \c RTITestSetting_set
 * and \c RTITestSetting_parseArgument().
 *
 * @see RTITestSetting_set
 * @see RTITestSetting_parseArgument()
 */
struct RTITestSetting {
    /*
     * if you modify this structure also modify RTI_TEST_SETTING_DEFAULT in
     * setting_impl
     */
    /*
     * Defines first submodule in range of tests and first unit test
     * within each submodule.
     * That is, if first unit test = 2, all submodule tests will start with
     * unit test 2.
     *
     * The submodule and unit test indices start at 0.
     */

    struct RTITestNumber begin;

    /*
     * Defines last submodule in range of tests and last unit test
     * within each submodule.
     * That is, if last unit test = 4, all submodule tests will only
     * run up to unit test 4 (or will stop sooner if there are not that
     * many unit tests).
     *
     * Use a negative number to run all available tests
     * (submodule and/or unit test).
     * For example, if last submodule = -1 and last unit test = 2,
     * the recursive test will enter \e all submodules and run up to
     * unit test 2 in each
     * submodule.
     */
    struct RTITestNumber end;

    /* bitmap to specify verbosity of logging &&& needs work */
    RTITestLogBitmap instrumentationMask;

    /*
     * If set to 1, all tests in specified range will be run, even if
     * one or more tests fail. If set to 0, the testing stops as soon as
     * one of the tests fails.
     */
    int ignoreFailure;

    /*
     * If set to 1, run interactive tests as well. Otherwise, skip all
     * the interactive tests. Default is 0.
     */
    int runInteractiveTest;

    /* ID used for port/multicast address calculation. Range is 0-99 */
    int id;

    /* Domain Tag used for tester isolation */
    char *tag;

    /*
     * If set to 1, tests that fail or hang when run over activeSync will not
     * be run. This is only applicable to Windows CE
     */
    int activeSync;

    /*
     * If set to 1, include tests which use external (plugin) ODBC databases.
     */
    int testOdbcDatabases;

    /*
     * If set to 1, DB and inst ini file will not be deleted after the test
     * has finished.
     */
    int keepOdbcResources;

    /*
     * The path to the odbc.ini file.
     */
    char *odbcIniPath;

    /*
     * name by which program was invoked
     */
    char *execPath;

    /*
     * Name of the database that will be tested
     * If this name is empty all databases will be tested unless
     * -noOdbcdatabase is used
     */
    const char *database;

    /*
     * If set to 1, then show the execution times for the tests(Windows and
     * Linux only).
     */
    int showTime;

    /*
     * user name
     */
    char user[RTI_TEST_MAX_USER_LENGTH];


    /*
     * The following variables are internal to test.1.0
     */

    /*
     * JUnit output file name
     */
    char _jUnitOutputFile[RTI_TEST_MAX_FILE_NAME_LENGTH + 1];

    /*
     * JUnit output file descriptor
     */
    FILE *_jUnitOutputFD;

    /*
     * Level of iteration
     */
    int _level;

    /*
     * Maximum number of times to retry a failed test.
     */
    int _maxRetries;

    /*
     * If set to 1, tests that require the RTI LAN will not
     * be run.
     */
    int noRtiLan;

    /*
     * If set to 1, tests that require files will not
     * be run.
     */
    int noTestFiles;

    /*
     * If set to 1, tests that require writing to files will not be run.
     */
    int noWritableFileSystem;

    /*
     * If set to 1, the test range runs forever. Useful to reproduce crashes.
     */
    int repeatTests;

    /* It specifies the number of times the tests are going to be run */
    unsigned int numberOfRepeats;

    /*
     * If set to non-negative integer, it will overwrite all hardcoded retry
     * values to this value. By default, it is -1 to indicate to use user
     * specified value. The value overwritten will be numRetries in
     * RTITestSetting_retryIfFailed(... , numRetries)
     */
    int globalIndividualUnitTestRetryCount;

    /*
     * A placeholder for custom parameters. This member contains the value
     * provided as part of the -option argument. The value is treated as an
     * string and it is up to the client to interpret it.
     */
    const char *option;

    /*
     * When set to 1, heap monitoring will be enabled.
     */
    int enableHeapMonitoring;

    /*
     * When set to 1, network capture will be enabled.
     */
    int enableNetworkCapture;

    /*e
     * When set to 1, a leak analysis will be run per test when using
     * Valgrind. Requires to build with PLATFORM_SUPPORT_VALGRIND_PER_TEST=ON
     */
    int valgrindPerTest;

    /*
     * When set to 1, detection of unexpected participants will be activated
     * when a test fails if possible
     */
    int detectInterferingParticipants;

    /**
     * @brief When set to RTI_TRUE, leak sanitizer check is performed between
     * tests.
     */
    RTIBool enableLeakSanitizerCheck;

    /**
     * @brief When set to RTI_TRUE, a test will fail if a leak is found.
     */
    RTIBool failOnLeak;
};

/** @internal
 * \ingroup RTITestSetting
 * @brief Initializes an \c RTITestSetting structure.
 *
 * This function is mainly used for platforms that do
 * not support a \e main() entry point (e.g. VxWorks).
 *
 * &&& is this function implemented ??? &&&
 *
 * @pre valid args
 *
 * @post setting packed
 *
 * @param setting \b In. "this".
 * @param beginSubmodule \b In. The module to start at.
 * @param beginUnit \b In. The test within the beginSubmodule to start at.
 * @param endSubmodule \b In. The module to finish at.
 * @param endUnit \b In. The test within the endSubmodule to finish at.
 * @param submodMask \b In. Bitmap of the modules to log.
 * @param instMask \b In. how much information do you want from the
 * module under test?
 * @param ignoreFailure \b In. 0 if you want the test to halt on first
 * encountered failure, 1 if you want the test to keep despite failure.
 * @param id \b In. ID used for port/multicast address calculation.
 * Range is 0-99
 * @param runInteractive \b In. 0 i fyou do not want to run the
 * interactive test.
 *
 * @see RTITestSetting_parseArgument
 */
extern RTITestDllExport void RTITestSetting_set(
        struct RTITestSetting *setting,
        int beginSubmodule,
        int beginUnit,
        int endSubmodule,
        int endUnit,
        RTITestLogBitmap submodMask,
        RTITestLogBitmap instMask,
        int ignoreFailure,
        int id,
        int runInteractiveTest);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Parses a string to initialize an \c RTITestSetting structure.
 *
 * This function is meant to be used only in VxWorks DKMs, in the non-main
 * entrypoint functions, as a wrapper function for \e
 * RTITestSetting_parseArgument(). It process the given string to convert it
 * into an argv array of strings and calls \e RTITestSetting_parseArgument(). \e
 * args can be a NULL pointer, meaning no options provided and resulting in \e
 * settings unchanged.
 *
 * Example usage:
 *
 * \code
 * int entrypoint_function(char *args)
 * {
 * struct RTITestSetting setting;
 *
 * //initialize setting with default values
 * RTITestSetting_init(&setting);
 *
 * //overwrite some of the default values with command-line arguments
 * RTITestSetting_parseArgumentFromString(&setting, args);
 * 
 *  
 * } 
 * \endcode
 *
 * @pre \e setting valid, non-NULL pointer.
 * @post \e setting struct updated with command-line arguments.
 *
 * @param setting \b Out. "this" pointer. The command-line arguments
 * will be written to this RTITestSetting struct.
 * @param args \b In. First parameter of main() entry point.
 *
 * @return 1 if parsing was successful, 0 otherwise.
 *
 * @see RTITestSetting_parseArgument
 */
extern RTITestDllExport int RTITestSetting_parseArgumentFromString(
        struct RTITestSetting *setting,
        char *args);

/**
 * \ingroup RTITestSetting
 *
 * @brief Parses command-line arguments to initialize an \c RTITestSetting
 * structure.
 *
 * This function is only useful on platforms supporting \e main() as the
 * entry point.
 *
 * Example usage:
 *
 * \code
 * int main(int argc, char **argv)
 * {
 *     struct RTITestSetting setting;
 *
 *     //initialize setting with default values
 *     RTITestSetting_init(&setting);
 *
 *     //overwrite some of the default values with command-line arguments
 *     RTITestSetting_parseArgument(&setting, argc, argv));
 *
 *     return tester_run(&setting) == RTI_TEST_RETCODE_PASSED ?  0 : -1;
 * }
 * \endcode
 *
 * Run your program with the argument \c -help to check the available arguments
 * and a brief description of the effect of each of them.
 *
 * \c RTITestSetting_parseArgument() automatically prints a
 * usage message if it cannot successfully parse all command-line arguments.
 * @pre \e setting and \e argv valid, non-NULL pointers.
 * @post \e setting struct updated with command-line arguments.
 *
 * @param setting \b Out. "this" pointer. The command-line arguments
 * will be written to this RTITestSetting struct.
 * @param argCount \b In. First parameter of main() entry point.
 * @param argv \b In. Second parameter of main() entry point.
 *
 * @return 1 if parsing was successful, 0 otherwise.
 *
 * @see RTITestSetting_set
 */
extern RTITestDllExport RTIBool RTITestSetting_parseArgument(
        struct RTITestSetting *setting,
        int argCount,
        char **argv);

#if defined(RTI_WINCE)

/** @internal
 * \ingroup RTITestSetting
 * @brief Parses command-line arguments to initialize an \c RTITestSetting
 * structure.
 *
 * This function is only useful on platforms supporting \e wmain() as the
 * entry point. Hence, this function is specific to Windows CE, which passes
 * command-line arguments in wchar instead of char. This function converts the
 * arguments to char and calls RTITestSetting_parseArgument.
 *
 * For more details, refer to description of RTITestSetting_parseArgument
 *
 * \c RTITestSetting_parseWcharArgument automatically prints a usage message
 * if it cannot succesfully parse all command-line arguments.
 *
 * @pre \e setting and \e argv valid, non-NULL pointers.
 * @post \e setting struct updated with command-line arguments.
 *
 * @param setting \b Out. "this" pointer. The command-line arguments
 * will be written to this RTITestSetting struct.
 * @param argCount \b In. First parameter of main() entry point.
 * @param argv \b In. Second parameter of main() entry point.
 *
 * @return 1 if parsing was successful, 0 otherwise.
 *
 * @mtsafety
 *
 * @see RTITestSetting_set
 */
extern RTITestDllExport int RTITestSetting_parseWcharArgument(
        struct RTITestSetting *setting,
        int argCount,
        wchar_t **argv);

#endif /* RTI_WINCE */

/** @internal
 * \ingroup RTITestSettingClass
 * @brief Recursive test levels supported.
 *
 * The current implementation supports two test
 * levels for recursive testing of each module:
 * \li Unit test level
 * \li Submodule test level
 *
 * When setting up a recursive test, the \c setting variable
 * specifies the range of tests to run at each test level.
 * Use \c RTITestLevel to extract the information for
 * a given test level.
 *
 * Please refer to the code samples in the \ref RTITestSetting
 * overview for some examples.
 *
 * @see RTITestSetting_getRange
 */
typedef enum {
    RTI_TEST_LEVEL_UNIT,
    RTI_TEST_LEVEL_SUBMODULE
} RTITestLevel;

/**
 * @ingroup RTITestSetting
 *
 * @brief Given the test setting and the test level, this function extracts
 * the index of the first and last test at that level.
 *
 * The test setting contains the \e begin and \e end test numbers, both
 * at the unit test and submodule test level. This function extracts
 * those numbers. Use the \e currentLevel parameter to specify which level
 * you need the information for.
 *
 * @post \e begin and \e end contain the index of the first and last test to be
 * run.
 *
 * @param setting \b In. "this" pointer. The test setting that contains the
 * info.
 * @param begin \b Out. Pointer to begin answer.
 * @param end \b Out. Pointer to end answer.
 * @param currentLevel \b In. Level at which the info must be obtained.
 *
 * @see RTITestSetting_runTests
 */
extern RTITestDllExport void RTITestSetting_getRange(
        const struct RTITestSetting *setting,
        int *begin,
        int *end,
        RTITestLevel currentLevel);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Check if the range option was provided to the tester
 * @param begin \b In. The range value corresponding to begin.
 * @param end \b In. The range value corresponding to end.
 *
 * @return RTI_TRUE if a value other than -1 is specified for either begin or
 * end, RTI_FALSE otherwise.
 */
extern RTITestDllExport RTIBool
RTITestSetting_isRangeSpecified(int begin, int end);

/**
 * \ingroup RTITestSetting
 *
 * @brief Function prototype for all tests.
 *
 * All tests (module test, submodule test or unit test) use this function
 * prototype. This allows grouping them in arrays for recursive
 * execution.
 *
 * The \c RTITestSetting parameter is specified at the module test
 * level and passed down via the submodule tests to the unit tests.
 *
 * @pre \e Setting is a valid, non-NULL pointer.
 *
 * @post One or more aspects of the module have been fully tested.
 * All system resources must have been returned to their pre-condition
 * state. For example, malloc() is allowed, but the memory must be freed
 * finally, regardless of success or failure.
 *
 * @param setting \b In. Pointer to the test setting information.
 *
 * @return 1 on success, 0 otherwise.
 *
 * @exception up to the implementer.
 */
typedef RTITestReturnCode (*RTITestFunction)(
        const struct RTITestSetting *setting);

/**
 * @ingroup RTITestSetting
 *
 * @brief Given a set of tests and a test setting, run a subset of these tests
 * with that test setting.
 *
 * The set of tests is passed as an array of \c RTITestFunction function
 * pointers. The subset of tests to run is specified as a range of
 * array indices, from index \e begin to index \e end.
 *
 * Negative indices in the range are interpreted as first and last test
 * respectively. All other indices outside of the array bounds are
 * ignored.
 *
 * @post All tests from index \e begin to end in array \e test ran and passed.
 *
 * @param setting \b In. "this". Run applicable tests with this setting (passed
 * as a parameter to each test).
 * @param methodName \b In. Name of the module or submodule that is firing
 * off the batch test. Used for generating warning or error messages.
 * @param test \b In. Array of tests, as function pointers.
 * @param testCount \b In. Size of the test array. This includes any NULL
 * entries, which will be skipped.
 * @param begin \b In. The array index of the first test to run. A negative
 * number will be set to zero.
 * @param end \b In. The array index of the last test to run. A negative number
 * will be set to \e testCount-1.
 *
 * @return 1 if all tests in the specified range passed or if the
 * range is empty, 0 otherwise.
 *
 * @see RTITestSetting_getRange
 */
extern RTITestDllExport RTITestReturnCode RTITestSetting_runTests(
        const struct RTITestSetting *setting,
        const char *methodName,
        const RTITestFunction *test,
        int testCount,
        int begin,
        int end);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Similar to RTITestSetting_runTests but takes in two sets of tests,
 * a minimal set of tests that can be used to validate a feature and a complete
 * set.
 *
 * These two lists should be dijoint--no tests should be repeated on the two
 * lists.
 *
 * If the setting->minimalSetOnly is true and no range is specficied by the user
 * then only the testMinimal set is run, otherwise testMinimal is run followed
 * by testComplete.
 */
extern RTITestDllExport RTITestReturnCode RTITestSetting_runTestsExt(
        const struct RTITestSetting *setting,
        const char *methodName,
        const RTITestFunction *testBasic,
        int testCountBasic,
        const RTITestFunction *testAdditional,
        int testCountAdditional,
        int begin,
        int end);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Global variable which is temporarily changed for the duration
 * of a specific unit test which will repeat a that unit test
 * individualUnitTestRetryCount until it succeeds.
 */
extern RTITestDllVariable int RTITestSetting_g_individualUnitTestRetryCount;

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief function to be called at the beginning of a unit test in order
 * to repeat that unit test if it fails.
 * @param setting - RTITestSetting object passed to each unit
 * test run function.
 * @param numRetries - maximum number of times to retry a specific
 * unit test if it fails.
 */
extern RTITestDllExport void RTITestSetting_retryIfFailed(
        const struct RTITestSetting *setting,
        int numRetries);

/**
 * \ingroup RTITestSetting
 *
 * @brief Printout to indicate completion of a Tester
 */
extern RTITestDllExport void RTITestSetting_printComplete(const char *methodName);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Gets the full path name of the relative resource file name.
 *
 * The resource directory is assumed to be two levels up from the executable
 * file directory. i.e. ../../resource/\<relativePathFileName>
 *
 * The maximum length of fullPathFileName must be at least
 * RTI_TEST_MAX_FILE_NAME_LENGTH
 *
 * The full path name is the concatenation of
 *
 * argv[0] + /../../resource/\<relativePathFileName>
 */
extern RTITestDllExport RTIBool RTITestSetting_getFullResourcePathFileName(
        const struct RTITestSetting *setting,
        char *fullPathFileName,
        const char *relativeResourcePathFileName);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Same as RTITestSetting_getFullResourcePathFileName, but without
 * assuming that the resource directory is two levels up from the executable.
 * The resource directory is passed as a relative path to the tester executable
 * in the resourceRelativePath parameter.
 */
extern RTITestDllExport RTIBool RTITestSetting_getFullResourcePathFileNameEx(
        const struct RTITestSetting *setting,
        char *fullPathFileName,
        const char *resourceRelativePath,
        const char *relativeResourcePathFileName);

/** @internal
 * @ingroup RTITestSettingClass
 *
 * @brief Log a message stating that network capture is not supported in this
 * tester.
 */
extern RTITestDllExport
void RTITestSetting_logNetworkCaptureNotSupportedMessage(void);

#ifndef RTI_TEST_EXAMPLE_RELATIVE_PATH
  #ifdef RTI_ANDROID
    #define RTI_TEST_EXAMPLE_RELATIVE_PATH "/sdcard/example"
  #else
    #define RTI_TEST_EXAMPLE_RELATIVE_PATH "../../example"
  #endif
#endif

#ifndef RTI_TEST_RESOURCE_RELATIVE_PATH
  #ifdef RTI_ANDROID
    #define RTI_TEST_RESOURCE_RELATIVE_PATH "/sdcard/resource"
  #else
    #define RTI_TEST_RESOURCE_RELATIVE_PATH "../../resource"
  #endif
#endif

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Gets the full path name of the relative example file name.
 *
 * The example directory is assumed to be two levels up from the executable
 * file directory. i.e. ../../example/\<relativePathFileName>
 *
 * The maximum length of fullPathFileName must be at least
 * RTI_TEST_MAX_FILE_NAME_LENGTH
 *
 * The full path name is the concatenation of
 *
 * argv[0] + /../../example/\<relativePathFileName>
 */
extern RTITestDllExport RTIBool RTITestSetting_getFullExamplePathFileName(
        const struct RTITestSetting *setting,
        char *fullPathFileName,
        const char *relativeExamplePathFileName);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Same as RTITestSetting_getFullExamplePathFileName, but without
 * assuming that the example directory is two levels up from the executable.
 * The example directory is passed as a relative path to the tester executable
 * in the exampleRelativePath parameter.
 */
extern RTITestDllExport RTIBool RTITestSetting_getFullExamplePathFileNameEx(
        const struct RTITestSetting *setting,
        char *fullPathFileName,
        const char *exampleRelativePath,
        const char *relativeExamplePathFileName);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Gets the full path name of the executable from RTITestSetting.
 *
 * The maximum length of fullPathFileName must be at least
 * RTI_TEST_MAX_FILE_NAME_LENGTH
 *
 * The full path name is
 *
 * setting.execPath - \<executableName>
 */
extern RTITestDllExport RTIBool RTITestSetting_getExecutableFullPathFileName(
        const struct RTITestSetting *setting,
        char *fullPathFileName);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Returns RTI_TRUE if the tester can open files
 */
extern RTITestDllExport RTIBool
RTITestSetting_fileTestIsSupport(const struct RTITestSetting *setting);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Returns RTI_TRUE if the tester can write files
 */
extern RTITestDllExport RTIBool
RTITestSetting_fileSystemIsWritable(const struct RTITestSetting *setting);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Create a file in the folder of the module of the unit test.
 * @param setting \b In. Setting for the unit test.
 * @param fullPathFileName \b Out. Name of the file created (including the
 *  whole path).
 * @param relativeFileName \b In. Proposed file name.
 * @param fileAccessMode \b In. File access mode
 *
 * @return This function returns a FILE pointer. Otherwise, NULL is returned.
 */
extern RTITestDllExport FILE *RTITestSetting_createTempFile(
        const struct RTITestSetting *setting,
        char *fullPathFileName,
        const char *relativeFileName,
        const char *fileAccessMode);

/**
 * \ingroup RTITestSetting
 * @brief Fill setting with default values.
 * @details Override the values you are interested in after
 *          this. This function should be called in the test executable main
 *          function before RTITestSetting_parseArgument().
 *
 * @pre valid arg
 * @param setting \b Out. The setting to initialize
 *
 * @see RTITestSetting_parseArgument() for an example usage.
 */
extern RTITestDllExport void RTITestSetting_init(
        struct RTITestSetting *setting);

/** @internal
 * \ingroup RTITestSetting
 *
 *  @brief Get a temporary filename.
 *
 *  The filename is obtained by concatenation of:
 *  fileNamePrefix | address of fileName | fileSuffix
 *
 *  @pre filename should be initialized. If not this function will invoke
 *  undefined behavior.
 *
 *  @param fileName \b in/out. Output file name.
 *
 *  @param fileNameMaxSize \b in. Total size allocated for the fileName.
 *
 *  @param filePrefix \b in. fileName will start with this prefix.
 *
 *  @param fileSuffix \b in. fileName will end with this suffix. It is usually
 *  its file extension.
 *
 *  @return RTI_TRUE if the temporary filename was created successfully and
 *  RTI_FALSE otherwise.
 */
extern RTITestDllExport RTIBool RTITestSetting_getTempFileName(
        char *fileName,
        size_t fileNameMaxSize,
        const char *filePrefix,
        const char *fileSuffix);

/** @internal
 * \ingroup RTITestSetting
 *
 * @brief Returns RTI_TRUE if the test is configured with
 * useLowMemoryParticipantQos set to 1 or if the architecture is a part of
 * MINIMAL_VALIDATION_ARCHITECTURES. Returns RTI_FALSE otherwise.
 */
extern RTITestDllExport
RTIBool RTITestSetting_isLowMemoryParticipantQosSetting(void);

/** @internal
 * \ingroup RTITestSetting
 * @brief Returns RTI_TRUE if the architecture being compiled is part of the
 * MINIMAL_VALIDATION_ARCHITECTURES as defined in test.1.0/config.mk or if the
 * test is configured with runMinimalSet set to 1.
 * Returns RTI_FALSE otherwise.
 */
extern RTITestDllExport
RTIBool RTITestSetting_isMinimalValidationArchitecture(void);

/** @internal
 * \ingroup RTITestSetting
 * @brief Returns RTI_TRUE if:
 *   - The architecture being compiled is part of the
 *     EXTENDED_VALIDATION_ARCHITECTURES as defined in test.1.0/config.mk
 *   - The build mode is release.
 * Or if the test is configured with runExtendedSet set to 1.
 * Returns RTI_FALSE otherwise.
 */
extern RTITestDllExport
RTIBool RTITestSetting_isExtendedValidationArchitecture(void);

/** @internal
 * \ingroup RTITestSetting
 * @brief Returns RTI_TRUE if the architecture being compiled is part of the
 * CORE_BASICPUBSUB_VALIDATION_ARCHITECTURES as defined in test.1.0/config.mk or
 * if the test is configured with coreValidationOnly set to 1. Returns RTI_FALSE
 * otherwise.
 */
extern RTITestDllExport
RTIBool RTITestSetting_isCoreBasicPubSubValidationArchitecture(void);

/** @internal
 * \ingroup RTITestSetting
 * @brief Returns 1 if the user has chosen to disable shmem.
 * Returns 0 otherwise.
 */
extern RTITestDllExport
RTIBool RTITestSetting_disableShmem(void);

/**
 * @ingroup RTITestSetting
 * @brief Enables heap monitoring support.
 *
 * @details When the command-line option -enableHeapMonitoring
 * is used, the field enableHeapMonitoring in the RTITestSetting
 * structure will be set to RTI_TRUE. The tester_run function in
 * a module should call this API to enable support for heap
 * monitoring. For example:
 *
@code
    if (setting->enableHeapMonitoring) {
        // Make sure this is done before any memory allocation
        RTITest_assert(RTITestSetting_enableHeapMonitoringSupport());
    }
@endcode
 *
 * The function must be called at the very beginning of the test before
 * doing any DDS calls.
 *
 * If the function is not called and the command-line option
 * enableHeapMonitoring is used, the test will fail indicating that heap
 * monitoring has not been enabled.
 */
extern RTITestDllExport int RTITestSetting_enableHeapMonitoringSupport(void);

/**
 * @ingroup RTITestSetting
 * @brief Disables heap monitoring support and checks if there are memory leaks.
 *
 * When the command-line option enableHeapMonitoring is used,
 * this function must be called at the end of a tester_run
 * function in a module to disable support for heap monitoring.
 *
 * For example
 * @code
if (setting->enableHeapMonitoring) {
    RTITestSetting_disableHeapMonitoringSupport(&ok);
}
 * @endcode
 * If there are memory leaks, ok is set to RTI_FALSE and an exception is logged.
 *
 * @param ok \b Out. It will be set to 0 if there are memory leaks.
 *
 * @see RTITestSetting_enableHeapMonitoringSupport()
 */
extern RTITestDllExport void RTITestSetting_disableHeapMonitoringSupport(int *ok);

/**
 * @internal
 * @ingroup RTITestSettingClass
 *
 * @brief Global variable that stores the filename prefix to use for network
 * capture. It must be populated by RTITestSetting_parseArgument with the value
 * given by the user after -enableNetworkCapture.
 */
extern RTITestDllVariable
char RTITestSetting_g_networkCaptureFileNamePrefix[
        RTI_TEST_MAX_FILE_NAME_LENGTH];

/**
 * @ingroup RTITestSettingClass
 * @brief Enables network capture support.
 *
 * @details When the command-line option enableNetworkCapture is used, the
 * Tester_run function in a module should call this API to enable support for
 * network capture and start capturing traffic for all DomainParticipants. The
 * default capture options are to capture all traffic (including shared memory)
 * and configure security to parse encrypted messages and submessages. The
 * prefix for the capture files comes from the input the user passes when
 * setting the command-line option -enableNetworkCapture.
 *
 * The function must be called at the very beginning of the test before
 * doing any DDS calls.
 *
 * If the function is not called and the command-line option
 * enableNetworkCapture is used, the test will fail indicating that network
 * capture has not been enabled.
 *
 * @param ok \b Out. It will be set to RTI_FALSE if enabling or starting
 * network capture fails.
 */
extern RTITestDllExport
void RTITestSetting_enableAndStartNetworkCaptureSupport(RTIBool *ok);

/**
 * @ingroup RTITestSettingClass
 *
 * @brief Disables network capture support.
 *
 * When the command-line option enableNetworkCapture is used, this function must
 * be called at the end of a Tester_run function in a module to stop capturing
 * traffic and disable support for network capture.
 *
 * @param[out] RTITestReturnCode It will be set to RTI_TEST_RETCODE_FAILED if
 * stopping or disabling network capture fails.
 */
extern RTITestDllExport
void RTITestSetting_stopAndDisableNetworkCaptureSupport(
        RTITestReturnCode *result);

/**
 * @ingroup RTITestSetting
 * @brief Get the number of tests in the test array
 */
#define RTITestSetting_getTestCount(testArray) \
  (sizeof((testArray)) / sizeof(RTITestFunction))

/** @internal
 * @ingroup RTITestSetting
 * @brief Get the domain Id to use for the test
 */
#define RTITestSetting_getDomainId(setting) \
  ((setting->id == 0) ? TEST_DOMAIN : setting->id)

/**
 * @ingroup RTITestSetting
 * @brief Get the current number of retries.
 * @details The \c maxRetries option allows you to retry a failed test until it
 * succeeds or until the maximum retry number specifed with this argument is
 * reached. This function returns the current number of times a test has been
 * retried so far. A value of zero means that the test is being run for the
 * first time.
 */
extern RTITestDllExport int RTITestSetting_getCurrentNumberOfRetries(void);

/************************************ Setup ***********************************/

/** @internal
 * @ingroup RTITestSetting
 * @brief Checks if test module setup is initialized.
 * @return RTI_TRUE if test module setup is initialized, RTI_FALSE otherwise.
 */
extern RTITestDllExport RTIBool RTITestSetting_isSetupInitialized(void);

/** @internal
 * @ingroup RTITestSetting
 * @brief Initializes test module setup.
 */
extern RTITestDllExport void RTITestSetting_initializeSetup(void);

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

#include "rtitest/test_setting_impl.h"

#endif /* rtitest_setting_h */