M/c++_api/inc/DM/IAddInfo.hpp
1 #ifndef DM_IADDINFO_HPP_INCLUDED
2 #define DM_IADDINFO_HPP_INCLUDED
3 
4 #ifdef _MSC_VER
5  #pragma once
6 #endif
7 
8 #include "DM/config.hpp"
9 #include "DM/IAddInfoLayout.hpp"
10 
11 DM_NAMESPACE_BEGIN
12 
13 /// \brief AddInfo objects store a set of attributes
14 /**
15  Managing attributes, layout and views is a core feature of the DM library. Please refer to the
16  \ref dm_attributes section for implementation concepts and to the <a href="examples.html">examples</a>
17  section (attribute handling) for further details.
18 */
19 class DM_API IAddInfo : public IAddInfoLayout
20 {
21 protected:
22  virtual ~IAddInfo() {}
23 
24 public:
25  //IAddInfoLayout Interface ==================================================
26  virtual unsigned columns() const = 0;
27 
28  virtual const char* name(unsigned index) const = 0;
29  virtual ColumnType::Type type(unsigned index) const = 0;
30  virtual ColumnSemantic::Type semantic(unsigned index) const = 0;
31  virtual unsigned size(unsigned index) const = 0;
32 
33  virtual int index(const char*) const = 0;
34  virtual int index(ColumnSemantic::Type) const = 0;
35 
36  //actual IAddInfo Inteface ==================================================
37  virtual const IAddInfoLayout& layout() const = 0;
38 
39  /// \brief is the current layout just a view onto the storage object
40  virtual bool isView() const = 0;
41 
42  ///returns a full copy of the current object
43  virtual IAddInfo* clone() const = 0;
44 
45  /// \brief creates a new addinfo object with the provide view layout that refers to the same storage object
46  /**
47  Whereas setView changes the current addinfo object, cloneView leafs the current object unchanged and creates
48  an new addinfo object using the provide view layout that internal refers to the same storage object. See the
49  attribute handling example in the <a href="examples.html">examples</a> section.
50 
51  @param[in] layout view layout that should be used
52  @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
53  @return new addinfo object
54  */
55  virtual IAddInfo *cloneView(const AddInfoLayoutHandle &layout, bool readOnly) const = 0;
56  /// \brief creates a new addinfo object with the provide view layout and secures that the storage object contains the dataLayout
57  /**
58  Whereas setView changes the current addinfo object, cloneView leafs the current object unchanged and creates
59  an new addinfo object using the provide view layout that internal refers to the same storage object. Furthermore it is checked
60  that all columns of the dataLayout exist in the storage object. If not the storage object is extended. See the
61  attribute handling example in the <a href="examples.html">examples</a> section.
62 
63  @param[in] viewLayout view layout that should be set
64  @param[in] dataLayout defines columns that have to exist in the storage object
65  */
66  virtual IAddInfo *cloneView(const AddInfoLayoutHandle &viewLayout, const AddInfoLayoutHandle &dataLayout) const = 0;
67  /// \brief creates a new addinfo object using the true storage layout that referring to the same storage object
68  virtual IAddInfo *cloneFullLayout() const = 0;
69 
70  /// \brief applies a certain layout view onto the current object
71  /**
72  In contrast to cloneView the function changes the visible layout of the current object. Since
73  geometry object uses smart pointers to addinfo object this may affect other code parts.
74  The read only parameter does not protect for writing attributes to the addinfo object. The parameter refers to
75  the layout of storage object. The view layout is not necessarily a subset of the storage layout. In such a configuration
76  the disjunct attributes can be added (readOnly = false) to the attribute storage (and storage layout) or not
77  (readOnly = true). In the later case the disjunct attributes still exists in the view layout, but you will not be able to
78  read or write them. Only the isNull check will be valid and, of course, it will always return true for disjunct attributes.
79  In case you want to read/write all attributes of the view layout the read only parameter should be set to false
80 
81  @param[in] layout view layout that should be set
82  @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
83  */
84  virtual void setView(const AddInfoLayoutHandle &layout, bool readOnly) = 0;
85  /// \brief removes any view layout and sets the true storage layout as (internal) layout
86  virtual void restoreFullLayout() = 0;
87 
88  virtual bool isNull(unsigned index) const = 0;
89  virtual void setNull(unsigned index,bool nullFlag = true) = 0;
90 
91  virtual void setInt(unsigned index, int) = 0;
92  virtual void setUInt(unsigned index, unsigned int) = 0;
93 
94  virtual void setChar(unsigned index, char) = 0;
95  virtual void setUChar(unsigned index, unsigned char) = 0;
96 
97  virtual void setShort(unsigned index, short) = 0;
98  virtual void setUShort(unsigned index, unsigned short) = 0;
99 
100  virtual void setFloat(unsigned index, float) = 0;
101  virtual void setDouble(unsigned index, double) = 0;
102 
103  virtual void setLLong(unsigned index, long long) = 0;
104  virtual void setCStr(unsigned index, const char *) = 0; ///< for setting column values of type eCOLTYPE_CSTR or eCOLTYPE_STRING
105  virtual void setBool(unsigned index, bool) = 0;
106 
107  virtual int getInt(unsigned index) const = 0;
108  virtual unsigned int getUInt(unsigned index) const = 0;
109 
110  virtual char getChar(unsigned index) const = 0;
111  virtual unsigned char getUChar(unsigned index) const = 0;
112 
113  virtual short getShort(unsigned index) const = 0;
114  virtual unsigned short getUShort(unsigned index) const = 0;
115 
116  virtual float getFloat(unsigned index) const = 0;
117  virtual double getDouble(unsigned index) const = 0;
118 
119  virtual long long getLLong(unsigned index) const = 0;
120  virtual const char* getCStr(unsigned index) const = 0; ///< returns column values of type eCOLTYPE_CSTR or eCOLTYPE_STRING
121  virtual bool getBool(unsigned index) const = 0;
122 
123  //convenience functions for easier access to specific add info elements
124  virtual EchoClass::Type getEchoClass() const = 0;
125 
126  //get function with implizit conversion
127  virtual int getAsInt(unsigned index) const = 0;
128  virtual unsigned int getAsUInt(unsigned index) const = 0;
129 
130  virtual char getAsChar(unsigned index) const = 0;
131  virtual unsigned char getAsUChar(unsigned index) const = 0;
132 
133  virtual short getAsShort(unsigned index) const = 0;
134  virtual unsigned short getAsUShort(unsigned index) const = 0;
135 
136  virtual float getAsFloat(unsigned index) const = 0;
137  virtual double getAsDouble(unsigned index) const = 0;
138 
139  virtual long long getAsLLong(unsigned index) const = 0;
140  ///returns buffer length that is required to fully retrieve the column by getFromCStr (+1 for '\0' already included)
141  virtual unsigned getFromCStrLength(unsigned index) const = 0;
142  /// \brief stores column value in the provided character buffer
143  /// \param[in] index column index
144  /// \param[in,out] buffer character buffer
145  /// \param[in] bufferLen length of reserved character buffer
146  /// \return true if bufferLen was sufficient for storing the column value, otherwise false
147  virtual bool getFromCStr(unsigned index, char *buffer, unsigned bufferLen) const = 0;
148 
149  virtual void setFromInt(unsigned index, int) = 0;
150  virtual void setFromUInt(unsigned index, unsigned int) = 0;
151 
152  virtual void setFromChar(unsigned index, char) = 0;
153  virtual void setFromUChar(unsigned index, unsigned char) = 0;
154 
155  virtual void setFromShort(unsigned index, short) = 0;
156  virtual void setFromUShort(unsigned index, unsigned short) = 0;
157 
158  virtual void setFromFloat(unsigned index, float) = 0;
159  virtual void setFromDouble(unsigned index, double) = 0;
160 
161  virtual void setFromLLong(unsigned index, long long) = 0;
162  virtual void setFromCStr(unsigned index, const char *) = 0;
163 
164  static bool releaseMemory();
165 
166  /// \brief removes the specified attributes from current object
167  /**
168  @param[in] layout contains all attributes that should be erased from storage (and storage layout)
169  */
170  virtual void eraseLayout(const AddInfoLayoutHandle &layout) = 0;
171 
172 };
173 
174 typedef Handle<IAddInfo> AddInfoHandle;
175 
176 
177 DM_NAMESPACE_END
178 
179 #endif //DM_IADDINFO_HPP_INCLUDED