M/c++_api/inc/DM/IAddInfo.hpp

#pragma once
 
#include "DM/config.hpp"
#include "DM/IAddInfoLayout.hpp"
 
DM_NAMESPACE_BEGIN
 
/// \brief AddInfo objects store a set of attributes
/**
  Managing attributes, layout and views is a core feature of the DM library. Please refer to the
  \ref dm_attributes section for implementation concepts and to the <a href="examples.html">examples</a>
  section (attribute handling) for further details.
*/
class DM_API IAddInfo : public IAddInfoLayout
{
protected:
  virtual ~IAddInfo() {}
 
public:
  //IAddInfoLayout Interface ==================================================
  virtual unsigned columns() const = 0;
 
  virtual const char*    name(unsigned index) const = 0;
  virtual ColumnType     type(unsigned index) const = 0;
  virtual ColumnSemantic semantic(unsigned index) const = 0;
  virtual unsigned       size(unsigned index) const = 0;
  virtual bool           exist(unsigned index) const = 0;
 
  virtual int index(const char*) const = 0;
  virtual int index(ColumnSemantic) const = 0;
 
  //actual IAddInfo Inteface ==================================================
  virtual const IAddInfoLayout& layout() const = 0;
 
  /// \brief is the current layout just a view onto the storage object
  virtual bool isView() const = 0;
 
  ///returns a full copy of the current object
  virtual IAddInfo* clone() const = 0;
 
  /// \brief creates a new addinfo object with the provide view layout that refers to the same storage object
  /** 
    Whereas setView changes the current addinfo object, cloneView leafs the current object unchanged and creates 
    an new addinfo object using the provide view layout that internal refers to the same storage object. See the
    attribute handling example in the <a href="examples.html">examples</a> section.
 
    @param[in] layout    view layout that should be used
    @param[in] readOnly  flag if the layout of storage object should be changed, in case the view layout is not a true subset of the storage layout
    @return new addinfo object
  */
  virtual IAddInfo *cloneView(const AddInfoLayoutHandle &layout, bool readOnly) const = 0;
  /// \brief creates a new addinfo object with the provide view layout and secures that the storage object contains the dataLayout
  /**
    Whereas setView changes the current addinfo object, cloneView leafs the current object unchanged and creates 
    an new addinfo object using the provide view layout that internal refers to the same storage object. Furthermore it is checked 
    that all columns of the dataLayout exist in the storage object. If not the storage object is extended. See the
    attribute handling example in the <a href="examples.html">examples</a> section.
 
    @param[in] viewLayout    view layout that should be set
    @param[in] dataLayout    defines columns that have to exist in the storage object
  */  
  virtual IAddInfo *cloneView(const AddInfoLayoutHandle &viewLayout, const AddInfoLayoutHandle &dataLayout) const = 0;
  /// \brief creates a new addinfo object using the true storage layout that referring to the same storage object
  virtual IAddInfo *cloneFullLayout() const = 0;
 
  /// \brief applies a certain layout view onto the current object
  /**
    In contrast to cloneView the function changes the visible layout of the current object. Since
    geometry object uses smart pointers to addinfo object this may affect other code parts.
    The read only parameter does not protect for writing attributes to the addinfo object. The parameter refers to
    the layout of storage object. The view layout is not necessarily a subset of the storage layout. In such a configuration
    the disjunct attributes can be added (readOnly = false) to the attribute storage (and storage layout) or not 
    (readOnly = true). In the later case the disjunct attributes still exists in the view layout, but you will not be able to
    read or write them. Only the isNull check will be valid and, of course, it will always return true for disjunct attributes.
    In case you want to read/write all attributes of the view layout the read only parameter should be set to false
 
    @param[in] layout    view layout that should be set
    @param[in] readOnly  flag if the layout of storage object should be changed, in case the view layout is not a true subset of the storage layout
  */
  virtual void setView(const AddInfoLayoutHandle &layout, bool readOnly) = 0;
  /// \brief removes any view layout and sets the true storage layout as (internal) layout
  virtual void restoreFullLayout() = 0;
 
  virtual bool isNull(unsigned index) const = 0;
  virtual void setNull(unsigned index,bool nullFlag = true) = 0;
 
  virtual void setInt8(unsigned index, int8_t) = 0;
  virtual void setUInt8(unsigned index, uint8_t) = 0;
 
  virtual void setInt16(unsigned index, int16_t) = 0;
  virtual void setUInt16(unsigned index, uint16_t) = 0;
 
  virtual void setInt32(unsigned index, int32_t) = 0;
  virtual void setUInt32(unsigned index, uint32_t) = 0;
 
  virtual void setInt64(unsigned index, int64_t) = 0;
 
  virtual void setFloat(unsigned index, float) = 0;
  virtual void setDouble(unsigned index, double) = 0;
 
  virtual void setCStr(unsigned index, const char *) = 0;  ///< for setting column values of type eCOLTYPE_CSTR or eCOLTYPE_STRING
  virtual void setBool(unsigned index, bool) = 0;
 
  virtual int8_t      getInt8(unsigned index) const = 0;
  virtual uint8_t     getUInt8(unsigned index) const = 0;
 
  virtual int16_t     getInt16(unsigned index) const = 0;
  virtual uint16_t    getUInt16(unsigned index) const = 0;
 
  virtual int32_t     getInt32(unsigned index) const = 0;
  virtual uint32_t    getUInt32(unsigned index) const = 0;
 
  virtual int64_t     getInt64(unsigned index) const = 0;
 
  virtual float       getFloat(unsigned index) const = 0;
  virtual double      getDouble(unsigned index) const = 0;
 
  virtual const char* getCStr(unsigned index) const = 0;    ///< returns column values of type eCOLTYPE_CSTR or eCOLTYPE_STRING
  virtual bool        getBool(unsigned index) const = 0;
 
  //convenience functions for easier access to specific add info elements
  virtual EchoClass getEchoClass() const = 0;
 
  //get function with implizit conversion
  
  virtual int8_t    getAsInt8(unsigned index) const = 0;
  virtual uint8_t   getAsUInt8(unsigned index) const = 0;
 
  virtual int16_t   getAsInt16(unsigned index) const = 0;
  virtual uint16_t  getAsUInt16(unsigned index) const = 0;
 
  virtual int32_t   getAsInt32(unsigned index) const = 0;
  virtual uint32_t  getAsUInt32(unsigned index) const = 0;
 
  virtual int64_t   getAsInt64(unsigned index) const = 0;
 
  virtual float     getAsFloat(unsigned index) const = 0;
  virtual double    getAsDouble(unsigned index) const = 0;
 
  ///returns buffer length that is required to fully retrieve the column by getFromCStr (+1 for '\0' already included)
  virtual unsigned        getFromCStrLength(unsigned index) const = 0;            
  /// \brief stores column value in the provided character buffer
  /// \param[in]     index      column index
  /// \param[in,out] buffer     character buffer
  /// \param[in]     bufferLen  length of reserved character buffer
  /// \return true if bufferLen was sufficient for storing the column value, otherwise false 
  virtual bool            getFromCStr(unsigned index, char *buffer, unsigned bufferLen) const = 0;
 
  virtual void setFromInt8(unsigned index, int8_t) = 0;
  virtual void setFromUInt8(unsigned index, uint8_t) = 0;
 
  virtual void setFromInt16(unsigned index, int16_t) = 0;
  virtual void setFromUInt16(unsigned index, uint16_t) = 0;
 
  virtual void setFromInt32(unsigned index, int32_t) = 0;
  virtual void setFromUInt32(unsigned index, uint32_t) = 0;
 
  virtual void setFromInt64(unsigned index, int64_t) = 0;
 
  virtual void setFromFloat(unsigned index, float) = 0;
  virtual void setFromDouble(unsigned index, double) = 0;
 
  virtual void setFromCStr(unsigned index, const char *) = 0;
 
  static bool releaseMemory();
 
  /// \brief removes the specified attributes from current object
  /**
      @param[in] layout  contains all attributes that should be erased from storage (and storage layout)
  */
  virtual void eraseLayout(const AddInfoLayoutHandle &layout) = 0;
 
};
 
typedef Handle<IAddInfo> AddInfoHandle;
 
 
DM_NAMESPACE_END