|
1 // Copyright (c) 2003-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 // This file contains the declaration of the generic CMDXMLComposer class |
|
15 // which is responsible for creating an XML file |
|
16 // from a given DOM structure. |
|
17 // |
|
18 // |
|
19 |
|
20 /** |
|
21 @file |
|
22 */ |
|
23 |
|
24 |
|
25 #ifndef __GMXMLCOMPOSER_H__ |
|
26 #define __GMXMLCOMPOSER_H__ |
|
27 |
|
28 #include <e32base.h> |
|
29 #include <f32file.h> |
|
30 #include <gmxmlconstants.h> |
|
31 #include <charconv.h> |
|
32 |
|
33 //forward reference |
|
34 class CMDXMLDocument; |
|
35 class CMDXMLEntityConverter; |
|
36 class CMDXMLNode; |
|
37 |
|
38 class MMDXMLComposerObserver |
|
39 /** Abstract observer interface for notification when XML composition is complete. |
|
40 |
|
41 It should be implemented by users of CMDXMLComposer. |
|
42 |
|
43 @publishedPartner |
|
44 @released |
|
45 */ |
|
46 { |
|
47 public: |
|
48 /** |
|
49 Call back function used to inform a client of the composer that the composer has completed. |
|
50 */ |
|
51 virtual void ComposeFileCompleteL() = 0; |
|
52 }; |
|
53 |
|
54 |
|
55 class CMDXMLComposer: public CActive |
|
56 /** Creates an XML file from a given DOM structure. |
|
57 @publishedPartner |
|
58 @released |
|
59 */ |
|
60 { |
|
61 public: |
|
62 /** Destructor. */ |
|
63 IMPORT_C ~CMDXMLComposer(); |
|
64 |
|
65 /** Allocates and constructs a new XML composer. |
|
66 |
|
67 @param aComposerObserver Composer observer |
|
68 @leave KErrNoMemory Out of memory |
|
69 @return New XML composer */ |
|
70 IMPORT_C static CMDXMLComposer* NewL(MMDXMLComposerObserver* aComposerObserver); |
|
71 |
|
72 /** Allocates and constructs a new XML composer. |
|
73 |
|
74 @param aComposerObserver Composer observer |
|
75 @param aOutputProlog Whether to output Version and Doctype tags. |
|
76 @leave KErrNoMemory Out of memory |
|
77 @return New XML composer */ |
|
78 IMPORT_C static CMDXMLComposer* NewL(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog); |
|
79 |
|
80 |
|
81 /** Allocates and constructs a new XML composer, leaving the object on the cleanup |
|
82 stack. |
|
83 |
|
84 @leave KErrNoMemory Out of memory |
|
85 @param aComposerObserver Composer observer |
|
86 @return New XML composer */ |
|
87 IMPORT_C static CMDXMLComposer* NewLC(MMDXMLComposerObserver* aComposerObserver); |
|
88 |
|
89 /** Allocates and constructs a new XML composer, leaving the object on the cleanup |
|
90 stack. |
|
91 |
|
92 @leave KErrNoMemory Out of memory |
|
93 @param aComposerObserver Composer observer |
|
94 @param aOutputProlog Whether to output Version and Doctype tags. |
|
95 @return New XML composer */ |
|
96 IMPORT_C static CMDXMLComposer* NewLC(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog); |
|
97 |
|
98 /** Starts file composition. |
|
99 |
|
100 This function must not be called when file sizing is in progress. If it is necessary to calulate |
|
101 the size and generate the XML simultaneously then two instances of the composer should be used, |
|
102 one for sizing and one for composition. |
|
103 |
|
104 @param aRFs A file server session |
|
105 @param aFileToCompose Name of the file to create |
|
106 @param aDocument The document object to compose to the file |
|
107 @param aFileType Type of the output file |
|
108 @return KErrNone if successful */ |
|
109 IMPORT_C TInt ComposeFile(RFs aRFs, const TDesC& aFileToCompose, CMDXMLDocument* aDocument, TXMLFileType aFileType); |
|
110 |
|
111 IMPORT_C TInt ComposeFile(RFile& aFileHandleToCompose, CMDXMLDocument* aDocument, TXMLFileType aFileType); |
|
112 |
|
113 /** Starts calculating the size of the XML output without actually writing it to the file. |
|
114 |
|
115 File size calculation is asyncronous, the size value is only updated when ComposeFileComplete |
|
116 is called on the MMDXMLComposerObserver passed in in the NewL. |
|
117 |
|
118 This function must not be called when file composition or another sizing operation is |
|
119 in progress. If it is necessary to calulate the size and generate the XML simultaneously |
|
120 then two instances of the composer should be used, one for sizing and one for composition. |
|
121 |
|
122 @param aSize Will be set to the size of the XML document when composition has completed. |
|
123 @param aDocument The document object to size |
|
124 @param aFileType Type of the output file, required because it will affect the size of the XML |
|
125 @return KErrNone if successful */ |
|
126 |
|
127 IMPORT_C TInt CalculateFileSize(TInt& aSize, CMDXMLDocument* aDocument, TXMLFileType aFileType); |
|
128 |
|
129 /** Gets the composer's last error. |
|
130 |
|
131 @return Error code */ |
|
132 IMPORT_C TInt Error() const; |
|
133 |
|
134 /** |
|
135 Get the severity of the most severe error found. |
|
136 @return the maximum error severity |
|
137 */ |
|
138 IMPORT_C TXMLErrorCodeSeverity ErrorSeverity() const; |
|
139 |
|
140 //Defect fix for INC036136 - Enable the use of custom entity converters in GMXML |
|
141 /** Outputs raw data. |
|
142 it's only intended to be used from within a custom entity converter as |
|
143 it relies on a Composer sesssion already being in progress |
|
144 |
|
145 @param aData Data to output |
|
146 @return KErrNone if successful, otherwise a file writing error. |
|
147 */ |
|
148 IMPORT_C TInt OutputDataL(const TDesC& aData); |
|
149 |
|
150 /** |
|
151 * Sets the entity converter to be used |
|
152 * and take ownership of the passed entity converter |
|
153 * @param aEntityConverter The entity converter to be used |
|
154 */ |
|
155 IMPORT_C void SetEntityConverter(CMDXMLEntityConverter* aEntityConverter); |
|
156 //End Defect fix for INC036136 |
|
157 |
|
158 public: // public functions used by other classes within the .dll, not for Export. |
|
159 /** Gets the entity converter used by the composer. |
|
160 |
|
161 @return The entity converter used by the composer. */ |
|
162 IMPORT_C CMDXMLEntityConverter* EntityConverter() const; |
|
163 |
|
164 /** Outputs a comment. |
|
165 |
|
166 @param aComment Comment to output |
|
167 @return KErrNone if successful, otherwise a file writing error. */ |
|
168 TInt OutputCommentL(const TDesC& aComment); |
|
169 |
|
170 /** Outputs a processing instruction. |
|
171 |
|
172 @param aInstruction Processing instruction text to output |
|
173 @return KErrNone if successful, otherwise a file writing error. */ |
|
174 TInt OutputProcessingInstructionL(const TDesC& aInstruction); |
|
175 |
|
176 /** Outputs a CDATA section. |
|
177 |
|
178 @param aCDataSection CDATA section to output |
|
179 @return KErrNone if successful, otherwise a file writing error. */ |
|
180 TInt OutputCDataSectionL(const TDesC& aCDataSection); |
|
181 |
|
182 |
|
183 /** Outputs a start of element tag. |
|
184 |
|
185 @param aElementName The name of the tag to output |
|
186 @return KErrNone if successful, otherwise a file writing error. */ |
|
187 IMPORT_C TInt OutputStartOfElementTagL(const TDesC& aElementName); |
|
188 |
|
189 /** Outputs an end of element start tag (</). |
|
190 |
|
191 @param aHasChildren True if the element has children |
|
192 @return KErrNone if successful, otherwise a file writing error. */ |
|
193 IMPORT_C TInt OutputEndOfElementTagL(const TBool aHasChildren); |
|
194 |
|
195 /** Output an end of element tag. |
|
196 |
|
197 @param aElementName The name of the tag to output |
|
198 @return KErrNone if successful, otherwise a file writing error. */ |
|
199 TInt OutputEndTagL(const TDesC& aElementName); |
|
200 |
|
201 /** Outputs an attribute name and value. |
|
202 |
|
203 @param aAttributeName Attribute name |
|
204 @param aAttributeValue Attribute value |
|
205 @return KErrNone if successful, otherwise a file writing error. */ |
|
206 IMPORT_C TInt OutputAttributeL(const TDesC& aAttributeName, const TDesC& aAttributeValue); |
|
207 |
|
208 private: |
|
209 /* |
|
210 * BaseConstructL function to be called by dervived classes during their construction |
|
211 */ |
|
212 void BaseConstructL(); |
|
213 |
|
214 /* |
|
215 * RunError function inherited from CActive base class - intercepts any Leave from |
|
216 * the RunL() function, sets an appropriate errorcode and calls ComposeFileCompleteL |
|
217 */ |
|
218 IMPORT_C TInt RunError(TInt aError); |
|
219 |
|
220 /* |
|
221 * DoCancel function inherited from CActive base class |
|
222 */ |
|
223 IMPORT_C virtual void DoCancel(); |
|
224 |
|
225 /* |
|
226 * RunL function inherited from CActive base class - does the actual composition |
|
227 * @leave can Leave due to OOM |
|
228 */ |
|
229 virtual void RunL(); |
|
230 |
|
231 /* |
|
232 * Function to write string to required file format - handles format conversion |
|
233 * @param aStringToWrite the string to output |
|
234 * @return returns KERRNone if successful or a file write error. |
|
235 */ |
|
236 virtual TInt WriteFileL(const TDesC& aStringToWrite); |
|
237 |
|
238 /* |
|
239 * Function to flush output string to required file format - handles format conversion |
|
240 * @return returns KERRNone if successful or a file write error. |
|
241 */ |
|
242 virtual TInt FlushOutputBufferL(); |
|
243 |
|
244 /* |
|
245 * Constructor |
|
246 */ |
|
247 CMDXMLComposer(MMDXMLComposerObserver* aComposerObserver); |
|
248 |
|
249 /* |
|
250 * Constructor |
|
251 */ |
|
252 CMDXMLComposer(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog); |
|
253 |
|
254 |
|
255 /* |
|
256 * Sets iError to new errorcode if more serious than any error so far encountered |
|
257 */ |
|
258 IMPORT_C void SetError(const TInt aErrorCode, const TXMLErrorCodeSeverity aSeverity); |
|
259 |
|
260 |
|
261 /* |
|
262 * Outputs a start tag for the node which includes the |
|
263 * tag name and all attribute name value pairs currently |
|
264 * specified. If the node is an empty node then it |
|
265 * makes the tag an empty node tag, otherwise it creates |
|
266 * a start tag. |
|
267 * @param aNode The Node for which the start tag is being written |
|
268 * @return Returns KerrNone if successful or a file write error |
|
269 */ |
|
270 IMPORT_C TInt ComposeStartTagL(CMDXMLNode& aNode); |
|
271 |
|
272 /* |
|
273 * Outputs an end tag for the node. |
|
274 * @param aNode the node for which the tag is being written. |
|
275 * @return Returns KerrNone if successful or a file write error |
|
276 */ |
|
277 |
|
278 |
|
279 IMPORT_C TInt ComposeEndTagL(CMDXMLNode& aNode); |
|
280 |
|
281 /* |
|
282 * Second stage constructor |
|
283 * @param aEntityStrings the string table which lists the entity references and conversion |
|
284 */ |
|
285 void ConstructL(); |
|
286 TInt ComposeL(); |
|
287 |
|
288 void InitialiseCompose(CMDXMLDocument* aDocument, TXMLFileType aFileType); |
|
289 |
|
290 IMPORT_C void PlaceholderForRemovedExport1(MMDXMLComposerObserver* aComposerObserver); |
|
291 IMPORT_C void PlaceholderForRemovedExport2(); |
|
292 IMPORT_C void PlaceholderForRemovedExport3(); |
|
293 TInt ReplaceXmlCharactersL(const TDesC16& aXmlData, const TDesC& aString); |
|
294 |
|
295 private: |
|
296 MMDXMLComposerObserver* iComposerObserver; |
|
297 CMDXMLEntityConverter* iEntityConverter; // Entity converter to use |
|
298 CMDXMLDocument* iXMLDoc; // XML document being composed |
|
299 RFile iXMLFile; // File being composed |
|
300 TXMLFileType iFileType; // Type of file being composed |
|
301 TInt iError; // Current error |
|
302 TXMLErrorCodeSeverity iSeverity; // ErrorCode severity |
|
303 CCnvCharacterSetConverter* iCharconv; |
|
304 TBuf<KWriteBufferLen> iOutputBuffer; |
|
305 RFs iRFs; // File system to use |
|
306 TBool iOutputProlog; // Whether to output Version and Doctype tags |
|
307 |
|
308 TInt iSizeTally; |
|
309 TInt* iSize; |
|
310 TBool iOnlyCalculatingSize; |
|
311 |
|
312 #ifdef _DEBUG |
|
313 TInt iIndentationLevel; |
|
314 #endif |
|
315 }; |
|
316 |
|
317 #endif |