ChunkProducer.h

Go to the documentation of this file.

/*! \file ChunkProducer.h
  \brief  The ChunkProducer class.  

  \par Copyright Information

  Copyright (c) 2012 The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBLITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef _CHUNK_PRODUCER_H_
#define _CHUNK_PRODUCER_H_

#include <string>
#include "DDD_AttributeBase.h"
#include "DDD_LogFacade.h"
#include "DDD_AttributeList.h"
#include "DDD_RevertableAttribute.h"

namespace disti
{
class DDD_AttributeDouble;
class DDD_AttributeString;
class DDD_AttributeBool;
class DDD_AttributeUInt;
class ChunkDescription;

/** A ChunkAttribute maps a specific part of a chunk to a DataDirector attribute */
class DDD_EXPORT ChunkAttribute : public DDD_AttributeObserver
{
    public:
    std::string   _name;              /**< Name of the attribute */
    unsigned int  _offset;            /**< Offset from beginning of packet */
    unsigned int  _size;              /**< Size of field in bytes */
    bool          _bigEndian;         /**< True if field is "big endian" */
    bool          _isBitfield;        /**< True if attribute is a bitfield */
    unsigned int  _bitOffset;         /**< Offset of the bitfield in bits relative to the start of this attribute (optional) */
    unsigned int  _bitLength;         /**< Length of the bitfield in bits.  (optional) */
    unsigned int  _bitMask;           /**< Bitmask computed from offset and length  (optional) */
    bool          _attributeChanged;  /**< Dirty flag used by ChunkProducers to determine if an attribute update needs to be sent */
    ChunkDescription *_chunk;         /**< Pointer to the ChunkDescription that "owns" this ChunkAttribute */

    DDD_AttributeBase::DataType _type;      /**< Representation of the data in the chunk */
    DDD_AttributeBase *_directorAttribute;  /**< Pointer to the DataDirector attribute linked 
                                                 to this attribute */
    DDD_AttributeBase *_initialValue;       /**< Initial value of field (optional) */

    /** A callback method that will be called when the attribute being observed changes 
      * if this observer has registered to be notified on attribute change
      * \param attribute  A pointer to the attribute that changed
      */
    void OnAttributeChanged(DDD_AttributeBase *attribute);

    /** Constructor */
    ChunkAttribute(ChunkDescription *chunk) :
        _directorAttribute(NULL),
        _initialValue(NULL),
        _offset(0),
        _size(0),
        _bigEndian(false),
        _bitOffset(0),
        _bitLength(0),
        _bitMask(0),
        _isBitfield(false),
        _attributeChanged(false),
        _chunk(chunk)
    {
    }

    /** Destructor */
    ~ChunkAttribute() {}
};

/** A list of ChunkAttributes */
class DDD_EXPORT ChunkAttributeList : public DynamicPtrArray<ChunkAttribute *>
{
    public:

    /** Searches for a ChunkAttribute with the given name
      * \param name  The name of the attribute to fun
      * \return A pointer to the attribute if found, NULL otherwise
      */
    ChunkAttribute *FindAttributeByName(std::string &name);

    /** Constructor */
    ChunkAttributeList() {}

    /** Destructor */
    ~ChunkAttributeList()
    {
        EmptyList();
    }
};

/** A RuleElement.  One clause of a RuleDefinition */
class DDD_EXPORT RuleElement
{
    std::string _attributeName;  /**< Name of the attribute to match */
    std::string _value;          /**< Value of the attribute to match */

    ChunkAttribute *_attr;       /**< The chunk attribute associated with this rule, cached to speed up rule checking */

public:

    /** Constructor */
    RuleElement() :
      _attr(NULL)
    {
    }

    /** Set the attribute associated with this rule
      * \param attr  The Chunk attribute associated with this rule
      * \param attrName  The name of the attribute
      * \param attrValue  The attribute value to match 
      */
    void SetAttribute(ChunkAttribute *attr,const std::string &attrName,const std::string &attrValue)
    {
        _attributeName = attrName;
        _value = attrValue;
        _attr = attr;
    }

    /** \return Gets the attribute associated with this rule
      */
    ChunkAttribute *GetAttribute() const { return _attr; }

    /** \return Gets the attribute name with this rule
      */
    std::string &GetName() { return _attributeName; }

    /** \return Gets the attribute value with this rule
      */
    std::string &GetValue() { return _value; }
};

/** A Rule definition.  A collection of RuleElements to be matched */
class DDD_EXPORT RuleDefinition
{
public:
    DynamicPtrArray<RuleElement*> _elements;  /**< The collection of rule elements making up this rule */

    /** Constructor */
    RuleDefinition() {};

    /** Destructor */
    ~RuleDefinition()
    {
        _elements.EmptyList();
    }
};

/** A Chunk Description.  A chunk has a name and a list of attributes it produces. */
class DDD_EXPORT ChunkDescription
{
public:
    std::string _name;                /**< The name of this chunk.  It will be used as the rootname for its
                                         attributes */

    std::string _type;                /**< The 'type' of this chunk (optional).  Can be used by chunk producers for whatever purpose  */

    ChunkAttributeList _attributes;   /**< The list of attributes that this chunk produces */

    RuleDefinition     *_rule;        /**< Rule for determining that this chunk is present */

    unsigned int       _packetLength; /**< (Optional).  The length of the packet/chunk.  If this is set to a value other
                                        *  than zero, then it means one of two things.
                                        *  1.  If this Chunk is part of a producer that sends messages, this is the length of
                                        *      the message that will be sent
                                        *  2.  If this Chunk is part of a producer that receives messages, the length of the 
                                        *      chunk will be validated on reception and must match this value
                                        */

    std::string _headerName;
    bool _dirty;

    /** Constructor */
    ChunkDescription() :
        _rule(NULL),
        _packetLength(0),
        _headerName(""),
        _dirty(false)
    {
    }

};

class DDD_EXPORT ChunkDescriptionList : public DynamicPtrArray<ChunkDescription*>
{
public:
    /** Find the chunk attribute by fully qualified name, e.g.
      * chunkDesc.attributeName
      * \param attributeName  The fully qualified attribute name to find
      * \return A pointer to the attribute if found, NULL otherwise
      */
    ChunkAttribute *FindAttributeByName(std::string &name);

    /** Find the specified chunk description by name
      * \param chunkName  The name of the chunk to find
      * \return A pointer to the chunk if found, NULL otherwise
      */
    ChunkDescription *FindChunkDescriptionByName(std::string &name);
};
    

/** The Chunk Producer class.  Abstract base class for other "Producers" that will produce
  * attributes for use by the UDP_Asset */
class DDD_EXPORT ChunkProducer : public DDD_AttributeContainer, public DDD_Base, public DDD_AttributeObserver
{
protected:

    /** Processes an inbound bitfield attribute update.  Performs the actual decoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the bitfield attribute
      * \param msgBuf  A buffer containing a chunk of data
      */
    void ReadBitfield(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an inbound integer attribute update.  Performs the actual decoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the integer
      * \param msgBuf  A buffer containing a chunk of data
      */
    void ReadInt(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an inbound unsigned integer attribute update.  Performs the 
      * actual decoding, byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the unsigned integer
      * \param msgBuf  A buffer containing a chunk of data
      */
    void ReadUInt(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an inbound double/float attribute update.  Performs the actual decoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the double
      * \param msgBuf  A buffer containing a chunk of data
      */
    void ReadDouble(ChunkAttribute *attr,unsigned char *msgBuf);
    
    /** Processes an inbound boolean attribute update.  Performs the actual decoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the boolean
      * \param msgBuf  A buffer containing a chunk of data
      */    
    void ReadBoolean(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an inbound string attribute update.  Strings are not byte swapped
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the string
      * \param msgBuf  A buffer containing a chunk of data
      */    
    void ReadString(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an inbound chunk and updates any connected attributes
      * \param chunk The chunk specification
      * \param msgBuf  The UDP message buffer
      * \param receivedLen  The length of the UDP message
      */
    void ReadChunk(ChunkDescription *chunk,unsigned char *msgBuf,unsigned int receivedLen);

    /** Processes an outbound bitfield attribute update.  Performs the actual encoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the bitfield attribute
      * \param msgBuf  A buffer containing a chunk of data
      */
    int WriteBitfield(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an outbound integer attribute update.  Performs the actual encoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the integer
      * \param msgBuf  A buffer containing a chunk of data
      */
    int WriteInt(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an outbound unsigned integer attribute update.  Performs the 
      * actual encoding, byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the unsigned integer
      * \param msgBuf  A buffer containing a chunk of data
      */
    int WriteUInt(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an outbound double/float attribute update.  Performs the actual encoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the double
      * \param msgBuf  A buffer containing a chunk of data
      */
    int WriteDouble(ChunkAttribute *attr,unsigned char *msgBuf);
    
    /** Processes an outbound boolean attribute update.  Performs the actual encoding,
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the boolean
      * \param msgBuf  A buffer containing a chunk of data
      */    
    int WriteBoolean(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an outbound string attribute update. Strings are not byte swapped
      * byte swapping, etc of the attribute
      * \param attr    The chunk attribute describing the string
      * \param msgBuf  A buffer containing a chunk of data
      */    
    int WriteString(ChunkAttribute *attr,unsigned char *msgBuf);

    /** Processes an outbound chunk
      * \param chunk The chunk specification
      * \param msgBuf  The UDP message buffer
      * \param receivedLen  The length of the UDP message
      */
    int WriteChunk(ChunkDescription *chunk,unsigned char *msgBuf,unsigned int maxLen);

    /** Processes an inbound message, only for printing debug information to the console. 
      * \param msgBuf  A buffer containing a message
      * \param receivedLength The length of the received message
      */
    void PrintDebugInfo(unsigned char *msgBuf,unsigned int receivedLength);

    /* Function that implements the  DDD_AttributeObserver interface
     * \param attribute  Pointer to the attribute whose value just 
     * changed
     */
    virtual void OnAttributeChanged(DDD_AttributeBase *attribute)
    {
    }

    unsigned int _packetCount;              /**< For debugging only */
    unsigned int _debugMode;                /**< 0=None, 1=Light, 2=Verbose */
    bool _checkForChangeBeforeUpdate; /**< Whether or not to check the values for change before updating the connection value */

public:

    ChunkDescriptionList _chunkDescriptions;  /** A list of chunk descriptions */

    /** Constructor */
    ChunkProducer();

    /** Destructor */
    ~ChunkProducer();

    /** Processes an inbound message, classifying it into chunks and then updating their associated
      * attributes.   Required for producers which receive messages.  Only implemented by ChunkProducers 
      * that receive data.
      * \param msgBuf  A buffer containing a message
      * \param receivedLength The length of the received message
      */
    virtual void ProcessMessage(unsigned char *msgBuf,unsigned int receivedLength) {};

    /** Builds an outbound message buffer.  Only implemented by ChunkProducers that send data.
      * \param msgBuf  A buffer to contain the message
      * \param maxMessageLength The max length of the message to build
      * \return The length of the message built or -1 if no message built
      */
    virtual int BuildMessage(unsigned char *msgBuf,unsigned int maxMessageLength, unsigned int chunkNumber) { return -1; }

    /** Find the chunk attribute by fully qualified name, e.g.
      * chunkDesc.attributeName
      * \param attributeName  The fully qualified attribute name to find
      * \return A pointer to the attribute if found, NULL otherwise
      */
    ChunkAttribute *FindAttributeByName(std::string &name);

    /** Find the specified chunk description by name
      * \param chunkName  The name of the chunk to find
      * \return A pointer to the chunk if found, NULL otherwise
      */
    ChunkDescription *FindChunkDescriptionByName(std::string &name);

    /** Swaps a 2 byte quanity into the native byte order of this machine
    * \param val  Pointer to the value to swap
    */
    static void Swap2(unsigned char *val);

    /** Swaps a 4 byte quanity into the native byte order of this machine
    * \param val  Pointer to the value to swap
    */
    static void Swap4(unsigned char *val);

    /** Swaps an 8 byte quanity into the native byte order of this machine
    * \param val  Pointer to the value to swap
    */
    static void Swap8(unsigned char *val);

    // override from DDD_AttributeContainer
    virtual const char *GetName(void) { return "ChunkProducer"; }

    /** Sets the debug mode for the chunk producer
      * \param debugMode  New debug Mode:  0=None, 1=Light, 2=Verbose 
      */
    void SetDebugMode(unsigned int debugMode) { _debugMode = debugMode; }

    /**Setter for the flag specifying whether to check for value change before updating over connections
     * \param value true = check for change before updating over connections, false = do not
     */
    void SetCheckForChangeBeforeUpdate(const bool value){_checkForChangeBeforeUpdate = value;}

    /** Perform any producer specific initialization
      */
    virtual void Start() {}

};

} // end of namespace disti
#endif