Jamoma API  0.6.0.a19
TTXmlHandler.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup modularLibrary
4  *
5  * @brief TTObjectBase to handle xml file reading and writing to be able to store / recall state of an object into/from xml files.
6  *
7  * @details
8  *
9  * @authors Théo de la Hogue
10  *
11  * @copyright © 2010, Théo de la Hogue @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_XML_HANDLER_H__
18 #define __TT_XML_HANDLER_H__
19 
20 #include "TTModularIncludes.h"
21 #include <stdio.h>
22 
23 /** Write / Read mecanism
24 
25  writeAs<Format> / readFrom<Format> methods are not directly called using the classic message system.
26  We should prefer use one of the exported TT<Format>Reader / TT<Format>Writer method which have :
27  - an Object attribute : the TTObjectBase you want it reads / writes a file
28  or
29  - the data structure to pass in order to read / write depending on the selected <Format>
30 
31  This allow us to use the same method to start reading / writing and even to ask to other objects to
32  read / write recursively on the same data stucture.
33 
34 
35  Exemple :
36 
37  If you want to read in Xml format you set the Object attribute as myTopObject then you call the Read message with
38  aValueContainingFullPathToaFile. Then this method (as a friend of your TTTopObject class) will automatically create
39  an XmlReader data structure and call ReadFromXml(aValueContainingAnXmlReader) on your myTopObject.
40 
41  Because your TTTopObject class used TTLowerObject to describe himself (and have to extract their xml description
42  from the xml file to set them up) the ReadFromXml method sets recursively the Object Attribute with aLowerObject
43  and then calls the Read message with an empty value : this would calls the ReadFromXml(aValueContainingAnXmlReader)
44  on your TTLowerObject.
45 
46  */
47 
48 class TTMODULAR_EXPORT TTXmlHandler : public TTObjectBase
49 {
51 
52 public: // use public for recursive access
53 
54  TTValue mObject; ///< the last handled object (it is possible to have an array of objects)
55  TTSymbol mFilePath; ///< the path to the last writen/read file
56 
57  TTSymbol mHeaderNodeName; ///< the name of the header node in the xml file
58  TTSymbol mVersion; ///< the version number
59  TTSymbol mXmlSchemaInstance; ///< the URL of the schema instance location
60  TTSymbol mXmlSchemaLocation; ///< the URL of the xml schema location
61 
62  TTPtr mWriter; // xmlTextWriterPtr
63  TTPtr mReader; // xmlTextReaderPtr
64 
65  TTBoolean mXmlNodeStart; ///< true if the Reader starts to read a Node
66  TTBoolean mXmlNodeIsEmpty; ///< true if the Node is empty
67  TTSymbol mXmlNodeName; ///< the Node name being read by the Reader
68  TTValue mXmlNodeValue; ///< the Node value being read by the Reader
69 
70  /** Setter for mObject attribute. */
71  TTErr setObject(const TTValue& value);
72 
73  /** TTXmlWriter could takes absolute file path or nothing.
74  In the path case, TTXmlWriter starts xml file writting and then calls the WriteAsXml
75  method of mObject attribute
76  In the second case, it directly calls the WriteAsXml method */
77  TTErr Write(const TTValue& args, TTValue& outputValue);
78  TTErr WriteAgain();
79 
80  /** TTXmlReader could takes absolute file path or nothing.
81  In the path case, TTXmlReader starts xml file reading and then calls the ReadFromXml
82  method of mObject attribute
83  In the second case, it directly calls the ReadFromXml method */
84  TTErr Read(const TTValue& args, TTValue& outputValue);
85  TTErr ReadAgain();
86 
87  /** TTXmlReader make a TTValue from an xmlChar* using the fromString method (see in TTValue.h) */
88 // TTErr fromXmlChar(const xmlChar* xCh, TTValue& v, TTBoolean addQuote=NO, TTBoolean numberAsSymbol=NO);
89  TTErr fromXmlChar(const void* xCh, TTValue& v, TTBoolean addQuote=NO, TTBoolean numberAsSymbol=NO);
90 
91  /** Get the value of an xml element attribute */
92  TTErr getXmlAttribute(TTSymbol attributeName, TTValue& returnedValue, TTBoolean addQuote=NO, TTBoolean numberAsSymbol=NO);
93 
94  /** Get the value of the next xml element attribute */
95  TTErr getXmlNextAttribute(TTSymbol& returnedAttributeName, TTValue& returnedValue, TTBoolean addQuote=NO, TTBoolean numberAsSymbol=NO);
96 
97 private :
98 
99  TTBoolean mIsWriting; ///< a flag to know if it is writing a file
100  TTBoolean mIsReading; ///< a flag to know if it is reading a file
101 
102 };
103 
105 
106 
107 #endif // __TT_XML_HANDLER_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTModular Library.
TTValue mXmlNodeValue
the Node value being read by the Reader
Definition: TTXmlHandler.h:68
TTValue mObject
the last handled object (it is possible to have an array of objects)
Definition: TTXmlHandler.h:54
TTBoolean mXmlNodeIsEmpty
true if the Node is empty
Definition: TTXmlHandler.h:66
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
TTSymbol mXmlSchemaLocation
the URL of the xml schema location
Definition: TTXmlHandler.h:60
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
TTSymbol mVersion
the version number
Definition: TTXmlHandler.h:58
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTSymbol mXmlSchemaInstance
the URL of the schema instance location
Definition: TTXmlHandler.h:59
TTSymbol mHeaderNodeName
the name of the header node in the xml file
Definition: TTXmlHandler.h:57
TTBoolean mXmlNodeStart
true if the Reader starts to read a Node
Definition: TTXmlHandler.h:65
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTSymbol mXmlNodeName
the Node name being read by the Reader
Definition: TTXmlHandler.h:67
Write / Read mecanism.
Definition: TTXmlHandler.h:48
TTSymbol mFilePath
the path to the last writen/read file
Definition: TTXmlHandler.h:55
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34