NQMessage.cpp

Go to the documentation of this file.

// Message.cpp: implementation of the CNQMessage class.
//
#define __NQ_INTERNAL_SW__

#include "PlatformSW.h"
#include <assert.h>
#include "NQDeclarations.h"
#include "NQLogging.h"
#include "NQMessage.h"

#include <stdio.h>

// Construction/Destruction

CNQMessage::CNQMessage()
{
    clear();
}


CNQMessage::~CNQMessage()
{
    // not meaningful, but I'll do it anyway
    clear();
}

//
// CNQMessage::isRequest()
//
//  This method checks whether the CNQMessage contains a Request, which means nothing
//  more than the mandatoryPhysicalPacketType is set to REQUEST_PHYS.
//
//  Return codes:
//      true:   yes, it is a Request
//      false:  no Request
//
bool CNQMessage::isRequest() const
{
    if (mandatoryPhysicalPacketType == NQ_PT_REQUEST) return true;

    return false;
}

//
// CNQMessage::isResponse()
//
//  This method checks whether the CNQMessage contains a Response, which means nothing
//  more than the mandatoryPhysicalPacketType is set to RESPONSE_PHYS.
//
//  Return codes:
//      true:   yes, it is a Response
//      false:  no Response
//
bool CNQMessage::isResponse() const
{
    if (mandatoryPhysicalPacketType == NQ_PT_RESPONSE) return true;
    
    return false;
}

//
// CNQMessage::isTelegram()
//
//  This method checks whether the CNQMessage contains a Telegram, which means nothing
//  more than the mandatoryPhysicalPacketType is set to TELEGRAM_PHYS.
//
//  Return codes:
//      true:   yes, it is a Telegram
//      false:  no Telegram
//
bool CNQMessage::isTelegram() const
{
    if (mandatoryPhysicalPacketType == NQ_PT_TELEGRAM) return true;

    return false;
}


//
// CNQMessage::setType()
//
//  This method sets logical and physical packet/message types together into 
//  the appropriate private variables.
//
//
void  CNQMessage::setType( UINT8 aPhysicalType, UINT8 aLogicalType)
{
    mandatoryLogicalPacketType = aLogicalType;
    mandatoryPhysicalPacketType = aPhysicalType;
}

//
// CNQMessage::getLogicalType()
//
//  This method returns the logical type of the message. In case no type
//  is set, NQ_LT_NONE is returned (see Declarations.h)
//
UINT8 CNQMessage::getLogicalType()
{
    return mandatoryLogicalPacketType;
}

//
// CNQMessage::getLogicalType()
//
//  This method returns the physical type of the message. In case no type
//  is set, NQ_PT_NONE is returned (see Declarations.h)
//
UINT8 CNQMessage::getPhysicalType()
{
    return mandatoryPhysicalPacketType;
}

//
// CNQMessage::getSenderIPandPort()
//
//  This method checks whether the CNQMessage was received from remote peer and if yes,
//  returns ip and port of the remote peer.
//
//  Return codes:
//      true:   ip and port of remote peer are returned
//      false:  this is no CNQMessage that came from remote peer
//
//  Remarks:
//      In case of false the references ip_peer_hostorder and port_peer_hostorder are left untouched.
//
bool CNQMessage::getSenderIPandPort( UINT32 &ip_peer_hostorder, UINT16 &port_peer_hostorder )
{
    if (message_came_from_set == false) return false;

    ip_peer_hostorder = message_came_from_ip;
    port_peer_hostorder = message_came_from_port;

    return true;
}


//
// CNQMessage::clear()
//
//  This method clears all contents (reset contents to default values) inside the CNQMessage object.
//
//  This function is always successful.
//
void CNQMessage::clear()
{
    message_came_from_set = false;
    
    internalPacketMagic = NQ_PACKET_MAGIC_TOP;
    internalPacketVersion = 0x1;
    internalPacketSpecialBits = NQ_PACKET_SPECIAL_BITS_DEFAULT_VALUE;
    internalPacketTail = NQ_PACKET_MAGIC_TAIL;
    mandatoryPhysicalPacketType = NQ_PT_NONE;
    mandatoryLogicalPacketType = NQ_LT_NONE;
    notifySemaphoreOnReceiveAnswer = NQ_NO_SEMAPHORE;
    notifySemaphoreOnReceiveAck = NQ_NO_SEMAPHORE;

    payload_maxlength_net = NQ_MAX_PACKET_SIZE - (NQ_SIZE_MESSAGE_FILL_STUFF+NQ_SIZE_PACKET_FILL_STUFF); 
    
    payload_curlength_net = 0;
    payload_num_elements = 0;
    payload_buffer_left = (NQ_MAX_NUM_ENTRIES*NQ_MIN_SIZE_DATA)+NQ_SIZE_ADD_LINKEDLIST;

    payload_first_offset = -1;
}

//
// CNQMessage::check_int()
//
//  This method checks the contents of the message contained in this CNQMessage object
//  for correctness and completeness.
//
//  The return codes are:
//
//       0 - everything okay, valid
//      -1 - packet magic top invalid
//      -2 - packet magic tail invalid
//      -3 - packet version is not supported
//      -4 - packet align filler does not contain the defined value
//      -5 - no proper physical message type set
//      -6 - no proper logical type for request or response set
//      -7 - no proper logical type for telegram set
//      -8 - net data (nettodaten) too big
//
INT32 CNQMessage::check_int() const
{
    if (internalPacketMagic != NQ_PACKET_MAGIC_TOP) return -1;
    if (internalPacketTail != NQ_PACKET_MAGIC_TAIL) return -2;
    if ((internalPacketVersion&NQ_PACKET_VERSIONS_SUPPORTED) == 0) return -3;
    
    // if all valid bits are masked out and still bits are set, something is wrong
    if ((internalPacketSpecialBits&NQ_PACKET_SPECIAL_BITS_VALID_MASK) != 0) return -4;

    if ((mandatoryPhysicalPacketType != NQ_PT_REQUEST) &&
        (mandatoryPhysicalPacketType != NQ_PT_RESPONSE) &&
        (mandatoryPhysicalPacketType != NQ_PT_TELEGRAM)) return -5;
    
    if ((mandatoryPhysicalPacketType == NQ_PT_REQUEST) || (mandatoryPhysicalPacketType == NQ_PT_RESPONSE))
    {
        if ((mandatoryLogicalPacketType != NQ_LT_GET) &&
            (mandatoryLogicalPacketType != NQ_LT_PUT) &&
            (mandatoryLogicalPacketType != NQ_LT_CALL)) return -6;
    }

    if (mandatoryPhysicalPacketType == NQ_PT_TELEGRAM) 
    {
        if ((mandatoryLogicalPacketType != NQ_LT_TRAP) &&
            (mandatoryLogicalPacketType != NQ_LT_UPDATE)) return -7;
    }

    if (payload_curlength_net > payload_maxlength_net) return -8;

    return 0;
}


//
// CNQMessage::check_bool()
//
//  This method is a convenience method replacement for check_int. Instead of a dedicated return code,
//  true (message valid) or false (message invalid) is returned.
//
bool CNQMessage::check_bool() const
{
    if (check_int() == 0) return true; 
    else 
        return false;
}


//
// CNQMessage::isAckPacket()
//
//  This method checks whether the CNQMessage contains a 'ack' packet. 
//
//  Return codes:
//      true:   yes, it is an ACK packet
//      false:  no, it is no ack packet
//
bool CNQMessage::isAckPacket() const
{
    if ((internalPacketSpecialBits&NQ_PACKET_BIT_IS_ACKPACKET) == 0) return false;

    return true;
}

//
// CNQMessage::wantAckPacket()
//
//  This method checks whether the CNQMessage wants an ack packet as guaranteed 
//  delivery response.
//
//  Return codes:
//      true:   yes, an ACK packet is wanted
//      false:  no ACK packet is wanted
//
bool CNQMessage::wantAckPacket() const
{
    if ((internalPacketSpecialBits&NQ_PACKET_BIT_WANT_ACK) == 0) return false;

    return true;
}

//
// CNQMessage::matchAckPacket()
//
//   This method checks whether the passed parameter 'ack packet' is a valid ack packet to the 
//    CNQMessage contents.
//
//  Parameters:
//  [IN]    ack_packet      'ack packet' received that should be compared to the CNQMessage 
//
//  Return codes:
//      true:   The passed parameter is a valid ACK packet for the object's contents
//      false:  The passed parameter is NOT a valid ACK packet for the object's contents
//
//  Remark:
//
// An ACK packet is basically the same packet as the packet that wanted to have an ACK,
// just naturally the packet_size, packet_special_bits and num_of_datablocks are different
// because an ACK packet does NOT have data set appended
//
bool CNQMessage::matchAckPacket(const CNQMessage &ack_packet)
{
    bool is_ack = true;

    if ((internalPacketSpecialBits&NQ_PACKET_BIT_WANT_ACK) == 0)    { is_ack = false; goto end; }
    if ((ack_packet.internalPacketSpecialBits&NQ_PACKET_BIT_IS_ACKPACKET) == 0) { is_ack = false; goto end; }
    
    if (ack_packet.internalPacketMagic != internalPacketMagic) { is_ack = false; goto end; }
    if (ack_packet.internalPacketVersion != internalPacketVersion) { is_ack = false; goto end; }
    if (ack_packet.optAuthorisationID != optAuthorisationID) { is_ack = false; goto end; }
    
    if (ack_packet.internalRequestID != internalRequestID) { is_ack = false; goto end; }
    if (ack_packet.optSubsystemDeviceID != optSubsystemDeviceID) { is_ack = false; goto end; }
    if (ack_packet.mandatoryPhysicalPacketType != mandatoryPhysicalPacketType) { is_ack = false; goto end; }
    if (ack_packet.optPacketTypeParam != optPacketTypeParam) { is_ack = false; goto end; }
    if (ack_packet.mandatoryLogicalPacketType != mandatoryLogicalPacketType) { is_ack = false; goto end; }
    if (ack_packet.optPacketTypeParam != optPacketTypeParam) { is_ack = false; goto end; }
    if (ack_packet.internalPacketTail != internalPacketTail) { is_ack = false; goto end; }

end:
    return is_ack;

}

//
// CNQMessage::constructAckPacket()
//
//  This method constructs inside the object an appropriate 'ack' packet to react on the CNQMessage
//  that wants to have an ACK returned which is passed in 'template_packet').
//
//  Parameter:
//  [IN]    template_packet     received CNQMessage that wants to have an 'ack' response
//
//  This function is always successful.
//
void CNQMessage::constructAckPacket(const CNQMessage &template_packet)
{
    clear();

    internalPacketSpecialBits = 0;
    internalPacketSpecialBits |= NQ_PACKET_BIT_IS_ACKPACKET;

    internalPacketMagic = template_packet.internalPacketMagic;
    internalPacketVersion = template_packet.internalPacketVersion;
    optAuthorisationID = template_packet.optAuthorisationID;
    
    internalRequestID = template_packet.internalRequestID;
    optSubsystemDeviceID = template_packet.optSubsystemDeviceID;
    mandatoryPhysicalPacketType = template_packet.mandatoryPhysicalPacketType;
    mandatoryLogicalPacketType = template_packet.mandatoryLogicalPacketType;
    optPacketTypeParam = template_packet.optPacketTypeParam;
    internalPacketTail = template_packet.internalPacketTail;
}

//
// CNQMessage::ExportMessageToPacketBuffer()
//
//  This method is used by CNetworkQueue method SendProcessTask in order to encode the 
//  logical message representation inside CNQMessage object into a physical packet representation
//  that can be send out using the network.
//
//  Parameters:
//  [IN]    buffer          pointer to a memory location in order to put the physical packet contents
//  [I/O]   buffer_length   IN: maximum length of buffer in bytes
//                          OUT: real buffer length (size of packet to be sent) in bytes
//  Return codes:
//      true:   message was encoded into buffer
//      false:  message was not encoded into buffer
//
//  Remark:
//      In case of error (return: false), neither the memory location behind buffer 
//      was changed nor the buffer_length parameter was adjusted.
//
bool CNQMessage::ExportMessageToPacketBuffer(UINT8 *buffer, INT32 &buffer_length)
{
    const UINT8 *buffer8orig = (UINT8 *) buffer;
    UINT8  *buffer8 = (UINT8 *) buffer;

    if (buffer == NULL) return false;

    internalPacketSize = NQ_SIZE_MESSAGE_FILL_STUFF+NQ_SIZE_PACKET_FILL_STUFF+payload_curlength_net;

    if (buffer_length < internalPacketSize ) return false;

    platform_put_uint16_at( buffer8, internalPacketMagic);
    platform_put_uint16_at( buffer8+2, internalPacketSize);
    platform_put_uint16_at( buffer8+4, internalPacketVersion);
    platform_put_uint16_at( buffer8+6, internalPacketSpecialBits);

    platform_put_uint32_at( buffer8+8, optAuthorisationID);

    platform_put_uint16_at( buffer8+12, internalPacketIndex);
    platform_put_uint16_at( buffer8+14, internalRequestID);
    platform_put_uint16_at( buffer8+16, optSubsystemDeviceID);
    platform_put_uint16_at( buffer8+18, payload_num_elements); // num_datablocks

    platform_put_uint8_at( buffer8+20, mandatoryPhysicalPacketType); 
    platform_put_uint8_at( buffer8+21, mandatoryLogicalPacketType); 

    platform_put_uint16_at( buffer8+22, optPacketTypeParam);

    buffer8 += 24;

    if (payload_num_elements > 0)
    {
        UINT8 *pdp; // PayloaDPointer
        UINT32 payload_next = payload_first_offset;

        for (int i=0;i<payload_num_elements;i++)
        {
            pdp = &payload_buffer[payload_next];

            if (i>0)
                assert(payload_next>0);

            UINT16 gross_size;
            //UINT16 vartype;

            payload_next = platform_get_uint32_at(pdp);
            gross_size = platform_get_uint16_at(pdp+4);

            memcpy(buffer8, pdp+4, gross_size);
            buffer8+=gross_size;

            pdp = &payload_buffer[payload_next];
        }
    }

    platform_put_uint16_at(buffer8, internalPacketTail);

    buffer_length = (UINT32) (buffer8+2 - buffer8orig); // +2 == UINT16(packet_tail)
    
    
    if (buffer_length != internalPacketSize)
    {
        NQ_DBG(("Buffer length(%d) != packet_size(%d)\n", buffer_length, internalPacketSize));
        NQ_DBG(("payload_curlength_net(%d) payload_num_elements(%d)\n", payload_curlength_net, payload_num_elements));
    }
    // for safety
    assert( buffer_length == internalPacketSize);

    return true;
}

//
// CNQMessage::ImportMessageFromPacketBuffer()
//
//  This method is used by CNetworkQueue method ReceiveProcessTask in order to decode the 
//  physical packet representation (as received by recv() call) into a logical message representation 
//  inside CNQMessage object that can be used further.
//
//  Parameters:
//  [IN]    buffer          pointer to a memory location in order to get the physical packet contents from
//  [IN]    buffer_length   length of 'buffer' in bytes
//                          
//  Return codes:
//      true:   success: message was decoded out of buffer
//      false:  failure: message was not decoded out of buffer (invalid message)
//
//  Remark:
//      In case of any return code assume that the contents of the CNQMessage object could have changed!
//
bool CNQMessage::ImportMessageFromPacketBuffer(const UINT8 *buffer, INT32 buffer_length, UINT32 ip_hostorder, UINT16 port_hostorder)
{
    INT32 pdl=0; // packet_data_length
    UINT8  *buffer8 = (UINT8 *) buffer;
    UINT8  *l_packet_data;

    // !!! buffer into local variables first (validity check!!!)
    pdl = buffer_length - (NQ_SIZE_MESSAGE_FILL_STUFF+NQ_SIZE_PACKET_FILL_STUFF);
    
    if (pdl < 0 || pdl > payload_maxlength_net)
    {
        return false;
    }

    internalPacketMagic = platform_get_uint16_at(buffer8);
    internalPacketSize = platform_get_uint16_at(buffer8+2);

    if (internalPacketSize != buffer_length) return false;

    internalPacketVersion = platform_get_uint16_at(buffer8+4);
    internalPacketSpecialBits = platform_get_uint16_at(buffer8+6);

    optAuthorisationID = platform_get_uint32_at(buffer8+8);

    internalPacketIndex = platform_get_uint16_at(buffer8+12);
    internalRequestID = platform_get_uint16_at(buffer8+14);
    optSubsystemDeviceID = platform_get_uint16_at(buffer8+16);
    payload_num_elements = platform_get_uint16_at(buffer8+18);

    mandatoryPhysicalPacketType = platform_get_uint8_at(buffer8+20);
    mandatoryLogicalPacketType = platform_get_uint8_at(buffer8+21);

    optPacketTypeParam = platform_get_uint16_at(buffer8+22);

    buffer8 += 24;
    l_packet_data = buffer8;
    buffer8 += pdl;
    payload_curlength_net = pdl;

    internalPacketTail = platform_get_uint16_at(buffer8);

    // check whether packet is valid
    if (check_bool() == false ) return false;

    payload_first_offset = -1;
    UINT8 *pdp = &payload_buffer[0];
    const UINT8 *pdp_end = (&payload_buffer[(NQ_MAX_NUM_ENTRIES*NQ_MIN_SIZE_DATA)+NQ_SIZE_ADD_LINKEDLIST-1]);

    UINT8 *source_buffer = l_packet_data;
    // last_good_byte!
    UINT8 *source_buffer_end = l_packet_data+buffer_length-(NQ_SIZE_MESSAGE_FILL_STUFF+NQ_SIZE_PACKET_FILL_STUFF);

    // bound checking and error handling could still be improved
    //  but frozen because meaningfulness is fulfilled
    // data treated in here comes from the network, dont trust nothing!!!

    if (payload_num_elements > 0)
    {
        for (int i=0;i<payload_num_elements;i++)
        {
            UINT32 payload_next;
            UINT16 blocksize;
            UINT16 vartype;
            UINT16 varid;
            UINT16 net_size;

            if (payload_first_offset == -1) 
            {
                payload_first_offset = 0;
            }

            blocksize = platform_get_uint16_at(source_buffer);
            
            // meaningful blocksize is anything below
            // payload network length
            assert( blocksize <= pdl );
            if (blocksize > pdl) return false;
    
            // meaningful varid is any valid number
            varid = platform_get_uint16_at(source_buffer+2);

            // meaningful vartype is anything between NQ_MIN_VARTYPE and NQ_MAX_VARTYPE
            vartype = platform_get_uint16_at(source_buffer+4);
            assert( (vartype >= NQ_MIN_VARTYPE) && (vartype <= NQ_MAX_VARTYPE));
            if ((vartype < NQ_MIN_VARTYPE) || (vartype > NQ_MAX_VARTYPE)) return false;

            net_size = sizeof_per_element(vartype)*(platform_get_uint16_at(source_buffer+6));

            payload_next = pdp + blocksize + 4 - payload_buffer;

            if (i == (payload_num_elements-1)) payload_next = 0;

            assert( (pdp+blocksize+4) <= pdp_end );
            if ((pdp+blocksize+4) > pdp_end) return false;

            platform_put_uint32_at(pdp, payload_next);
            platform_put_uint16_at(pdp+4, blocksize);
            

            // varid, vartype, net_size(amount), net_size(data)
            memcpy(pdp+6, source_buffer+2, net_size+6);
            
            source_buffer+=blocksize;

            assert( source_buffer <= source_buffer_end );
            if (source_buffer > source_buffer_end) return false;

            pdp = &payload_buffer[payload_next];
            
            // only continue if size is not exhausted
            assert( payload_next <= ((NQ_MAX_NUM_ENTRIES*NQ_MIN_SIZE_DATA)+NQ_SIZE_ADD_LINKEDLIST) );
            if (payload_next > ((NQ_MAX_NUM_ENTRIES*NQ_MIN_SIZE_DATA)+NQ_SIZE_ADD_LINKEDLIST)) return false;
        }
    }

    notifySemaphoreOnReceiveAnswer = NQ_NO_SEMAPHORE;
    notifySemaphoreOnReceiveAck = NQ_NO_SEMAPHORE;

    message_came_from_set = true;
    message_came_from_ip = ip_hostorder;
    message_came_from_port = port_hostorder;

    return true;
}

//
// CNQMessage::check_buffer_against_vartype()
//
//  This method is used internally to validate buffer contents against vartype.
//
//  Parameters:
//  [IN]    vartype         variable type ID (see Declarations.h)
//  [IN]    buffer          pointer to a memory location in order to get the physical packet contents from
//  [IN]    buflength       length of 'buffer' in number of elements!
//                          
//  Return codes:
//      true:   success: buffer contains valid data according to 'suspected' vartype
//      false:  failure: buffer does not contain valid data according to 'suspected' vartype
//
//  Remark:
//      Checking is done on size base, so e.g. a NAN for float and double will pass!
//
bool    CNQMessage::check_buffer_against_vartype( UINT16 vartype, const VOIDP buffer, UINT32 buflength)
{
    // strict checking!

    if (buffer == NULL) return false;
    if (buflength == 0) return false;

    switch( vartype )
    {
        case NQ_VARTYPE_BINARY:
        case NQ_VARTYPE_FLOAT:
        case NQ_VARTYPE_DOUBLE:
        case NQ_VARTYPE_INT8:
        case NQ_VARTYPE_UINT8:
        case NQ_VARTYPE_INT16:
        case NQ_VARTYPE_UINT16:
        case NQ_VARTYPE_INT32:
        case NQ_VARTYPE_UINT32:
                return true;
                break;

        case NQ_VARTYPE_TEXT:
                {
                    UINT8 *bui8 = (UINT8 *) buffer;
                    UINT16 local_length = 0;

                    // string must contain a nullbyte inside the bounds of the buflength
                    while (local_length < buflength)
                    {
                        if (bui8[local_length]==0) break;
                        local_length++;
                    }

                    // string is valid if at least one char is set,
                    // and the string (plus) 0-byte is inside buflength bounds
                    if (local_length > 0 && local_length<buflength) return true;
                }
                break;


        default:  
                break; 
    }

    return false;
}

//
// convenience functions
//

bool CNQMessage::read_BINARY( UINT16 varid, UINT8 *target_buffer, UINT32 &target_buffer_size_bytes)
{
    return read( varid, NQ_VARTYPE_BINARY, target_buffer, target_buffer_size_bytes);
}

bool CNQMessage::read_FLOAT( UINT16 varid, FLOAT &target_buffer)
{
    FLOAT fltbuf;
    UINT32 num_elements = 1;    
    
    if (read( varid, NQ_VARTYPE_FLOAT, &fltbuf, num_elements) == true)
    {
        target_buffer=fltbuf;
        return true;
    }

    return false;
}

bool CNQMessage::read_DOUBLE( UINT16 varid, DOUBLE &target_buffer)
{
    DOUBLE dblbuf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_DOUBLE, &dblbuf, num_elements) == true)
    {
        target_buffer=dblbuf;
        return true;
    }

    return false;
}

bool CNQMessage::read_INT8( UINT16 varid, INT8 &target_buffer)
{
    INT32 i8buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_INT8, &i8buf, num_elements) == true)
    {
        target_buffer= i8buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_UINT8( UINT16 varid, UINT8 &target_buffer)
{
    UINT8 ui8buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_UINT8, &ui8buf, num_elements) == true)
    {
        target_buffer= ui8buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_INT16( UINT16 varid, INT16 &target_buffer)
{
    INT16 i16buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_INT16, &i16buf, num_elements) == true)
    {
        target_buffer=i16buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_UINT16( UINT16 varid, UINT16 &target_buffer)
{
    UINT16 ui16buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_UINT16, &ui16buf, num_elements) == true)
    {
        target_buffer=ui16buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_INT32( UINT16 varid, INT32 &target_buffer)
{
    INT32 i32buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_INT32, &i32buf, num_elements) == true)
    {
        target_buffer=i32buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_UINT32( UINT16 varid, UINT32 &target_buffer)
{
    UINT32 ui32buf;
    UINT32 num_elements = 1;

    if (read( varid, NQ_VARTYPE_UINT32, &ui32buf, num_elements) == true)
    {
        target_buffer=ui32buf;
        return true;
    }

    return false;
}

bool CNQMessage::read_TEXT( UINT16 varid, UINT8 *target_buffer, UINT32 &target_buffer_size_bytes)
{
    return read( varid, NQ_VARTYPE_TEXT, target_buffer, target_buffer_size_bytes );
}


//
// CNQMessage::read()
//
//  This method is part of the API to read message contents. It looks inside the CNQMessage payload
//  for appropriate data block and puts the contents (value) inside target_buffer.
//
//  Parameters:
//  [IN]    varid               variable ID (to be defined by the user)
//  [IN]    vartype             variable type ID (see Declarations.h)
//  [IN]    target_buffer       pointer to a memory location to put the data if found
//  [I/O]   target_buffer_num_elements  IN: maximum length of target buffer in number of elements of 'vartype'
//                                      OUT: on false the minimum size required to put the data in
//                                      OUT: on true the number of elements actually filled
//                          
//  Return codes:
//      true:   success: target_buffer contains valid data according to vartype
//      false:  failure: buffer does not contain valid data according to vartype
//              if target_buffer_size is bigger than on call (in case false was returned)
//              buffer was too small and must be increased to at least the returned 
//              target_buffer_size
//
//              false reasons could be:
//                  target buffer invalid
//                  target buffer to small
//                  vartype does not match
//                  vartype unknown
//                  varid could not be found
//                  packet/message has no data appended
//
//  Remark:
//      In case of false, target buffer was not filled anyhow.
//
bool CNQMessage::read( UINT16 varid, UINT16 vartype, VOIDP target_buffer, UINT32 &target_buffer_num_elements)
{
    // empty ? -> return nothing!
    if (payload_first_offset == -1) return false;

    // no place to write ? 
    if (target_buffer == NULL) return false;

    UINT8 *pdp = &payload_buffer[payload_first_offset]; // PayloaDPointer
    
    UINT32 payload_next;
    UINT16 cur_varid;
    UINT16 cur_vartype;
    UINT16 cur_num_elements;

    do
    {
        payload_next = platform_get_uint32_at(pdp);
        cur_varid = platform_get_uint16_at(pdp+6);
        cur_vartype = platform_get_uint16_at(pdp+8);
        cur_num_elements = platform_get_uint16_at(pdp+10);

        if (varid == cur_varid)
        {
            // no implicit type conversion!
            if (cur_vartype != vartype) return false;
            
            if (target_buffer_num_elements >= cur_num_elements)
            {
                copy_data_depending_on_vartype( (UINT32 *) target_buffer, (const UINT32 *) (pdp+12), cur_num_elements, vartype);
                target_buffer_num_elements = cur_num_elements;
                return true;
            }
            else 
            {
                target_buffer_num_elements = cur_num_elements;
                return false;
            }
        }

        pdp = &payload_buffer[payload_next];

    }
    while (payload_next != 0);

    return false;
}

//
// convenience functions
//

bool CNQMessage::write_BINARY( UINT16 varid, const UINT8 *source_buffer, UINT32 source_buffer_size_bytes)
{
    return write( varid, NQ_VARTYPE_BINARY, (const VOIDP) source_buffer, source_buffer_size_bytes );
}

bool CNQMessage::write_FLOAT( UINT16 varid, FLOAT source_buffer)
{
    return write( varid, NQ_VARTYPE_FLOAT, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_DOUBLE( UINT16 varid, DOUBLE source_buffer)
{
    return write( varid, NQ_VARTYPE_DOUBLE, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_INT8( UINT16 varid, INT8 source_buffer)
{
    return write( varid, NQ_VARTYPE_INT8, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_UINT8( UINT16 varid, UINT8 source_buffer)
{
    return write( varid, NQ_VARTYPE_UINT8, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_INT16( UINT16 varid, INT16 source_buffer)
{
    return write( varid, NQ_VARTYPE_INT16, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_UINT16( UINT16 varid, UINT16 source_buffer)
{
    return write( varid, NQ_VARTYPE_UINT16, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_INT32( UINT16 varid, INT32 source_buffer)
{
    return write( varid, NQ_VARTYPE_INT32, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_UINT32( UINT16 varid, UINT32 source_buffer)
{
    return write( varid, NQ_VARTYPE_UINT32, &source_buffer, 1 ); // 1 element
}

bool CNQMessage::write_TEXT( UINT16 varid, const UINT8 *source_buffer, UINT32 source_buffer_size_bytes)
{
    return write( varid, NQ_VARTYPE_TEXT, (const VOIDP) source_buffer, source_buffer_size_bytes );
}


//
// CNQMessage::write()
//
//  This method is part of the API to read message contents. It adds or replaces a data block inside
//  CNQMessage payload and puts the contents (value) contained inside buffer.
//
//  Parameters:
//  [IN]    varid           variable ID (to be defined by the user)
//  [IN]    vartype         variable type ID (see Declarations.h)
//  [IN]    buffer          pointer to a memory location that contains the value 
//  [IN]    elements_in_buffer  number of 'vartype' elements contained in buffer
//                          
//  Return codes:
//      true:   success: datablock 'varid' added or replaced
//      false:  failure, datablock was neither added nor replaced
//              if there was an old data block with the same varid, it might be deleted now (see WARNING)
//
//              false reasons could be:
//                  buffer does not correspond to vartype
//                  not enough space left in payload space
//                  vartype unknown
//
//  Remark:
//      WARNING: In case of false, message contents might be exhausted! When using debug mode,
//      in exhaust cases an assert() is thrown inside that will notify you of the error.
//
//
bool CNQMessage::write( UINT16 varid, UINT16 vartype, const VOIDP buffer, const UINT32 elements_in_buffer)
{
    UINT32 buffer_size = sizeof_per_element(vartype)*elements_in_buffer;
    // check for bad passed buffer
    if (check_buffer_against_vartype(vartype, buffer, buffer_size) == false) return false; 

    // align to 32bit
    UINT32 new_gross_size = buffer_size;
    if (buffer_size&3) new_gross_size += 4-(buffer_size&3);
    new_gross_size += NQ_MIN_SIZE_DATA_NET-4;

    INT32 payload_first_offset_local = payload_first_offset;
    UINT8 *pdp = &payload_buffer[payload_first_offset_local]; // PayloaDPointer
    UINT8 *prev_pdp = NULL;
    
    if (payload_num_elements > 0)
    {
        bool    new_first;
        UINT32 payload_next;
        UINT16 cur_varid;
        UINT16 cur_net_size;
        UINT16 cur_gross_size;

        do
        {
            payload_next = platform_get_uint32_at(pdp);
            cur_gross_size = platform_get_uint16_at(pdp+4);
            cur_varid = platform_get_uint16_at(pdp+6);
            cur_net_size = platform_get_uint16_at(pdp+10);
            new_first=false;

            if (varid == cur_varid)
            {
                if (cur_net_size == elements_in_buffer)
                {
                    platform_put_uint16_at(pdp+8, vartype);
                    copy_data_depending_on_vartype((UINT32 *) (pdp+12), (const UINT32 *) buffer, elements_in_buffer, vartype);

                    return true; // overwritten: not more to do.
                }
                else
                {
                    // remove first element
                    if (prev_pdp == NULL)
                    {
                        // aha, it is the first one

                        if (payload_buffer_left < (new_gross_size+4)) return false;

                        // check whether size will not be exhausted by exchanging elements
                        INT32   size = payload_curlength_net;
                            
                        size -= (cur_gross_size);
                        size += (new_gross_size);

                        if (size > payload_maxlength_net) return false;

                        // now do operation on the data!
                        payload_first_offset_local = payload_next;
                        payload_curlength_net -= (cur_gross_size);
                        payload_num_elements--;


                        // next is now the first one!
                        new_first=true;
                    }
                }
            }

            if (new_first)
            {
                        prev_pdp = NULL;
                        pdp = &payload_buffer[payload_first_offset_local];
            }
            else
            {
                prev_pdp = pdp;
                if (payload_next != 0) pdp = &payload_buffer[payload_next];
            }

        }
        while (payload_next != 0);

        // note:
        // when the instruction pointer is here, pdp points to the start of the last element in the list, 
        // so we can append a new variable to it!

        if (payload_buffer_left < (new_gross_size+4)) 
        {
            assert(payload_buffer_left >= (new_gross_size+4)); // assert will always break here!
            return false;
        }
        if ((payload_curlength_net+new_gross_size) > payload_maxlength_net) 
        {
            assert((payload_curlength_net+new_gross_size) <= payload_maxlength_net); // assert will always break here!
            return false;
        }

        payload_next = pdp+(cur_gross_size+4)-payload_buffer;
        platform_put_uint32_at(pdp, payload_next);
        pdp = &payload_buffer[payload_next];

        platform_put_uint32_at(pdp, 0);
        platform_put_uint16_at(pdp+4, new_gross_size );
        platform_put_uint16_at(pdp+6, varid);
        platform_put_uint16_at(pdp+8, vartype);
        platform_put_uint16_at(pdp+10, elements_in_buffer);
       
        copy_data_depending_on_vartype((UINT32 *) (pdp+12), (const UINT32 *) buffer, elements_in_buffer, vartype);

        payload_buffer_left -= (new_gross_size+4);
        payload_curlength_net += new_gross_size;
        payload_num_elements++;

        payload_first_offset = payload_first_offset_local;
    }
    else
    {
        //insert at the beginning
        payload_first_offset_local = 0;
        pdp = &payload_buffer[payload_first_offset_local];

        if (payload_buffer_left < (new_gross_size+4)) return false;
        if ((payload_curlength_net+new_gross_size) > payload_maxlength_net) return false;

        platform_put_uint32_at(pdp, 0); // no_next_thing
        platform_put_uint16_at(pdp+4, new_gross_size );
        platform_put_uint16_at(pdp+6, varid);
        platform_put_uint16_at(pdp+8, vartype);
        platform_put_uint16_at(pdp+10, elements_in_buffer);

        copy_data_depending_on_vartype((UINT32 *) (pdp+12), (const UINT32 *) buffer, elements_in_buffer, vartype);

        payload_buffer_left -= (new_gross_size+4);
        payload_curlength_net += new_gross_size;
        payload_num_elements++;

        payload_first_offset = payload_first_offset_local;
    
    }

    return true;
}

//
// CNQMessage::copy_data_depending_on_vartype()
//
//  This method is used internally to copy data with endian changes (where required).
//
//  Parameters:
//
//  [IN]    tgtbufpos       pointer to a target memory location (put to)
//  [IN]    srcbufpos       pointer to a source memory location (get from)
//  [IN]    num_elements    length of buffer location tgtbufpos and srcbufpos in number of elements of vartype
//  [IN]    vartype         variable type ID (see Declarations.h)
//                          
//  Return codes:
//      This function never fails. For debug mode, asserts() are included (loose checking).
//
//  Remark:
//      Copying from source to target, endian changing will take place.
//
void CNQMessage::copy_data_depending_on_vartype( UINT32 *tgtbufpos, const UINT32* srcbufpos, UINT32 num_elements, UINT16 vartype)
{
    // loose checking only !
    assert(tgtbufpos != NULL);
    assert(srcbufpos != NULL);
    assert(num_elements != 0);

    switch( vartype )
    {
        case NQ_VARTYPE_TEXT:
        case NQ_VARTYPE_BINARY:
        case NQ_VARTYPE_INT8:
        case NQ_VARTYPE_UINT8:
                memcpy(tgtbufpos, srcbufpos, num_elements*sizeof_per_element(vartype));
                break; 

        case NQ_VARTYPE_FLOAT:
                {
                    FLOAT* srcbufpos_float = (FLOAT *) srcbufpos;
                    FLOAT* tgtbufpos_float = (FLOAT *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_float_at((UINT8 *) (tgtbufpos_float++), *srcbufpos_float++ );
                        num_elements--;
                    }
                }
                break; 


        case NQ_VARTYPE_DOUBLE:
                {
                    DOUBLE* srcbufpos_double = (DOUBLE *) srcbufpos;
                    DOUBLE* tgtbufpos_double = (DOUBLE *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_double_at((UINT8 *) (tgtbufpos_double++), *srcbufpos_double++ );
                        num_elements--;
                    }
                }
                break; 

        
        case NQ_VARTYPE_INT16:
                {
                    INT16* srcbufpos_int16 = (INT16 *) srcbufpos;
                    INT16* tgtbufpos_int16 = (INT16 *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_int16_at((UINT8 *) (tgtbufpos_int16++), *srcbufpos_int16++ );
                        num_elements--;
                    }
                }
                break;
        
        case NQ_VARTYPE_UINT16:
                {
                    UINT16* srcbufpos_uint16 = (UINT16 *) srcbufpos;
                    UINT16* tgtbufpos_uint16 = (UINT16 *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_uint16_at((UINT8 *)(tgtbufpos_uint16++), *srcbufpos_uint16++ );
                        num_elements--;
                    }
                }
                break;
        
        case NQ_VARTYPE_INT32:
                {
                    INT32* srcbufpos_int32 = (INT32 *) srcbufpos;
                    INT32* tgtbufpos_int32 = (INT32 *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_int32_at((UINT8 *) (tgtbufpos_int32++), *srcbufpos_int32++ );
                        num_elements--;
                    }
                }
                break;
        
        case NQ_VARTYPE_UINT32:
                {
                    UINT32* srcbufpos_uint32 = (UINT32 *) srcbufpos;
                    UINT32* tgtbufpos_uint32 = (UINT32 *) tgtbufpos;

                    while( num_elements > 0)
                    {
                        platform_put_uint32_at((UINT8 *) (tgtbufpos_uint32++), *srcbufpos_uint32++ );
                        num_elements--;
                    }
                }
                break;

        default: assert(1==2);
                break; // not meaningful, but anyhow
    }

}


//
// CNQMessage::sizeof_per_element()
//
//  This method is used internally to obtain size in bytes of an element of type 'vartype'.
//
//  Parameters:
//
//  [IN]    vartype         variable type ID (see Declarations.h)
//                          
//  Return value:
//      This function returns the number of bytes required to store/encode one element of
//      the given vartype.
//
//  Remark:
//      In case of illegal vartype, an assert() is thrown in debug mode. In release mode, 1 (byte)
//      is returned in order to be safe.
//
UINT32 CNQMessage::sizeof_per_element( const UINT16 vartype )
{
    switch( vartype )
    {

        case NQ_VARTYPE_TEXT:
        case NQ_VARTYPE_BINARY:
        case NQ_VARTYPE_INT8:
        case NQ_VARTYPE_UINT8:
                return 1;
                break; 

        case NQ_VARTYPE_INT16:
        case NQ_VARTYPE_UINT16:
                return 2;
                break;

        case NQ_VARTYPE_FLOAT:
        case NQ_VARTYPE_INT32:
        case NQ_VARTYPE_UINT32:
                return 4;
                break; 

        case NQ_VARTYPE_DOUBLE:
                return 8;
                break; 

        default:
                break;
    }

    assert(1==2); // break, but
    return 1; // be safe
}

---