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