|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // XML Deserializer |
|
15 // |
|
16 |
|
17 |
|
18 |
|
19 /** |
|
20 @file |
|
21 @publishedAll |
|
22 @released |
|
23 */ |
|
24 #ifndef XMLENGDESERIALIZER_H |
|
25 #define XMLENGDESERIALIZER_H |
|
26 |
|
27 #include <e32base.h> |
|
28 #include <xml/dom/xmlengparsingoptions.h> |
|
29 |
|
30 #include <xml/contenthandler.h> |
|
31 #include <xml/parser.h> |
|
32 #include <e32std.h> |
|
33 |
|
34 class RFs; |
|
35 class TXmlEngDataContainer; |
|
36 |
|
37 /** Controls the format of deserialization */ |
|
38 enum TXmlEngDeserializerType |
|
39 { |
|
40 /** Default deserialization (XML) */ |
|
41 EDeserializerDefault, |
|
42 /** Deserialization from MIME Multipart containing XOP */ |
|
43 EDeserializerXOP, |
|
44 /** Deserialization from XOP Infoset */ |
|
45 EDeserializerXOPInfoset, |
|
46 /** Deserialization from GZip */ |
|
47 EDeserializerGZip |
|
48 }; |
|
49 |
|
50 /** Controls the source of the deserialization */ |
|
51 enum TXmlEngDeserializationSource |
|
52 { |
|
53 EDeserializeFromFile, |
|
54 EDeserializeFromBuffer, |
|
55 EDeserializeFromStream |
|
56 }; |
|
57 |
|
58 /** |
|
59 Provides deserialization and parsing for XML content using a SAX callback |
|
60 interface. Derived classes provide deserialization for specific formats, |
|
61 whereas this class defines the interface and provides default (plain XML) |
|
62 deserialization. |
|
63 |
|
64 @see TXmlEngDeserializerType |
|
65 |
|
66 Deserialization generates SAX events that are passed to a MContentHandler. |
|
67 |
|
68 @see Xml::MContentHandler |
|
69 |
|
70 For deserialization to a DOM tree, see CXmlEngDeserializerDOM. |
|
71 @see CXmlEngDeserializerDOM |
|
72 |
|
73 Support for data stored outside the DOM tree, such as data linked by |
|
74 xop:include references, is provided. The external data must be set with |
|
75 UseExternalDataL() prior to deserialization. The data is then returned through |
|
76 the MContentHandler interface. |
|
77 */ |
|
78 class CXmlEngDeserializer: public CBase |
|
79 { |
|
80 friend class CXmlEngDeserializerXOP; |
|
81 friend class CXmlEngDeserializerGZIP; |
|
82 |
|
83 public: |
|
84 /** |
|
85 Creates a deserializer of the given type. Returns an instance of this |
|
86 class or a derived class. |
|
87 |
|
88 @param aHandler Content handler for SAX events triggered by deserialization |
|
89 @param aType Deserializer type |
|
90 @return The deserializer |
|
91 @leave - One of the system-wide error codes |
|
92 */ |
|
93 IMPORT_C static CXmlEngDeserializer* NewL( Xml::MContentHandler& aContentHandler, TXmlEngDeserializerType aType = EDeserializerDefault); |
|
94 |
|
95 /** |
|
96 Sets the input type to file and saves the file name for later |
|
97 deserialization. |
|
98 @param aFileName The file name of the file to deserialize |
|
99 @leave - One of the system-wide error codes |
|
100 */ |
|
101 IMPORT_C void SetInputFileL(const TDesC& aFileName); |
|
102 |
|
103 /** |
|
104 Sets the input type to buffer and saves the buffer for later deserialization. |
|
105 @param aBuffer The buffer to deserialize |
|
106 */ |
|
107 IMPORT_C void SetInputBuffer(const TDesC8& aBuffer); |
|
108 |
|
109 /** |
|
110 Sets the content handler which handles SAX events raised during |
|
111 deserialization. Clients must derive from Xml::MContentHandler in order to |
|
112 receive SAX callbacks. |
|
113 |
|
114 @param aContentHandler The content handler |
|
115 @leave - One of the system-wide error codes |
|
116 */ |
|
117 IMPORT_C virtual void SetContentHandlerL(Xml::MContentHandler& aContentHandler); |
|
118 |
|
119 /** |
|
120 Sets parsing options used for deserialization. |
|
121 @param aOptions Parsing options to set. A copy of the options is stored. |
|
122 */ |
|
123 IMPORT_C virtual void SetParsingOptions(TXmlEngParsingOptions& aOptions); |
|
124 |
|
125 /** |
|
126 Gets the parsing options |
|
127 @return The parsing options |
|
128 */ |
|
129 IMPORT_C virtual const TXmlEngParsingOptions& ParsingOptions(); |
|
130 |
|
131 /** |
|
132 Sets a list of data containers and indicates that the XML to be |
|
133 deserialized contains references (such as xop:include) to data stored |
|
134 outside the DOM tree. |
|
135 |
|
136 Upon deserialization, the references are substituted with the matching data |
|
137 containers and returned via the content handler. |
|
138 |
|
139 This often occurs when a multipart MIME message is received. The text XML |
|
140 content may be in one part, while the binary content is in another part. |
|
141 Each part containing binary content must be placed into a data container using |
|
142 RXmlEngDocument::CreateBinaryContainerL() or similar. When deserialization |
|
143 of the XML occurs, the data containers are retrieved by content-id. |
|
144 |
|
145 Ownership is not transferred and the list must stay in scope for the |
|
146 lifetime of the deserializer. |
|
147 |
|
148 @param aList The list of data containers |
|
149 @leave - Any system-wide error code |
|
150 */ |
|
151 IMPORT_C void UseExternalDataL(RArray<TXmlEngDataContainer>& aList); |
|
152 |
|
153 /** |
|
154 Gets the list of external data containers. |
|
155 @return The list of data containers or NULL if no external data is registered |
|
156 */ |
|
157 IMPORT_C RArray<TXmlEngDataContainer>* ExternalData(); |
|
158 |
|
159 /** |
|
160 Enables parser features. |
|
161 |
|
162 @see Xml::CParser::EnableFeature() |
|
163 @see Xml::CParser::TParserFeature |
|
164 @param aParserFeature The parser feature to enable |
|
165 @return KErrNone if successful, otherwise one of the system-wide error codes |
|
166 */ |
|
167 IMPORT_C virtual TInt EnableFeature(TInt aParserFeature); |
|
168 |
|
169 /** |
|
170 Disables parser features. |
|
171 |
|
172 @see Xml::CParser::DisableFeature() |
|
173 @see Xml::CParser::TParserFeature |
|
174 @param aParserFeature The parser feature to disable |
|
175 @return KErrNone if successful, otherwise one of the system-wide error codes |
|
176 */ |
|
177 IMPORT_C virtual TInt DisableFeature(TInt aParserFeature); |
|
178 |
|
179 /** |
|
180 Checks if a parser feature is enabled. |
|
181 |
|
182 @see Xml::CParser::IsFeatureEnabled() |
|
183 @see Xml::CParser::TParserFeature |
|
184 @param aParserFeature The parser feature to check |
|
185 @return ETrue if feature is enabled, otherwise EFalse |
|
186 */ |
|
187 IMPORT_C virtual TBool IsFeatureEnabled(TInt aParserFeature) const; |
|
188 |
|
189 /** |
|
190 Deserializes the file or buffer previously set by SetInputFileL() or |
|
191 SetInputBuffer(). |
|
192 |
|
193 The result of deserialization is passed to the content handler as SAX |
|
194 events. |
|
195 |
|
196 @leave KXmlEngErrNoParameters No file or buffer has been previously set |
|
197 @leave - One of the system wide error codes or one of the Xml specific |
|
198 ones defined in XmlFrameworkErrors.h |
|
199 */ |
|
200 IMPORT_C virtual void DeserializeL(); |
|
201 |
|
202 /** |
|
203 Deserializes the given file. Any filename previously set with |
|
204 SetInputFileL() is ignored. |
|
205 |
|
206 The result of deserialization is passed to the content handler as SAX |
|
207 events. |
|
208 |
|
209 @param aFileName The file to be parsed |
|
210 @param aOptions Parsing options |
|
211 @leave - One of the system wide error codes or one of the Xml specific |
|
212 ones defined in XmlFrameworkErrors.h |
|
213 */ |
|
214 IMPORT_C virtual void DeserializeL( const TDesC& aFileName, |
|
215 const TXmlEngParsingOptions& aOptions = |
|
216 TXmlEngParsingOptions()); |
|
217 |
|
218 /** |
|
219 Deserializes the given file. Any filename previously set with |
|
220 SetInputFileL() is ignored. |
|
221 |
|
222 The result of deserialization is passed to the content handler as SAX |
|
223 events. |
|
224 |
|
225 @param aRFs File Server session |
|
226 @param aFileName The file to be parsed |
|
227 @param aOptions Parsing options |
|
228 @leave - One of the system wide error codes or one of the Xml specific |
|
229 ones defined in XmlFrameworkErrors.h |
|
230 */ |
|
231 IMPORT_C virtual void DeserializeL( RFs& aRFs, |
|
232 const TDesC& aFileName, |
|
233 const TXmlEngParsingOptions& aOptions = |
|
234 TXmlEngParsingOptions()); |
|
235 |
|
236 /** |
|
237 Deserializes the given buffer. Any buffer previously set with |
|
238 SetInputBuffer() is ignored. |
|
239 |
|
240 The result of deserialization is passed to the content handler as SAX |
|
241 events. |
|
242 |
|
243 @param aBuffer The buffer to be parsed |
|
244 @param aOptions Parsing options |
|
245 @leave - One of the system wide error codes or one of the Xml specific |
|
246 ones defined in XmlFrameworkErrors.h |
|
247 */ |
|
248 IMPORT_C virtual void DeserializeL( const TDesC8& aBuffer, |
|
249 const TXmlEngParsingOptions& aOptions = |
|
250 TXmlEngParsingOptions()); |
|
251 |
|
252 /** Destructor */ |
|
253 virtual ~CXmlEngDeserializer(); |
|
254 |
|
255 /** |
|
256 Retrieves a pointer to the data container referenced by CID. |
|
257 @param aCid The aCid corresponding to the data container required |
|
258 @return The data container or NULL if no matching container is found |
|
259 */ |
|
260 TXmlEngDataContainer* GetDataContainer(const TDesC8& aCid); |
|
261 |
|
262 private: |
|
263 /** Default constructor */ |
|
264 CXmlEngDeserializer( ); |
|
265 |
|
266 /** 2nd phase constructor */ |
|
267 virtual void ConstructL( Xml::MContentHandler& aContentHandler ); |
|
268 |
|
269 private: |
|
270 /** SAX Parser */ |
|
271 Xml::CParser* iParser; |
|
272 |
|
273 /** File to be parsed */ |
|
274 HBufC* iInputFileName; |
|
275 |
|
276 /** Buffer to be parsed */ |
|
277 TPtrC8 iBuffer; |
|
278 |
|
279 /** Deserialization format */ |
|
280 TXmlEngDeserializationSource iSerializationOutput; |
|
281 |
|
282 /** Array of external data */ |
|
283 RArray<TXmlEngDataContainer>* iDataList; |
|
284 |
|
285 /** Features */ |
|
286 TUint iFeatures; |
|
287 |
|
288 /** Parsing options */ |
|
289 TXmlEngParsingOptions iParsingOptions; |
|
290 |
|
291 }; //class CXmlEngDeserializer |
|
292 |
|
293 |
|
294 |
|
295 #endif /* XMLENGDESERIALIZER_H */ |
|
296 |