--- 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 <f32file.h>
@@ -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 */