The Fib multimedia system
Fib is a system for storing multimedia data (like images or films).
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
cOptionalPart.h
Go to the documentation of this file.
1 /**
2  * @class cOptionalPart
3  * file name: cOptionalPart.h
4  * @author Betti Oesterholz
5  * @date 29.06.2009
6  * @mail webmaster@BioKom.info
7  *
8  * System: C++
9  *
10  * This class represents the optionalpart of an root -element.
11  * Copyright (C) @c LGPL3 2009 Betti Oesterholz
12  *
13  * This program is free software: you can redistribute it and/or modify
14  * it under the terms of the GNU Lesser General Public License (LGPL) as
15  * published by the Free Software Foundation, either version 3 of the
16  * License, or any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU Lesser General Public License for more details.
22  *
23  * You should have received a copy of the GNU Lesser General Public License
24  * along with this program. If not, see <http://www.gnu.org/licenses/>.
25  *
26  *
27  * This class represents the optionalpart for an root -element.
28  * The optionalpart consists of an list of key -value -pairs.
29  *
30  */
31 /*
32 History:
33 29.06.2009 Oesterholz created
34 10.07.2011 Oesterholz changes for compressed storing
35 23.09.2012 Oesterholz Warning removed: virtual destructor added
36 */
37 
38 #ifndef ___C_OPTIONAL_PART_H__
39 #define ___C_OPTIONAL_PART_H__
40 
41 
42 #include "version.h"
43 
44 #include "fibDatatyps.h"
45 #include "cReadBits.h"
46 
47 #include "tinyxml.h"
48 
49 #include <string>
50 #include <list>
51 #include <utility> //for pair
52 #include <ostream>
53 
54 
55 using std::string;
56 using std::list;
57 using std::pair;
58 using std::ostream;
59 
60 
61 namespace fib{
62 
63 class cRoot;//cyclic dependencie
64 
66 
67 friend class cRoot;
68 
69 protected:
70 
71 
72  /**
73  * the list with the key -value -pairs of optional information
74  */
75  list< pair<string,string> > optionalInformation;
76 
77 
78  /**
79  * This number will be increased with each update.
80  * With it, it can be checked if this optional part is changed.
81  */
82  unsigned long ulVersion;
83 
84  /**
85  * The type of the compression.
86  * Possible typs are:
87  * 0: no compression
88  * 1: The data is compressed in the zlib format. This is a Warper
89  * (documented in RFC 1950) for a deflate stream (lossless data
90  * compression, documented in RFC 1951).
91  */
93 
94 //the folowing datatyps are just for intern use
95  /**
96  * The compressed data of this optional part version
97  * @see ulCompressedDataVersion.
98  * If ulCompressedDataVersion and @see ulVersion are equal the
99  * compressed data is actual and can be used.
100  */
101  mutable char * pCompressedData;
102 
103  /**
104  * The size in byts of the compressed data @see pCompressedData of
105  * this optional part.
106  */
107  mutable size_t uiCompressedDataSize;
108 
109  /**
110  * The version number of the compressed data @see pCompressedData of
111  * this optional part.
112  * If ulCompressedDataVersion and @see ulVersion are equal the
113  * compressed data is actual and can be used.
114  */
115  mutable unsigned long ulCompressedDataVersion;
116 
117 
118 #ifdef TEST
119 public: //make the following constructor public for the test
120 #endif
121 
122  /**
123  * The constructor for the optionalpart.
124  */
125  cOptionalPart();
126 
127  /**
128  * The destructor for the optionalpart.
129  */
130  virtual ~cOptionalPart();
131 
132 
133  /**
134  * This Method clones this object.
135  *
136  * @return a clone of this object
137  */
138  virtual cOptionalPart *clone() const;
139 
140 
141 public:
142 
143 
144  /**
145  * @return returns the number of entries in the optional part
146  */
148 
149 
150  /**
151  * This method returns the ulEntryNumber'th entry of the optional part
152  * list.
153  * If ther is no ulEntryNumber'th entry a pair with two empty strings is
154  * returend;
155  *
156  * @param ulEntryNumber the number of the entry in the optional list of
157  * the entry to return (counting begins with 1)
158  * @return the ulEntryNumber'th entry of the optional part list or a pair
159  * with to empty strings if an ulEntryNumber'th entry dosn't exists;
160  * the returned pair is an (key, value) -pair
161  */
162  pair< string, string > getEntry( unsignedLongFib ulEntryNumber ) const;
163 
164 
165  /**
166  * This method returns all entries which have the given key szKey as
167  * ther full key (if bFullBegin=true) or as the begining of ther key
168  * (if bFullBegin=false) .
169  *
170  * @param szKey the key for which the entries are to return
171  * @param bFullBegin if true (the standardvalue) the given key szKey
172  * is the complete key to be found, else the key szKey is just the
173  * beginning of the key to be found
174  * @return a list with the key -value -pairs for the given key szKey;
175  * the returned pairs are an (key, value) -pairs
176  */
177  list< pair<string,string> > getEntries( string szKey,
178  bool bFullBegin=true ) const;
179 
180 
181  /**
182  * This method returns all entries which have the given szKeyPart as an
183  * part of ther key.
184  *
185  * @param szKeyPart the part of the keys for which the entries are to
186  * be return
187  * @return a list with the key -value -pairs with szKeyPart as part of
188  * ther key; the returned pairs are an (key, value) -pairs
189  */
190  list< pair<string,string> > findKeyPart( string szKeyPart ) const;
191 
192 
193  /**
194  * This method ads the given key szKey and value szValue pair to the
195  * optionalpart list.
196  *
197  * @param szKey the key of the entry to add
198  * @param szValue the value of the entry to add
199  * @param ulPosition the position on which in the optional part list
200  * the new entry should be added (counting begins with 1);
201  * the standardvalue is 0 to add the entry on the end of the list
202  * @return the position wher the new entry was added to the optional
203  * part list (counting begins with 1)
204  */
205  unsignedLongFib addEntry( string szKey, string szValue,
206  unsignedLongFib ulPosition=0 );
207 
208 
209  /**
210  * This method deletes the ulEntryNumber'th entry of the optional part
211  * list.
212  *
213  * @param ulEntryNumber the number of the entry in the optional list of
214  * the entry to delete (counting begins with 1)
215  * @return true if the entry was deleted, else false
216  */
217  bool deleteEntry( unsignedLongFib ulEntryNumber );
218 
219 
220  /**
221  * This method deletes all entries which have the given key szKey as
222  * ther full key (if bFullBegin=true) or as the begining of ther key
223  * (if bFullBegin=false) .
224  *
225  * @param szKey the key for which the entries are to delete
226  * @param bFullBegin if true (the standardvalue) the given key szKey
227  * is the complete key to be found, else the key szKey is just the
228  * beginning of the key to be found
229  * @return the number of deleted entries
230  */
231  unsignedLongFib deleteEntries( string szKey,
232  bool bFullBegin=true );
233 
234 
235  /**
236  * This method stores this optionalpart in the XML -format into the
237  * given stream.
238  * example:
239  * <optionalpart>
240  * <pair key="copyright" value="GNU GPL 3"/>
241  * <pair key="type" value="die Berliner Mauer"/>
242  * </optionalpart>
243  *
244  * @param ostream the stream where this optionalpart should be stored to
245  * @return true if this optionalpart is stored, else false
246  */
247  virtual bool storeXml( ostream & ostream ) const;
248 
249  /**
250  * This method restores this optionalpart in the XML-format from an
251  * an TinyXml element.
252  *
253  * @param pXmlNode a pointer to the TinyXml node wher the optionalpart is stored in
254  * @return an integervalue with the errorvalue
255  * possible errorvalues are:
256  * - 0 loading successful
257  * - -1 loading error, invalid pXmlElement
258  * - -2 loading error, invalid data in pXmlElement
259  * - 1 loading warning, invalid data in pXmlElement, error could be corrected
260  * - 2 loading warning, invalid data in pXmlElement, maybe the loaded
261  * object is wrong
262  */
263  virtual intFib restoreXml( const TiXmlElement * pXmlElement );
264 
265  /**
266  * This method evaluades the size of the optionalpart in bits in the
267  * compressed file form.
268  *
269  * @see store()
270  * @see restore()
271  * @see setCompressionType()
272  * @see uiCompressionType
273  * @see actualizeCompressData()
274  * @see cFibElement::getCompressedSize()
275  * @return the size of the optionalpart in bits in the compressed form
276  */
277  virtual unsignedLongFib getCompressedSize() const;
278 
279  /**
280  * This method stores this optionalpart in the compressed fib-format
281  * (with the deflate -algorithmus) into the given stream.
282  *
283  * @see restore()
284  * @see setCompressionType()
285  * @see uiCompressionType
286  * @see actualizeCompressData()
287  * @see cFibElement::store()
288  * @param stream the stream where this optionalpart should be stored to
289  * @return true if the optionalpart are stored, else false
290  */
291  virtual bool store( ostream & stream ) const;
292 
293  /**
294  * This method restores the optionalpart from a bitstream, wher it is
295  * stored in the compressed fib-format with the set compression type.
296  *
297  * @see store()
298  * @see setCompressionType()
299  * @see uiCompressionType
300  * @see actualizeCompressData()
301  * @see cFibElement::store()
302  * @param iBitStream the stream where this optionalpart is stored to in,
303  * because this stream is an cReadBits, any number of bits can be
304  * readed from it
305  * @param ulBytsToRead the nuber of byts the optional part is long,
306  * if 0 (defaultvalue) it will be read till the end of the stream is reached
307  * @return the errorvalue
308  * possible errorvalues are:
309  * - 0 loading successful
310  * - -1 loading error, invalid stream
311  * - -2 loading error, invalid data in stream
312  * - 1 loading warning, invalid data in stream, error could be corrected
313  * - 2 loading warning, invalid data in stream, maybe the loaded
314  * object is wrong
315  */
316  virtual intFib restore( cReadBits & iBitStream, const unsigned long ulBytsToRead = 0 );
317 
318  /**
319  * This method sets the compression type of the optional part for
320  * compressed storing.
321  * Possible typs are:
322  * 0: no compression
323  * 1: The data is compressed in the zlib format. This is a Warper
324  * (documented in RFC 1950) for a deflate stream (lossless data
325  * compression, documented in RFC 1951).
326  *
327  * @see uiCompressionType
328  * @see store()
329  * @see restore()
330  * @see getCompressedSize()
331  * @see actualizeCompressData()
332  * @param uiInCompressionType the compression type to set,
333  * standard value is 1 fo zlib compression
334  * @return true if the compression type could be set
335  */
336  virtual bool setCompressionType( unsignedIntFib uiInCompressionType = 1 );
337 
338  /**
339  * This Method checks if the given optionalpart is equal to this
340  * optionalpart.
341  * Two optionalpart are equal, if they have the same entries in the
342  * same order.
343  *
344  * @param optionalPart the optionalpart to compare with this
345  * @return true if the given optionalpart is equal to this
346  * optionalpart, else false
347  */
348  virtual bool equal( const cOptionalPart &optionalPart ) const;
349 
350  /**
351  * This Method checks if the given optionalpart is equal to this
352  * optionalpart.
353  * Two optionalpart are equal, if they have the same entries in the
354  * same order.
355  *
356  * @param optionalPart the optionalpart to compare with this
357  * @return true if the given optionalpart is equal to this
358  * optionalpart, else false
359  */
360  virtual bool operator==( const cOptionalPart &optionalPart ) const;
361 
362 
363 
364 protected:
365 
366  /**
367  * This method actualize the compressed data of this optional part.
368  * After it was performed successful @see ulCompressedDataVersion and
369  * @see ulVersion will be equal and pCompressedData will contain the
370  * data of this optional part.
371  *
372  * @see store()
373  * @see restore()
374  * @see getCompressedSize()
375  * @see uiCompressionType
376  * @see setCompressionType()
377  * @return true if pCompressedData contains the actual data of this
378  * optional part, else false
379  */
380  virtual bool actualizeCompressData() const;
381 
382 
383 };//end class cOptionalPart
384 
385 
386 }//end namespace fib
387 
388 #endif //___C_OPTIONAL_PART_H__