diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/xml/dom/xmlengdomparser.h --- a/epoc32/include/xml/dom/xmlengdomparser.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/xml/dom/xmlengdomparser.h Wed Mar 31 12:33:34 2010 +0100 @@ -1,28 +1,26 @@ /* -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). * All rights reserved. * This component and the accompanying materials are made available -* 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 +* under the terms of "Eclipse Public License v1.0" * which accompanies this distribution, and is available -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* at the URL "http://www.eclipse.org/legal/epl-v10.html". * * Initial Contributors: * Nokia Corporation - initial contribution. * * Contributors: * -* Description: DOM parser functions +* Description: * */ - - - - - - -#ifndef XMLENGINE_DOMPARSER_H_INCLUDED -#define XMLENGINE_DOMPARSER_H_INCLUDED +/** @file +@publishedAll +@released +*/ +#ifndef XMLENGDOMPARSER_H +#define XMLENGDOMPARSER_H #include @@ -30,155 +28,152 @@ class RXmlEngDocument; /** - * DOM parser class implements methods for parsing XML data. - * - * Parse XML data in one chunk. Data can be parsed from file - * or memory buffer. - * - * Sample code for parsing from buffer: - * @code - * RXmlEngDOMImplementation domImpl; - * domImpl.OpenL(); ///< opening DOM implementation object - * RXmlEngDOMParser parser; - * parser.Open( domImpl ); ///< opening parser object - * RXmlEngDocument iDoc; - * iDoc =parser.ParseL( *aInput ); ///< parsing aInput - buffer - * iDoc.Close(); ///< closing all opened objects - * parser.Close(); - * domImpl.Close(); - * @endcode - * - * Sample code for parsing from file: - * @code - * RXmlEngDOMImplementation domImpl; - * domImpl.OpenL(); ///< opening DOM implementation object - * RXmlEngDOMParser parser; - * parser.Open( domImpl ); ///< opening parser object - * RXmlEngDocument iDoc; - * iDoc =parser.ParseFileL( aFileName ); ///< parsing from file - * iDoc.Close(); ///< closing all openend objects - * parser.Close(); - * domImpl.Close(); - * @endcode - * - * @lib XmlEngineDOM.lib - * @since S60 v3.1 - */ +This class implements methods for parsing XML data. XML data may be parsed +from a chunk, file, or memory buffer. + +Sample code for parsing from buffer: +@code + RXmlEngDOMImplementation domImpl; + domImpl.OpenL(); // opening DOM implementation object + RXmlEngDOMParser parser; + parser.Open( domImpl ); // opening parser object + RXmlEngDocument iDoc; + iDoc =parser.ParseL( *aInput ); // parsing aInput - buffer + iDoc.Close(); // closing all opened objects + parser.Close(); + domImpl.Close(); +@endcode + +Sample code for parsing from file: +@code + RXmlEngDOMImplementation domImpl; + domImpl.OpenL(); // opening DOM implementation object + RXmlEngDOMParser parser; + parser.Open( domImpl ); // opening parser object + RXmlEngDocument iDoc; + iDoc =parser.ParseFileL( aFileName ); // parsing from file + iDoc.Close(); // closing all openend objects + parser.Close(); + domImpl.Close(); +@endcode +*/ class RXmlEngDOMParser { public: - /** - * Default constructor - */ + /** Default constructor */ IMPORT_C RXmlEngDOMParser(); /** - * Opens the parser. - * - * @since S60 v3.2 - * @param aDOMImpl DOM implementation object - * @return KErrNone if succeed. - */ + Opens the parser. The RXmlEngDOMImplementation object passed as an + argument may be used by multiple RXmlEngDOMParser objects. + + @param aDOMImpl DOM implementation object previously opened without error. + @return KErrNone if successful, system wide error code otherwise + */ IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl); - /** - * Closes the parser. - * - * @since S60 v3.2 - */ + /** Closes the parser. */ IMPORT_C void Close(); - /** - * Parses chunk of XML data from memory buffer and builds DOM RXmlEngDocument. - * - * @since S60 v3.2 - * @param aBuffer XML data buffer - * - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory) - */ + /** + Parses a chunk of XML data from a memory buffer and builds an internal DOM + tree. The DOM tree can be accessed by calling FinishL() to obtain a + RXmlEngDocument. + + @see FinishL() + @param aBuffer XML data buffer + @see GetLastParsingError() + @leave KXmlEngErrParsing Parsing error + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called + @leave - One of the system-wide error codes + */ IMPORT_C void ParseChunkL(const TDesC8& aBuffer); - /** - * Creates document from parsed chunks of data. - * Should be called after parsing of allchunks. - * Ownership over returned RXmlEngDocument object is transferred to the caller of the method. - * - * @since S60 v3.2 - * @return RXmlEngDocument created document. - * - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory) - */ + + /** + Creates a document from chunks of data previously parsed by ParseChunkL(). + Should be called after parsing all chunks. Ownership of the returned + RXmlEngDocument object is transferred to the caller of the method. + RXmlEngDocument::Close() must be called when the document is no longer + required. + + @see ParseChunkL() + @return The created document + @see GetLastParsingError() + @leave KXmlEngErrParsing Parsing error + @leave KXmlEngErrWrongUseOfAPI OpenL() or ParseChunkL() not previously + called + @leave - One of the system-wide error codes + */ IMPORT_C RXmlEngDocument FinishL(); /** - * Parses XML file and builds DOM RXmlEngDocument - * - * @since S60 v3.2 - * @param aRFs File server session - * @param aFileName File name - * @param aChunkSize Size of chunk (if 0 chunks won't be used) - * @return Document handle - * - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory) - */ + Parses XML file and builds a DOM RXmlEngDocument. Ownership of the + returned RXmlEngDocument object is transferred to the caller of the method. + RXmlEngDocument::Close() must be called when the document is no longer + required. + + @param aRFs Open file server session + @param aFileName File name + @param aChunkSize The number of bytes to parse from the file at a time, or 0 + if the whole file should be parsed at once. + @return The created document + @see GetLastParsingError() + @leave KXmlEngErrParsing Parsing error + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called + @leave - One of the system-wide error codes + */ IMPORT_C RXmlEngDocument ParseFileL(RFs &aRFs, const TDesC& aFileName, TUint aChunkSize = 0); /** - * Parses XML file and builds DOM RXmlEngDocument - * - * @since S60 v3.2 - * @param aFileName File name - * @param aChunkSize Size of chunk (if 0 chunks won't be used) - * @return Document handle - * - * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory) - */ + Parses XML file and builds a DOM RXmlEngDocument. Ownership of the + returned RXmlEngDocument object is transferred to the caller of the method. + RXmlEngDocument::Close() must be called when the document is no longer + required. + + @param aFileName File name + @param aChunkSize The number of bytes to parse from the file at a time, or 0 + if the whole file should be parsed at once. + @return The created document + @see GetLastParsingError() + @leave KXmlEngErrParsing Parsing error + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called + @leave - One of the system-wide error codes + */ IMPORT_C RXmlEngDocument ParseFileL(const TDesC& aFileName, TUint aChunkSize = 0); - /** - * Parses XML data from memory buffer and builds DOM RXmlEngDocument without chunks - * - * @since S60 v3.1 - * @param aBuffer XML data buffer - * @return Document handle - * - * @leave KXmlEngErrParsing code (besides system I/O error codes) - */ + /** + Parses XML data from a memory buffer that holds the entire XML structure + and builds a DOM RXmlEngDocument. Ownership of the returned + RXmlEngDocument object is transferred to the caller of the method. + RXmlEngDocument::Close() must be called when the document is no longer + required. + + @see ParseChunkL() + @param aBuffer XML data buffer + @return The created document + @see GetLastParsingError() + @leave KXmlEngErrParsing Parsing error + @leave KXmlEngErrWrongUseOfAPI OpenL() not previously called + @leave - One of the system-wide error codes + */ IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer); /** - * Return last parsing error code. - * - * @since S60 v3.2 - * @return positive number - * - * @note Error codes are positive numbers. User can find them - * in XmlEngDErrors.h - */ + Return last parsing error code. Error codes are positive numbers. + @see xmlengerrors.h + @return The last error returned by the parser or KErrNone if none + */ IMPORT_C TInt GetLastParsingError(); + private: - /** - * Parses XML file and builds DOM RXmlEngDocument without usage of chunks - * - * @param aRFs File server session - * @param aFileName File name - * @return Document handle - * - * @leave KXmlEngErrParsing code (besides system I/O error codes) - */ RXmlEngDocument ParseFileWithoutChunksL(RFs& aRFs, const TDesC& aFileName); + void Cleanup(); - /** - * Cleanup internal data. - * - * @since S60 v3.2 - */ - void Cleanup(); private: void* iInternal; TInt iError; RXmlEngDOMImplementation* iImpl; }; +#endif /* XMLENGDOMPARSER_H */ - -#endif /* XMLENGINE_DOMPARSER_H_INCLUDED */