|
1 /* |
|
2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 /** @file |
|
19 @publishedAll |
|
20 @released |
|
21 */ |
|
22 #ifndef XMLENGDOMPARSER_H |
|
23 #define XMLENGDOMPARSER_H |
|
24 |
|
25 #include <f32file.h> |
|
26 |
|
27 class RXmlEngDOMImplementation; |
|
28 class RXmlEngDocument; |
|
29 |
|
30 /** |
|
31 This class implements methods for parsing XML data. XML data may be parsed |
|
32 from a chunk, file, or memory buffer. |
|
33 |
|
34 Sample code for parsing from buffer: |
|
35 @code |
|
36 RXmlEngDOMImplementation domImpl; |
|
37 domImpl.OpenL(); // opening DOM implementation object |
|
38 RXmlEngDOMParser parser; |
|
39 parser.Open( domImpl ); // opening parser object |
|
40 RXmlEngDocument iDoc; |
|
41 iDoc =parser.ParseL( *aInput ); // parsing aInput - buffer |
|
42 iDoc.Close(); // closing all opened objects |
|
43 parser.Close(); |
|
44 domImpl.Close(); |
|
45 @endcode |
|
46 |
|
47 Sample code for parsing from file: |
|
48 @code |
|
49 RXmlEngDOMImplementation domImpl; |
|
50 domImpl.OpenL(); // opening DOM implementation object |
|
51 RXmlEngDOMParser parser; |
|
52 parser.Open( domImpl ); // opening parser object |
|
53 RXmlEngDocument iDoc; |
|
54 iDoc =parser.ParseFileL( aFileName ); // parsing from file |
|
55 iDoc.Close(); // closing all openend objects |
|
56 parser.Close(); |
|
57 domImpl.Close(); |
|
58 @endcode |
|
59 */ |
|
60 class RXmlEngDOMParser |
|
61 { |
|
62 public: |
|
63 /** Default constructor */ |
|
64 IMPORT_C RXmlEngDOMParser(); |
|
65 |
|
66 /** |
|
67 Opens the parser. The RXmlEngDOMImplementation object passed as an |
|
68 argument may be used by multiple RXmlEngDOMParser objects. |
|
69 |
|
70 @param aDOMImpl DOM implementation object previously opened without error. |
|
71 @return KErrNone if successful, system wide error code otherwise |
|
72 */ |
|
73 IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl); |
|
74 |
|
75 /** Closes the parser. */ |
|
76 IMPORT_C void Close(); |
|
77 |
|
78 /** |
|
79 Parses a chunk of XML data from a memory buffer and builds an internal DOM |
|
80 tree. The DOM tree can be accessed by calling FinishL() to obtain a |
|
81 RXmlEngDocument. |
|
82 |
|
83 @see FinishL() |
|
84 @param aBuffer XML data buffer |
|
85 @see GetLastParsingError() |
|
86 @leave KXmlEngErrParsing Parsing error |
|
87 @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called |
|
88 @leave - One of the system-wide error codes |
|
89 */ |
|
90 IMPORT_C void ParseChunkL(const TDesC8& aBuffer); |
|
91 |
|
92 /** |
|
93 Creates a document from chunks of data previously parsed by ParseChunkL(). |
|
94 Should be called after parsing all chunks. Ownership of the returned |
|
95 RXmlEngDocument object is transferred to the caller of the method. |
|
96 RXmlEngDocument::Close() must be called when the document is no longer |
|
97 required. |
|
98 |
|
99 @see ParseChunkL() |
|
100 @return The created document |
|
101 @see GetLastParsingError() |
|
102 @leave KXmlEngErrParsing Parsing error |
|
103 @leave KXmlEngErrWrongUseOfAPI OpenL() or ParseChunkL() not previously |
|
104 called |
|
105 @leave - One of the system-wide error codes |
|
106 */ |
|
107 IMPORT_C RXmlEngDocument FinishL(); |
|
108 |
|
109 /** |
|
110 Parses XML file and builds a DOM RXmlEngDocument. Ownership of the |
|
111 returned RXmlEngDocument object is transferred to the caller of the method. |
|
112 RXmlEngDocument::Close() must be called when the document is no longer |
|
113 required. |
|
114 |
|
115 @param aRFs Open file server session |
|
116 @param aFileName File name |
|
117 @param aChunkSize The number of bytes to parse from the file at a time, or 0 |
|
118 if the whole file should be parsed at once. |
|
119 @return The created document |
|
120 @see GetLastParsingError() |
|
121 @leave KXmlEngErrParsing Parsing error |
|
122 @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called |
|
123 @leave - One of the system-wide error codes |
|
124 */ |
|
125 IMPORT_C RXmlEngDocument ParseFileL(RFs &aRFs, const TDesC& aFileName, TUint aChunkSize = 0); |
|
126 |
|
127 /** |
|
128 Parses XML file and builds a DOM RXmlEngDocument. Ownership of the |
|
129 returned RXmlEngDocument object is transferred to the caller of the method. |
|
130 RXmlEngDocument::Close() must be called when the document is no longer |
|
131 required. |
|
132 |
|
133 @param aFileName File name |
|
134 @param aChunkSize The number of bytes to parse from the file at a time, or 0 |
|
135 if the whole file should be parsed at once. |
|
136 @return The created document |
|
137 @see GetLastParsingError() |
|
138 @leave KXmlEngErrParsing Parsing error |
|
139 @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called |
|
140 @leave - One of the system-wide error codes |
|
141 */ |
|
142 IMPORT_C RXmlEngDocument ParseFileL(const TDesC& aFileName, TUint aChunkSize = 0); |
|
143 |
|
144 /** |
|
145 Parses XML data from a memory buffer that holds the entire XML structure |
|
146 and builds a DOM RXmlEngDocument. Ownership of the returned |
|
147 RXmlEngDocument object is transferred to the caller of the method. |
|
148 RXmlEngDocument::Close() must be called when the document is no longer |
|
149 required. |
|
150 |
|
151 @see ParseChunkL() |
|
152 @param aBuffer XML data buffer |
|
153 @return The created document |
|
154 @see GetLastParsingError() |
|
155 @leave KXmlEngErrParsing Parsing error |
|
156 @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called |
|
157 @leave - One of the system-wide error codes |
|
158 */ |
|
159 IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer); |
|
160 |
|
161 /** |
|
162 Return last parsing error code. Error codes are positive numbers. |
|
163 @see xmlengerrors.h |
|
164 @return The last error returned by the parser or KErrNone if none |
|
165 */ |
|
166 IMPORT_C TInt GetLastParsingError(); |
|
167 |
|
168 private: |
|
169 RXmlEngDocument ParseFileWithoutChunksL(RFs& aRFs, const TDesC& aFileName); |
|
170 void Cleanup(); |
|
171 |
|
172 private: |
|
173 void* iInternal; |
|
174 TInt iError; |
|
175 RXmlEngDOMImplementation* iImpl; |
|
176 }; |
|
177 |
|
178 #endif /* XMLENGDOMPARSER_H */ |
|
179 |