/*
*         Copyright (c), Philips Semiconductors Gratkorn / Austria
*
*                     (C)PHILIPS Electronics N.V.2000
*       All rights are reserved. Reproduction in whole or in part is 
*      prohibited without the written consent of the copyright owner.
*  Philips reserves the right to make changes without notice at any time.
* Philips makes no warranty, expressed, implied or statutory, including but
* not limited to any implied warranty of merchantability or fitness for any
*particular purpose, or that the use will not infringe any third party patent,
* copyright or trademark. Philips must not be liable for any loss or damage
*                          arising from its use.
*/

/*! \file CommandObject.h
*
* Projekt: Host RF Reader Communication
*
* $Workfile:: CommandObject.h                                                 $ 
* $Modtime:: 26.07.01 8:33                                              $ 
* $Author:: Hb                                                          $
* $Revision:: 7                                                         $
*
*/
#ifndef COMMANDOBJECT_H
#define COMMANDOBJECT_H

#ifdef __cplusplus
extern "C" {
#endif

//----------------------------------------------------------------------------
// INCLUDES
//----------------------------------------------------------------------------
#include <OsDefs.h>

//----------------------------------------------------------------------------
// PROTOTYPE DECLARATIONS
//----------------------------------------------------------------------------
class StrBufferContainer;

/// Communication Command Object
/*!
* \ingroup hostrdcom
* Generic storage class, provides a data structure
* which stores all information needed between protocol
* layer and pruduct API layer.
*
* usage:
* <ul>
*  <li> setCommand - stores the command to be sent
*  <li> AddParam   - overridden method, sets copies data to 
*                    CommandBuffer, this provides the data to be 
*                    sent 
*  <li> GetCommandBuffer - protcol gets a pointer to CommandBuffer
*  <li> SetDataByte - Protocol copies received databytes into it
*  <li> GetParam    - overridden method, returns Data to product API
*  <li> GetDataBuffer - product API gets a pointer to DataBuffer
* </ul>
*
*/
class DLLEXP_IMP CommandObject
{
//----------------------------------------------------------------------------
// Member Functions
//----------------------------------------------------------------------------
public:    
    // default constructor
    CommandObject();
    // default destructor
    ~CommandObject();

    //! get/set Command Code to be sent  
    /*! \name Command Code
    *
    * treating the Command code to be sent via protocol
    *
    * Each function call on the reader is uniquly identified by a command
    * code. This code determines the following number of parameters and their 
    * types.
    */
    //@{
    void SetCommand (const unsigned char ccmd);
    unsigned char GetCommand ();
    //@}
    
    //! Status of the processed command
    /*!
    * \name Status
    *
    * Depending on the protocol type, the status flag of a processed 
    * command can have a different value range.
    *
    * In former protocols, there is only one byte reserved. For 
    * nowerdays and future requirements, two or four bytes are 
    * provided.
    */
    //@{
    void SetStatus(const char status);
    void SetStatus(const short status);
    void SetStatus(const long status);
    
    long GetStatus();
    //@}
    
    //! Adding one parameter to the protocoll buffer
    /*! 
    * \name Add Parameters
    *
    * Depending on the command code, several parameters can be passed to
    * the reader. The order of parameters within the sending buffer
    * depends on the order of calling
    * this functions. The length of the parameter depends on the data type
    * of the passed parameter.
    *
    * Several member functions provides a unified interface for passing
    * these parameters.
    */
    //@{
    short AddParam(const unsigned char& data  );
    short AddParam(const unsigned short& data );
    short AddParam(const unsigned int& data   );
    short AddParam(const unsigned long& data );
    short AddParam(const unsigned char * data, const unsigned long& len);
    //@}

    //! Extract one parameter from the protocoll buffer
    /*!
    * \name Extract Parameters
    *
    * Depending on the command code, several parameters are returned by
    * the reader. The order of parameters within the received buffer 
    * depends on the order of calling this functions. The length and type
    * of the parameter depends on the data type of the returned 
    * function parameter.
    *
    * Several member functions provides a unified interface for extracting
    * these returned values from the buffer.
    */ 
    //@{
    short GetParam(unsigned char& data  );
    short GetParam(unsigned short& data );
    short GetParam(signed short& data );
    short GetParam(unsigned int& data   );
    short GetParam(unsigned long& data  );
    short GetParam(unsigned char* data, const unsigned long& len);
    //@}

    //! Buffer Manipulation and Command Configuration
    /*!
    * \name Administrative Functions
    *
    * Except the function <em>ResetBuffers</em> all administrative functions
    * are needed to internaly manipulate the byte stream, which should be sent
    * to the reader or which had been received from the reader.
    *
    * The function <em>ResetBuffers</em> initializes all internal variables and
    * resets the status of the Command Object to the default status.
    *
    * The <em>set</em> and <em>get</em> functions enables the concatenation of
    * several Objects.
    */
    //@{
    //! resets Commandobject
    void ResetBuffers();
    //! returns a pointer to Commandbuffer (not valid after ResetBuffers anymore!)
    const unsigned char*  GetCommandBuffer();
    //! copy unsigned char* of length len to Databuffer beginning at position 0
    short SetDataBuffer(const unsigned char* buffer,const unsigned long& len);
    //! returns a pointer to Databuffer (not valid after ResetBuffers anymore!)
    const unsigned char*  GetDataBuffer();
    //! appends 1 byte to the end of databuffer
    unsigned char SetDataByte(unsigned char& byte);
    //! returns actual DataBuffer length
    unsigned long GetDataBufferLength();
    //! returns actual CommandBuffer length
    unsigned long GetCommandBufferLength();
    //@}

    //! BUG: Wrong Operator Delete Called for Exported Class
    /*!
    * \name BUG: Q122675
    *
    * When allocating and deleting an object of a class that is exported from a DLL, 
    * you may find that the new operator in the EXE is called to allocate the memory but 
    * the delete operator in the DLL is called to delete the memory. Therefore, there is 
    * a new/delete mismatching problem, which may cause run-time errors. 
    */
    //@{
    void* operator new( size_t tSize );
    void  operator delete( void* p );
    //@}

private:
    //! protected copy constructor
    CommandObject(const CommandObject& cmdobj) {};
    //! protected overridden assignment operator
    CommandObject& operator=(const CommandObject& cmdobj) {return *this;};

//----------------------------------------------------------------------------
// Data Members
//----------------------------------------------------------------------------
public:
    enum CONSTANTS { MAX_SEND_BUFFER= 32737,MAX_RECEIVE_BUFFER= 4294967295};
    
private:
    //!  stores the command to be sent
   volatile unsigned char   cCommand;
    //! stores the protocol's return status
    volatile long   lStatus;
    //! CommandBuffer
    StrBufferContainer* psCommandBuffer;
    //! DataBuffer (response)
    StrBufferContainer* psDataBuffer;
};
#ifdef __cplusplus
}
#endif

#endif  //   COMMANDOBJECT_H