1.1 --- a/epoc32/include/xml/dom/xmlengdomparser.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/xml/dom/xmlengdomparser.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,28 +1,26 @@
1.4 /*
1.5 -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
1.7 * All rights reserved.
1.8 * This component and the accompanying materials are made available
1.9 -* 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
1.10 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: DOM parser functions
1.21 +* Description:
1.22 *
1.23 */
1.24
1.25 -
1.26 -
1.27 -
1.28 -
1.29 -
1.30 -
1.31 -#ifndef XMLENGINE_DOMPARSER_H_INCLUDED
1.32 -#define XMLENGINE_DOMPARSER_H_INCLUDED
1.33 +/** @file
1.34 +@publishedAll
1.35 +@released
1.36 +*/
1.37 +#ifndef XMLENGDOMPARSER_H
1.38 +#define XMLENGDOMPARSER_H
1.39
1.40 #include <f32file.h>
1.41
1.42 @@ -30,155 +28,152 @@
1.43 class RXmlEngDocument;
1.44
1.45 /**
1.46 - * DOM parser class implements methods for parsing XML data.
1.47 - *
1.48 - * Parse XML data in one chunk. Data can be parsed from file
1.49 - * or memory buffer.
1.50 - *
1.51 - * Sample code for parsing from buffer:
1.52 - * @code
1.53 - * RXmlEngDOMImplementation domImpl;
1.54 - * domImpl.OpenL(); ///< opening DOM implementation object
1.55 - * RXmlEngDOMParser parser;
1.56 - * parser.Open( domImpl ); ///< opening parser object
1.57 - * RXmlEngDocument iDoc;
1.58 - * iDoc =parser.ParseL( *aInput ); ///< parsing aInput - buffer
1.59 - * iDoc.Close(); ///< closing all opened objects
1.60 - * parser.Close();
1.61 - * domImpl.Close();
1.62 - * @endcode
1.63 - *
1.64 - * Sample code for parsing from file:
1.65 - * @code
1.66 - * RXmlEngDOMImplementation domImpl;
1.67 - * domImpl.OpenL(); ///< opening DOM implementation object
1.68 - * RXmlEngDOMParser parser;
1.69 - * parser.Open( domImpl ); ///< opening parser object
1.70 - * RXmlEngDocument iDoc;
1.71 - * iDoc =parser.ParseFileL( aFileName ); ///< parsing from file
1.72 - * iDoc.Close(); ///< closing all openend objects
1.73 - * parser.Close();
1.74 - * domImpl.Close();
1.75 - * @endcode
1.76 - *
1.77 - * @lib XmlEngineDOM.lib
1.78 - * @since S60 v3.1
1.79 - */
1.80 +This class implements methods for parsing XML data. XML data may be parsed
1.81 +from a chunk, file, or memory buffer.
1.82 +
1.83 +Sample code for parsing from buffer:
1.84 +@code
1.85 + RXmlEngDOMImplementation domImpl;
1.86 + domImpl.OpenL(); // opening DOM implementation object
1.87 + RXmlEngDOMParser parser;
1.88 + parser.Open( domImpl ); // opening parser object
1.89 + RXmlEngDocument iDoc;
1.90 + iDoc =parser.ParseL( *aInput ); // parsing aInput - buffer
1.91 + iDoc.Close(); // closing all opened objects
1.92 + parser.Close();
1.93 + domImpl.Close();
1.94 +@endcode
1.95 +
1.96 +Sample code for parsing from file:
1.97 +@code
1.98 + RXmlEngDOMImplementation domImpl;
1.99 + domImpl.OpenL(); // opening DOM implementation object
1.100 + RXmlEngDOMParser parser;
1.101 + parser.Open( domImpl ); // opening parser object
1.102 + RXmlEngDocument iDoc;
1.103 + iDoc =parser.ParseFileL( aFileName ); // parsing from file
1.104 + iDoc.Close(); // closing all openend objects
1.105 + parser.Close();
1.106 + domImpl.Close();
1.107 +@endcode
1.108 +*/
1.109 class RXmlEngDOMParser
1.110 {
1.111 public:
1.112 - /**
1.113 - * Default constructor
1.114 - */
1.115 + /** Default constructor */
1.116 IMPORT_C RXmlEngDOMParser();
1.117
1.118 /**
1.119 - * Opens the parser.
1.120 - *
1.121 - * @since S60 v3.2
1.122 - * @param aDOMImpl DOM implementation object
1.123 - * @return KErrNone if succeed.
1.124 - */
1.125 + Opens the parser. The RXmlEngDOMImplementation object passed as an
1.126 + argument may be used by multiple RXmlEngDOMParser objects.
1.127 +
1.128 + @param aDOMImpl DOM implementation object previously opened without error.
1.129 + @return KErrNone if successful, system wide error code otherwise
1.130 + */
1.131 IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl);
1.132
1.133 - /**
1.134 - * Closes the parser.
1.135 - *
1.136 - * @since S60 v3.2
1.137 - */
1.138 + /** Closes the parser. */
1.139 IMPORT_C void Close();
1.140
1.141 - /**
1.142 - * Parses chunk of XML data from memory buffer and builds DOM RXmlEngDocument.
1.143 - *
1.144 - * @since S60 v3.2
1.145 - * @param aBuffer XML data buffer
1.146 - *
1.147 - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)
1.148 - */
1.149 + /**
1.150 + Parses a chunk of XML data from a memory buffer and builds an internal DOM
1.151 + tree. The DOM tree can be accessed by calling FinishL() to obtain a
1.152 + RXmlEngDocument.
1.153 +
1.154 + @see FinishL()
1.155 + @param aBuffer XML data buffer
1.156 + @see GetLastParsingError()
1.157 + @leave KXmlEngErrParsing Parsing error
1.158 + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called
1.159 + @leave - One of the system-wide error codes
1.160 + */
1.161 IMPORT_C void ParseChunkL(const TDesC8& aBuffer);
1.162 - /**
1.163 - * Creates document from parsed chunks of data.
1.164 - * Should be called after parsing of allchunks.
1.165 - * Ownership over returned RXmlEngDocument object is transferred to the caller of the method.
1.166 - *
1.167 - * @since S60 v3.2
1.168 - * @return RXmlEngDocument created document.
1.169 - *
1.170 - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)
1.171 - */
1.172 +
1.173 + /**
1.174 + Creates a document from chunks of data previously parsed by ParseChunkL().
1.175 + Should be called after parsing all chunks. Ownership of the returned
1.176 + RXmlEngDocument object is transferred to the caller of the method.
1.177 + RXmlEngDocument::Close() must be called when the document is no longer
1.178 + required.
1.179 +
1.180 + @see ParseChunkL()
1.181 + @return The created document
1.182 + @see GetLastParsingError()
1.183 + @leave KXmlEngErrParsing Parsing error
1.184 + @leave KXmlEngErrWrongUseOfAPI OpenL() or ParseChunkL() not previously
1.185 + called
1.186 + @leave - One of the system-wide error codes
1.187 + */
1.188 IMPORT_C RXmlEngDocument FinishL();
1.189
1.190 /**
1.191 - * Parses XML file and builds DOM RXmlEngDocument
1.192 - *
1.193 - * @since S60 v3.2
1.194 - * @param aRFs File server session
1.195 - * @param aFileName File name
1.196 - * @param aChunkSize Size of chunk (if 0 chunks won't be used)
1.197 - * @return Document handle
1.198 - *
1.199 - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)
1.200 - */
1.201 + Parses XML file and builds a DOM RXmlEngDocument. Ownership of the
1.202 + returned RXmlEngDocument object is transferred to the caller of the method.
1.203 + RXmlEngDocument::Close() must be called when the document is no longer
1.204 + required.
1.205 +
1.206 + @param aRFs Open file server session
1.207 + @param aFileName File name
1.208 + @param aChunkSize The number of bytes to parse from the file at a time, or 0
1.209 + if the whole file should be parsed at once.
1.210 + @return The created document
1.211 + @see GetLastParsingError()
1.212 + @leave KXmlEngErrParsing Parsing error
1.213 + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called
1.214 + @leave - One of the system-wide error codes
1.215 + */
1.216 IMPORT_C RXmlEngDocument ParseFileL(RFs &aRFs, const TDesC& aFileName, TUint aChunkSize = 0);
1.217
1.218 /**
1.219 - * Parses XML file and builds DOM RXmlEngDocument
1.220 - *
1.221 - * @since S60 v3.2
1.222 - * @param aFileName File name
1.223 - * @param aChunkSize Size of chunk (if 0 chunks won't be used)
1.224 - * @return Document handle
1.225 - *
1.226 - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)
1.227 - */
1.228 + Parses XML file and builds a DOM RXmlEngDocument. Ownership of the
1.229 + returned RXmlEngDocument object is transferred to the caller of the method.
1.230 + RXmlEngDocument::Close() must be called when the document is no longer
1.231 + required.
1.232 +
1.233 + @param aFileName File name
1.234 + @param aChunkSize The number of bytes to parse from the file at a time, or 0
1.235 + if the whole file should be parsed at once.
1.236 + @return The created document
1.237 + @see GetLastParsingError()
1.238 + @leave KXmlEngErrParsing Parsing error
1.239 + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called
1.240 + @leave - One of the system-wide error codes
1.241 + */
1.242 IMPORT_C RXmlEngDocument ParseFileL(const TDesC& aFileName, TUint aChunkSize = 0);
1.243
1.244 - /**
1.245 - * Parses XML data from memory buffer and builds DOM RXmlEngDocument without chunks
1.246 - *
1.247 - * @since S60 v3.1
1.248 - * @param aBuffer XML data buffer
1.249 - * @return Document handle
1.250 - *
1.251 - * @leave KXmlEngErrParsing code (besides system I/O error codes)
1.252 - */
1.253 + /**
1.254 + Parses XML data from a memory buffer that holds the entire XML structure
1.255 + and builds a DOM RXmlEngDocument. Ownership of the returned
1.256 + RXmlEngDocument object is transferred to the caller of the method.
1.257 + RXmlEngDocument::Close() must be called when the document is no longer
1.258 + required.
1.259 +
1.260 + @see ParseChunkL()
1.261 + @param aBuffer XML data buffer
1.262 + @return The created document
1.263 + @see GetLastParsingError()
1.264 + @leave KXmlEngErrParsing Parsing error
1.265 + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called
1.266 + @leave - One of the system-wide error codes
1.267 + */
1.268 IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer);
1.269
1.270 /**
1.271 - * Return last parsing error code.
1.272 - *
1.273 - * @since S60 v3.2
1.274 - * @return positive number
1.275 - *
1.276 - * @note Error codes are positive numbers. User can find them
1.277 - * in XmlEngDErrors.h
1.278 - */
1.279 + Return last parsing error code. Error codes are positive numbers.
1.280 + @see xmlengerrors.h
1.281 + @return The last error returned by the parser or KErrNone if none
1.282 + */
1.283 IMPORT_C TInt GetLastParsingError();
1.284 +
1.285 private:
1.286 - /**
1.287 - * Parses XML file and builds DOM RXmlEngDocument without usage of chunks
1.288 - *
1.289 - * @param aRFs File server session
1.290 - * @param aFileName File name
1.291 - * @return Document handle
1.292 - *
1.293 - * @leave KXmlEngErrParsing code (besides system I/O error codes)
1.294 - */
1.295 RXmlEngDocument ParseFileWithoutChunksL(RFs& aRFs, const TDesC& aFileName);
1.296 + void Cleanup();
1.297
1.298 - /**
1.299 - * Cleanup internal data.
1.300 - *
1.301 - * @since S60 v3.2
1.302 - */
1.303 - void Cleanup();
1.304 private:
1.305 void* iInternal;
1.306 TInt iError;
1.307 RXmlEngDOMImplementation* iImpl;
1.308 };
1.309
1.310 +#endif /* XMLENGDOMPARSER_H */
1.311
1.312 -
1.313 -#endif /* XMLENGINE_DOMPARSER_H_INCLUDED */