/* Copyright 2020 Siemens Digital Industries Software
 ==================================================
 Copyright 2020.
 Siemens Product Lifecycle Management Software Inc.
 All Rights Reserved.
 ==================================================
 Copyright 2020 Siemens Digital Industries Software */

/**
    @file

    Manufacturing Validation Check API for ME
*/ 

/** 
 
This header and its comments are oriented towards a developer writing a Validation Test Suite callback function to be registered with Teamcenter.

Additional Validation Test framework documentation available at Teamcenter Documentation Topic => reference 'TBD'

Terminology :

Validation Test Suite API : the API defined in this file that validation test suite callbacks are written to.

Validation Test Suite : A registered callback function written to the API defined by this file.
                        The validation test suite function contains one or more Validation Tests.
                        A validation test suite is registered to Teamcenter using the 'install_callback' routine.
            For example:
            install_callback -u=${TC_USER}  -pf=${TC_USER_PASSWD_FILE} -g=dba -mode=create -type=MyMfgValidationsType -library=libmymfgvalidations -function=MyValidationSuiteA -name="My Validation Suite A"
            install_callback -u=${TC_USER}  -pf=${TC_USER_PASSWD_FILE} -g=dba -mode=create -type=MyMfgValidationsType -library=libmymfgvalidations -function=MyValidationSuiteB -name="My Validation Suite B"
            The -name argument should be meaningful to the end user.

Validation Test : A subfunction within the validation test suite function that performs one validation test. 
                  Has a unique name within the Validation Test Suite.
                  The name should be meaningful to an end user.

Validation Test Framework (or Manager) : a component of the Teamcenter server.

    Communication with a Validation Test Client:
        a) Processes request for names of Validation Test Suites and contained Validation Test names.
        b) Processes request to execute Validation Test Suites or selected Validation Test(s) within a Validation Test Suite.

    Communication with a Validation Test suite function:
        a) Request a list of the contained Validation Test names from a Validation Test Suite function.
        b) Request the Validation Test Suite to run all or a subset of its Validation Tests and return the Validation Test Results. 
        Note - Can run the MfgValidationTestFramework_<clientname>_<ValidationTestSuiteTypeName>_ClosureRule on the input target objects before calling a Validation Test Suite.
                Passes found objects from closure rule to Validation Test Suite function.

Validation Test Client : Currently only EasyPlan WI.
             Can request list of Validation Test Suites and Validation Tests.
             Can request to execute a set of Validation Test Suites or Validation Tests and get associated Validation Test results.

Validation Test Framework Preferences:

    Name:  MfgValidationTestFramework_Clients
    Scope: Site and User Scope
    Type:  Array of String 
    Description : Each entry is the name of another preference of this form.
                  MfgValidationTestFramework_Client_<clientname>_ValidationTestTypes where <clientname> is a unique client identifier that communicates with the Mfg Validation Test Framework. 
          For example:
                      MfgValidationTestFramework_Client_EP_WI_ValidationTestTypes. 
          In essence the combination of these two preferences allows different clients to register with the Validation Test Framework, the Mfg Validation Test types that a client can handle. 
          Currently, a single tcserver instance can handle 'one' validation test client.
          Several client preferences can be listed with this preference but when the client requests the registered validation tests it will specify which validation client to use.

    Required: Yes 

    Name:  MfgValidationTestFramework_Client_<clientname>_ValidationTestTypes. 
    Scope: Site and User Scope
    Type:  Array of String 
    Description : Each entry is a Manufacturing Validation Test Type that this client can present and handle.
                  Each entry must match the the -type argument used during the 'install_callback' for a Validation Test Suite.
    Required: Required if specified in MfgValidationTestFramework_Clients 


    Name:  MfgValidationTestFramework_<clientname>_<ValidationTestSuiteTypeName>_ClosureRule
    Scope: Site and User Scope
    Type:  Single String 
    Description : Name of Closure Rule.
                  <ValidationTestSuiteTypeName> must match the -type argument used during the 'install_callback' for the Validation Test Suite.
          This closure rule is associated with all the manufacturing test suites of this type. This closure rule will be run by the Mfg Test Framework before executing a Validation Test Suite.
          This is a closure rule that is relevant across all validation test suites within a registered type.  Of course, each Mfg Validation Test suite can do any further traversal refinements within its own implementation. 
    Required: Optional

   
    Note: In the future the validation test client will be able to select a subset of validation tests within a validation test suite and have only those tests executed. 
          The validation test suite developer should take this into account when designing and implementing the validation test suite implementation.
*/

#ifndef ME_TEAMCENTER_MFGVALIDATIONTESTINTERFACE_HXX  
#define ME_TEAMCENTER_MFGVALIDATIONTESTINTERFACE_HXX 

#include <vector>
#include <string>
#include <map>
#include <unidefs.h>
#include <me/libme_exports.h>

/**
    @defgroup ME Manufacturing Process Planner (ME)
    @{
*/

/**
    @name Manufacturing Validation API data types
    @{
*/

/**
 A validation test can Pass or Fail or Not Applicable
 */
const int ValidationTestResult_Pass = 0;
const int ValidationTestResult_Fail = 1;
const int ValidationTestResult_NotApplicable = 2;  /* If the validation suite does not return a Pass or Fail for a validation test it is assumed to be Not Applicable */

/**
 A validation test result can have an associated message of one of the following types
 */
const int ValidationTestResultMessageType_Info = 0;
const int ValidationTestResultMessageType_Warning = 1;
const int ValidationTestResultMessageType_Error = 2;

/**
 Each selected Validation Test returns the following result. 
 */
struct ValidationTestResult
{
    std::string validationTestSuiteName;    /**< The name of the validation test suite */ 
    std::string validationTestName;         /**< The name of the Validation Test within the Validation Test Suite that was executed or skipped. */ 
    int validationTestResult;               /**< Validation Test result : Pass=0, Fail=1 or Not Applicable=2 */ 
    int messageType;                        /**< The status message type Error=0,Warning=1 or Info=2 */  
    std::string statusMessage;              /**< The contents of the status message */
};

/**
 Defines the input object and associated found objects by closure rule (if specified)
 */
typedef std::map<tag_t, std::vector<tag_t> > InputObjectToFoundObjectsMap;

/**
 Defines the tested object and its associated validation test results. 
 */
typedef std::map<tag_t, std::vector<ValidationTestResult> > TestedObjectToValidationResultsMap;

/** @} */

/**
    @name Manufacturing Validation API function definition 
    @{
*/

/**
  
 The API that Validation Test Suite functions must adhere too.
  
 The validation framework creates a key in the @p inputObjectToFoundObjectsMap for each input object sent from the validation client with an empty found objects vector. 
 If the @c MfgValidationTestFramework_<client_name>_<ValidationTestSuiteTypeName>_ClosureRule preference exist with a valid closure rule then:
 The validation framework runs this closure rule against each input target object creating a corresponding found objects vector.
 The validation framework inserts a [input object,found objects vector] entry in the map.
 */
typedef int (*validation_testsuite_callback_fn_t)
    (const InputObjectToFoundObjectsMap & inputObjectToFoundObjectsMap,  /**< (I)  The input objects and associated found objects to run validation tests against. */ 
     const std::vector<std::string> & validationTestNames,               /**< (I)  If empty the Validation Test suite function needs to populate the @p additionalInfo with the names of its Validation Tests. 
                                                                             <br/> If not empty then the Validation Test suite function needs to execute the validation tests specified.
                                                                             <br/> Currently this is all the Validation Tests with the Validation Test Suite.*/
     std::vector<std::string> & additionalInfo,                          /**< (OF) The names of the validation tests contained by the Validation Test Suite, when @p validationTestNames is empty. */ 
     TestedObjectToValidationResultsMap & validationTestResults          /**< (OF) The Validation Results per object tested.  This vector should be the same size as the input @p validationTestNames. */
    );

/** @} */


#include <me/libme_undef.h>
/** @} */
#endif
