Language.h

Go to the documentation of this file.

/*
    Copyright (C) 2010-2012
    Johannes Feuser <feuser@uni-bremen.de>
    This file is part of the openETCS library.

    The openETCS library is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    any later version.

    The openETCS library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with the openETCS library.  If not, see <http://www.gnu.org/licenses/>.
*/

/*!
 *  \author Johannes Feuser <feuser@uni-bremen.de>
 *  \brief language classes
 */

#ifndef __OETCS_DF_LANGUAGE_H__
#define __OETCS_DF_LANGUAGE_H__




#include <map>
#include "Configuration.h"
#include "Error/ExceptionTypes.h"
#include <string>
#include <vector>
#include "Storage.h"


namespace oETCS { namespace UT { class CLanguage; }  }

namespace oETCS { namespace DF { class CEVCStateMachine; }  } 
namespace oETCS { namespace DF { class CBitFlow; }  } 


namespace oETCS {

namespace DF {


/*!
 *  \brief base class for all language structure classs
 */
class CLanguage 
{
  public:
    /*!
     *  \brief general constructor
     *
     *  \param[in] pStateMachine pointer to the parent EVC state machine
     */
    explicit CLanguage(oETCS::DF::CEVCStateMachine * const pStateMachine) throw();
    
    

    /*!
     *  \brief destructor
     */
    virtual ~CLanguage() throw();
    
    


}; // class CLanguage



/*!
 *  \brief class for holding variable values
 */
class CVariable : public oETCS::DF::CLanguage 
{
  public:
    /*!
     *  \brief enum type for the physical unit type of a variable
     */
    enum UNIT_T 
    {
        /*!
         *  \brief seconds as physical unit
         */
        SECONDS = 0,

        /*!
         *  \brief km/h as physical unit
         */
        KILO_METERS_PER_HOUR = 1,

        /*!
         *  \brief meters as physical unit
         */
        METERS = 2,

        /*!
         *  \brief centi meters as physical unit
         */
        CENTI_METERS = 3,

        /*!
         *  \brief per mill as physical unit (unit less)
         */
        PER_MILL = 4,

        /*!
         *  \brief plain integer as physical unit (unit less)
         */
        INTEGER = 5,

        /*!
         *  \brief plain double as physical unit (unit less)
         */
        DOUBLE = 6,

        /*!
         *  \brief plain string as physical unit (unit less)
         */
        STRING = 7


    }; // enum UNIT_T
    

    /*!
     *  \brief general constructor
     *
     *  Parameterises the Packet with all constant members.
     *  The Packet object takes over the posession of all variables/memory
     *  passed by pointer.
     *
     *  \param[in] pStateMachine pointer to parent EVC state machine
     *  \param[in] iResolution numerical resolution
     *  \param[in] eUnit physical unit
     *  \param[in] bIsConditional       optional flag for an conditional iterator
     *  \param{in] lConditionalValue    optional value used for the conditional iterator
     *  \param[in] ValueMap             optional map of values
     */
    explicit CVariable(oETCS::DF::CEVCStateMachine * const pStateMachine, const unsigned int & iResolution, const UNIT_T & eUnit, const unsigned long & lSize, const bool & bIsConditional = false, const long & lConditonalValue = 0, const ::std::map< VARIABLE_VALUE_VECTOR_T, CVariable * >& ValueMap = ::std::map< VARIABLE_VALUE_VECTOR_T, CVariable * >()) throw();
    
    

    /*!
     *  \brief deleted copy constructor
     *
     */
    CVariable(const CVariable& Source) = delete;
    
    

    virtual ~CVariable() throw();
    
    

    /*!
     *  \brief calculates the value
     *
     *  Calculates the real value, including value map and scaling, 
     *  and stores it in the storage object under m_pValueStorage, if
     *  available.
     */
    void Calculate() throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief gets the size of the variable depending on the value stored
     *
     *  \return size of the variable in bits
     */
    unsigned long GetSize() const throw();
    
    

    /*!
     *  \brief sets explicitly the value of a variable by a string
     *
     *  \param[in] Value new value as string
     */
    void SetValue(const ::std::string& Value) throw();
    
    

    /*!
     *  \brief streaming operator for filling a telegram with raw data
     *
     *  \param[in] Bits vector of boolean holding the the exact amount of bit raw data in little endian format
     */
    CVariable& operator<<(const ::std::vector< bool >& Bits) throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief streaming operator for getting the raw data in a variable
     *
     *  \param[out] Bits vector of boolean holding the bit raw data in little endian format
     *  \return               reference to this instance
     */
    CVariable& operator>>(::std::vector< bool >& Bits) throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief deleted assignment operator
     *
     */
    CVariable & operator=(const CVariable & Source) = delete;
    
    

    /*!
     *  \brief convertion method
     *  
     *  Converts a string (encoded by a prefix) to the
     *  value vector type used by language variables.\n\n
     *  Prefixes:\n
     *  d - double value
     *  s - string value
     *  i - integer value
     *      all other - binary value
     *
     *  \param[in] Value string with the value to convert
     *  \return           converted value vector
     */
    static oETCS::DF::VARIABLE_VALUE_VECTOR_T StringToValueVector(const ::std::string& Value) throw();
    
    

    /*!
     *  \brief fixed resolution of a variable
     */
    const unsigned int m_iResolution;
    
    

    /*!
     *  \brief unit of variable value
     */
    const UNIT_T m_eUnit;
    
    

    /*!
     *  \brief size of the variable in bit
     */
    const unsigned long m_lSize;
    
    


  private:
    /*!
     *  \brief vector as bit storages for the value of a variable
     *
     *  Index 0 (m_Value[0]) is the LSB.
     */
    ::std::vector< oETCS::DF::VARIABLE_VALUE_T > m_Value;
    
    

    /*!
     *  \brief iteration factor
     *
     *  Defines how many times a variable object is iterated.
     */
    unsigned int m_iIterated;
    
    

    /*!
     *  \brief scalar factor
     *
     *  Is multiplied with any numerical result of the value calculation
     */
    double m_dFactor;
    
    

    /*!
     *  \brief flag for variable being a conditional iterator
     */
    const bool m_bConditionalIterator;
    
    

    /*!
     *  \brief conditional value used, if conditional operator
     */
    const long m_lConditionalValue;
    
    


  public:
    /*!
     *  \brief vector of pointers to bit flows to storages
     */
    ::std::vector< oETCS::DF::CBitFlow* > m_BitValues;
    
    

    /*!
     *  \brief vector with pointers to allvariable objecst which are scaled by this instance
     */
    ::std::vector< CVariable* > m_ScaledVariables;
    
    

    /*!
     *  \brief vector with pointers to all variables which are iterated by this instance
     */
    ::std::vector< CVariable* > m_IteratedVariables;
    
    


  private:
    /*!
     *  \brief optional map of certain byte values to predefined variables
     */
    const ::std::map< oETCS::DF::VARIABLE_VALUE_VECTOR_T, CVariable* > m_ValueMap;
    
    


// only include the following, if unit test framework is available
#ifdef __HAS_UNIT_TEST__

  friend class ::oETCS::UT::CLanguage;

#endif // #ifdef __HAS_UNIT_TEST__

}; // class CVariable : public oETCS::DF::CLanguage



/*!
 *  \brief class for holding packet information
 */
class CPacket : public oETCS::DF::CLanguage 
{
  public:
    /*!
     *  \brief general constructor
     *
     *  Parameterises the Packet with all constant members.
     *  The Packet object takes over the posession of all variables/memory
     *  passed by pointer.
     *
     *  \param[in] pStateMachine pointer to parent EVC state machine
     *  \param[in] cID unique numerical ID of the packet
     *  \param[in] Variables optional vector with pointers to all packets supported
     */
    explicit CPacket(oETCS::DF::CEVCStateMachine * const pStateMachine, const unsigned char & cID, const ::std::vector< oETCS::DF::CVariable * >& Variables = ::std::vector< oETCS::DF::CVariable* >(0)) throw();
    
    

    /*!
     *  \brief deleted copy constructor
     */
    CPacket(const CPacket & Source) = delete;
    
    

    /*!
     *  \brief destructor
     */
    virtual ~CPacket() throw();
    
    

    /*!
     *  \brief gets the size of the packet depending on the variables stored
     *
     *  \return size of the packet in bits
     */
    unsigned long GetSize() const throw();
    
    

    /*!
     *  \brief streaming operator for filling a telegram with raw data
     *
     *  Bits consumed for packet and underlying variabke reconstruction are
     *  removed from bit stream vector.
     *  The first sizeof(m_cID) bytes are compared with m_cID. If unequal,
     *  the complete bit stream will be ignored.
     *
     *  \param[inout] Bits vector of boolean holding the bit raw data in little endian format
     */
    CPacket& operator<<(::std::vector< bool >& Bits) throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief streaming operator for getting the raw data in a packet
     *
     *  \param[out] Bits vector of boolean holding the bit raw data in little endian format
     *  \return               reference to this instance
     */
    CPacket& operator>>(::std::vector< bool >& Bits) throw();
    
    

    /*!
     *  \brief deleted assignment operator
     */
    CPacket operator=(const CPacket& Source) = delete;
    
    

    /*!
     *  \brief numerical unique ID of a packet
     */
    const unsigned char m_cID;
    
    


  private:
    /*!
     *  \brief vector with pointers to all possible included variables in their order
     */
    ::std::vector< oETCS::DF::CVariable* > m_Variables;
    
    


// only include the following, if unit test framework is available
#ifdef __HAS_UNIT_TEST__

  friend class ::oETCS::UT::CLanguage;

#endif // #ifdef __HAS_UNIT_TEST__

}; // class CPacket : public oETCS::DF::CLanguage



/*!
 *  \brief class for holding telegram information
 */
class CTelegram : public oETCS::DF::CLanguage 
{
  public:
    /*!
     *  \brief general constructor
     *
     *  Parameterises the Telegram with all constant members.
     *  The Telegram object takes over the posession of all variables/memory
     *  passed by pointer.
     *
     *  \param[in] pStateMachine pointer to parent EVC state machine
     *  \param[in] Header vector with pointers to all variables used as header
     *  \param[in] Packets vector with pointers to all packets supported
     */
    CTelegram(oETCS::DF::CEVCStateMachine * const pStateMachine, const ::std::vector< oETCS::DF::CVariable * >& Header, const ::std::vector< oETCS::DF::CPacket * >& Packets) throw();
    
    

    /*!
     *  \brief deleted copy constructor
     *
     */
    CTelegram(const CTelegram& Source) = delete;
    
    

    /*!
     *  \brief destructor
     */
    virtual ~CTelegram() throw();
    
    

    /*!
     *  \brief gets the size of the telegram depending on the packets stored
     *
     *  \return size of the telegram in bits
     */
    unsigned long GetSize() const throw();
    
    

    /*!
     *  \brief streaming operator for filling a telegram with raw data
     *
     *  \param[in] Bits vector of boolean holding the bit raw data in little endian format
     *  \return              vector with used ETCS Language Packet IDs found
     */
    ::std::vector< unsigned char > operator<<(const ::std::vector< bool >& Bits) throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief streaming operator for getting the raw data in a telegram
     *
     *  \param[out] Bits vector of boolean holding the bit raw data in little endian format
     *  \return               reference to this instance
     */
    CTelegram& operator>>(::std::vector< bool >& Bits) throw();
    
    

    /*!
     *  \brief deleted assignment operator
     */
    CTelegram & operator=(const CTelegram & Source) = delete;
    
    


  private:
    /*!
     *  \brief vector with pointers to all possible included packets
     */
    ::std::vector< oETCS::DF::CPacket* > m_Packets;
    
    

    /*!
     *  \brief vector with pointers to all variables defining the header of a telegram
     */
    const ::std::vector< oETCS::DF::CVariable* > m_Header;
    
    


// only include the following, if unit test framework is available
#ifdef __HAS_UNIT_TEST__

  friend class ::oETCS::UT::CLanguage;

#endif // #ifdef __HAS_UNIT_TEST__

}; // class CTelegram : public oETCS::DF::CLanguage





} // namespace oETCS::DF

} // namespace oETCS

#endif // __ OETCS_DF_LANGUAGE_H__