IEventReceiver.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \defgroup GrpEventReceiver Using EventReceiver
/// @{
/// \ingroup GrpTestUtils 
/// \brief Support for event processing of test events
/// Class IEventReceiver defines an interface to which any kind of test events
/// (e.g. protocol entries, detected errors,...) can be passed.
///
/// \sa IEventReceiver.h (File documentation)
/// \sa TestToolBox::IEventReceiver (interface documentation)
/// \sa TestToolBox::EventReceiverStdOut (simple receiver class writing to stdout)
///
////////////////////////////////////////////////////////////////////////////////

#pragma once

#include "TestToolBox\CommonSources\CommonDefinitions.h"

#pragma warning( push )
#pragma warning( disable : 4996 ) // vsprintf declared deprecated


namespace TestToolBox
{
    /// \brief Context info which may optionally be available for a TestEvent.
    /// The values may be combined to a bit combination
    enum EventContext
    {
        CTX_NO_CONTEXT        = 0x8000,  ///< context not specified\n\n

        CTX_TIMEOUT_ELAPSED   = 0x0001,  ///< multiple bits can be set
        CTX_TOO_MANY_EVENTS   = 0x0002,  ///< multiple bits can be set
        CTX_UNEXPECTED_EVENTS = 0x0004,  ///< multiple bits can be set\n\n

        CTX_PROT               = 0x0008, ///< only one bit of this group should be set
        CTX_INFO               = 0x0010, ///< only one bit of this group should be set
        CTX_WARNING            = 0x0020, ///< only one bit of this group should be set
        CTX_ERROR              = 0x0040, ///< only one bit of this group should be set
        CTX_FATAL_ERROR        = 0x0080, ///< only one bit of this group should be set
        CTX_TEST_EVENT         = 0x0100,  ///< only one bit of this group should be set\n\n

        CTX_ALL                = 0xfff8,  ///< filter mask
        CTX_ONLY_ERROR         = CTX_ERROR | CTX_FATAL_ERROR ///< filter mask
    };


    // ----------  Interface IEventReceiver  ----------

    /// \brief This interface is used to convert a textual TestEvent into a message
    /// suitable for the specific test environment (e.g. within Boost test
    /// a Boost macro will be called)
    /// \nosubgrouping 
    struct IEventReceiver
    {
        /// Constructor
        IEventReceiver()
        : m_splitAtNewLine(false)
        {}

        /// Signal actual event as occured during test execution
        virtual void EventMsg(
            EventContext in_context,
            const char*  in_eventDescription) = 0;

        //---------------------------------------------------------------
        /// \name Convenience functions
        /// Convenience functions to allow printf formating of output,
        /// automatic supply of context param and usage of std::string
        /// \{


        /// Supply context and char*
        virtual void Event(
            EventContext in_context,
            const char*  in_eventDescription, ...)
        {
                UTIL_GET_FORMATTED_LINE_NO_NEWLINE (in_eventDescription);
                SplitLineAndAddPrefixIfNeeded(in_context, formattedLine);
        };

        /// Supply char*
        virtual void Event(
            const char* in_eventDescription, ...)
        {
                UTIL_GET_FORMATTED_LINE_NO_NEWLINE (in_eventDescription);
                SplitLineAndAddPrefixIfNeeded(CTX_NO_CONTEXT, formattedLine);
        };

        /// Supply context and std::string
        virtual void Event(
            EventContext      in_context,
            std::string const in_eventDescription)
        {
            SplitLineAndAddPrefixIfNeeded(in_context, in_eventDescription);
        }

        /// Supply std::string
        virtual void Event(
            std::string const in_eventDescription)
        {
            SplitLineAndAddPrefixIfNeeded(CTX_NO_CONTEXT, in_eventDescription);
        }

        /// \brief Optionally add a prefix to the test events
        ///
        /// A prefix can be added when writing the test script to enable simply copying
        /// from test output to test script (e.g. "TTB_EXP" leads to
        /// event entry "TTB_EXP(MyEventString);" instead of "MyEventString")
        void SetEventPrefix (std::string const & in_eventPrefix)
        {m_eventPrefix = in_eventPrefix;}

        /// \brief Optionally a given event string can be split into several events
        /// using newline as separator
        void SetSplitAtNewLine (bool in_split)
        {m_splitAtNewLine = in_split;}

        /// \}

    ///\cond
 
    // TODO later: move to separate impl class?
    protected:
        std::string m_eventPrefix;
        bool m_splitAtNewLine;

        std::string AddPrefix (
            std::string const & in_eventDescription)
        {
            if (m_eventPrefix.empty()) return in_eventDescription;

            std::string eventStr = m_eventPrefix + "(\"" + in_eventDescription + "\");";
            return eventStr;
        }

        void SplitLineAndAddPrefixIfNeeded (
            EventContext        in_context,
            std::string const & in_eventDescription)
        {
            if (m_splitAtNewLine)
            {
                StringPosition curPos;
                EventContext context = in_context;
                while (GetNextLineStr(in_eventDescription, curPos))
                {
                    EventMsg(context, AddPrefix(curPos.m_lineStr).c_str());
                    // remaining lines are marked as info
                    context = CTX_INFO;
                }
            }
            else
            {
                EventMsg(in_context, AddPrefix(in_eventDescription).c_str());
            }

        }
        struct StringPosition
        {
            explicit StringPosition (
                std::string::size_type in_pos = 0)
            : m_curPos  (in_pos)
            , m_lastPos (in_pos)
            , m_lineStr ()
            {}

            std::string::size_type m_curPos;
            std::string::size_type m_lastPos;
            std::string            m_lineStr;
        };

        static bool GetNextLineStr (
            std::string const & in_stringWithNewLines,
            StringPosition &    io_current)
        {
               if (io_current.m_lastPos == std::string::npos) return false;

               io_current.m_curPos = in_stringWithNewLines.find_first_of( '\n', io_current.m_lastPos);
               io_current.m_lineStr = in_stringWithNewLines.substr(io_current.m_lastPos,
                   io_current.m_curPos - io_current.m_lastPos);

               if (io_current.m_curPos != std::string::npos)
                   io_current.m_lastPos = io_current.m_curPos + 1;
               else
                   io_current.m_lastPos = std::string::npos;

               return true;
        }

    ///\endcond
        // ToDo / possible extension:
        // Add helper class here to support output with stream operators
    };

}; // namespace TestToolBox

#pragma warning( pop )

/// @} // end group GrpEventReceiver

---