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

/**
    @file 
    Defines the class PomResultStatus, which leverages both error codes and instances of status_t 
    in order to check the status of returned codes and throw exceptions if need be.
*/

/* */
#ifndef TEAMCENTER_BASE_UTILS_POMRESULTSTATUS_HXX
#define TEAMCENTER_BASE_UTILS_POMRESULTSTATUS_HXX

#include <base_utils/StatusT.hxx>
#include <base_utils/libbase_utils_exports.h>

/** 
    @brief A PomResultStatus instance is a temporary object to which both error codes and instances of status_t can be assigned.
    <br/>If, once such has been assigned, the result turns out to be a failure, the class will throw an IFail using the specified error.
    <br/>This is the main difference with ResultStatus:
    <ul>
    <li>ResultStatus uses the last error on the stack to throw the IFail
    <li>PomResultStatus uses the specified error and puts it on the error stack.
    </ul>
    
    Also, keep in mind that the operator = of this class should be used <b>ONLY</b> if the error message is of no importance or 
    if it does not contain any parameter. If this is not the case, use the constructor with parameters.

    @code
    ResultStatus ok;
    try
    {
        //NOTE: No need to check what calls have returned. 
        //      If this is an error, the ResultStatus class will ensure that an exception is thrown.
        ok = callSomeFunction();
        ok = callSomeOtherFunction(); 
        [...]
    }
    catch ( IFail& ifail )
    {
        //Handle the exception here
        [...]
    }
    @endcode
*/
class BASE_UTILS_API PomResultStatus
{
public:
    /** Default constructor */
    PomResultStatus();
    
    /**
       If the parameter @p ifail is not ITK_ok, adds the specified error 
       to the error stack and throws an IFail exception.
       
       @note Use this one if the returned error does not take any parameter
    */
    PomResultStatus( int  ifail ); //lint !e1931 <ThM> 2011-03-15 Cannot qualify as "explicit" because this conversion constructor is widely used in Teamcenter

    /**
        If the parameter @p ifail is not ITK_ok, adds the specified error 
        to the error stack and throws an IFail exception.

        @note Use this one if the returned error code takes a parameter
    */
    PomResultStatus( int  ifail,
                     const char *s1, const char *s2=0, const char *s3=0,
                     const char *s4=0, const char *s5=0, const char *s6=0,
                     const char *s7=0 ); /*  */ 
   
    /** Destructor */
    virtual ~PomResultStatus();

    /** 
        If the parameter @p ifail is not ITK_ok, adds the specified error 
        to the error stack and throws an IFail exception.
        
        @note Use this one if the returned error code does not take any parameter
    */
    PomResultStatus &  operator=( int  ifail );  /*  */ 
};

#include <base_utils/libbase_utils_undef.h>
#endif
