1 xmlengdomparser.h

     1 /*

     2 * Copyright (c) 2004-2006 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:       DOM parser functions

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 #ifndef XMLENGINE_DOMPARSER_H_INCLUDED

    25 #define XMLENGINE_DOMPARSER_H_INCLUDED

    26 

    27 #include <f32file.h>

    28 

    29 class RXmlEngDOMImplementation;

    30 class RXmlEngDocument;

    31 

    32 /** 

    33  * DOM parser class implements methods for parsing XML data.

    34  *

    35  * Parse XML data in one chunk. Data can be parsed from file 

    36  * or memory buffer.

    37  *

    38  * Sample code for parsing from buffer:

    39  * @code

    40  *      RXmlEngDOMImplementation domImpl;

    41  *      domImpl.OpenL();              ///< opening DOM implementation object 

    42  *      RXmlEngDOMParser parser;

    43  *      parser.Open( domImpl );   ///< opening parser object

    44  *      RXmlEngDocument iDoc;

    45  *      iDoc =parser.ParseL( *aInput );   ///< parsing aInput - buffer  

    46  *      iDoc.Close();               ///< closing all opened objects

    47  *      parser.Close();

    48  *      domImpl.Close();

    49  * @endcode 

    50  * 

    51  * Sample code for parsing from file:

    52  * @code

    53  *      RXmlEngDOMImplementation domImpl;

    54  *      domImpl.OpenL();              ///< opening DOM implementation object 

    55  *      RXmlEngDOMParser parser;

    56  *      parser.Open( domImpl );   ///< opening parser object

    57  *      RXmlEngDocument iDoc;

    58  *      iDoc =parser.ParseFileL( aFileName );   ///< parsing from file  

    59  *      iDoc.Close();               ///< closing all openend objects

    60  *      parser.Close();

    61  *      domImpl.Close();

    62  * @endcode 

    63  * 

    64  * @lib XmlEngineDOM.lib

    65  * @since S60 v3.1

    66  */

    67 class RXmlEngDOMParser

    68 {

    69 public:

    70     /**

    71      * Default constructor

    72      */

    73     IMPORT_C RXmlEngDOMParser();

    74 	

    75     /** 

    76      * Opens the parser.

    77      *

    78 	 * @since S60 v3.2

    79 	 * @param aDOMImpl DOM implementation object

    80      * @return KErrNone if succeed.

    81      */

    82     IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl);

    83     

    84     /** 

    85      * Closes the parser.

    86      *

    87 	 * @since S60 v3.2

    88 	 */

    89     IMPORT_C void Close();

    90 

    91     /** 

    92      * Parses chunk of XML data from memory buffer and builds DOM RXmlEngDocument.

    93      *

    94      * @since S60 v3.2

    95      * @param aBuffer XML data buffer

    96      * 

    97      * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

    98      */

    99     IMPORT_C void ParseChunkL(const TDesC8& aBuffer);

   100     /** 

   101      * Creates document from parsed chunks of data.

   102      * Should be called after parsing of allchunks.

   103      * Ownership over returned RXmlEngDocument object is transferred to the caller of the method.

   104      *

   105      * @since S60 v3.2

   106      * @return RXmlEngDocument created document.

   107      * 

   108      * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

   109      */

   110     IMPORT_C RXmlEngDocument FinishL();

   111     

   112     /** 

   113      * Parses XML file and builds DOM RXmlEngDocument

   114      *

   115      * @since S60 v3.2

   116 	 * @param aRFs File server session

   117      * @param aFileName File name

   118      * @param aChunkSize Size of chunk (if 0 chunks won't be used)

   119      * @return Document handle

   120      * 

   121      * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

   122 	 */

   123     IMPORT_C RXmlEngDocument ParseFileL(RFs &aRFs, const TDesC& aFileName, TUint aChunkSize = 0);

   124 

   125     /** 

   126      * Parses XML file and builds DOM RXmlEngDocument

   127      *

   128      * @since S60 v3.2

   129 	 * @param aFileName File name

   130      * @param aChunkSize Size of chunk (if 0 chunks won't be used)

   131      * @return Document handle

   132      * 

   133      * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

   134      */

   135     IMPORT_C RXmlEngDocument ParseFileL(const TDesC& aFileName, TUint aChunkSize = 0);

   136 

   137     /** 

   138      * Parses XML data from memory buffer and builds DOM RXmlEngDocument without chunks

   139      *

   140 	 * @since S60 v3.1

   141 	 * @param aBuffer XML data buffer

   142      * @return Document handle

   143      * 

   144      * @leave KXmlEngErrParsing code (besides system I/O error codes)

   145      */

   146     IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer);  

   147 

   148     /** 

   149      * Return last parsing error code. 

   150      *

   151      * @since S60 v3.2

   152 	 * @return positive number

   153      *

   154      * @note Error codes are positive numbers. User can find them

   155      *         in XmlEngDErrors.h

   156      */

   157     IMPORT_C TInt GetLastParsingError();

   158 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 

   170     /** 

   171      * Cleanup internal data.

   172      *

   173      * @since S60 v3.2

   174      */

   175     void Cleanup();

   176 private:

   177     void* iInternal;

   178     TInt iError;

   179     RXmlEngDOMImplementation* iImpl;

   180 };

   181 

   182 

   183 

   184 #endif /* XMLENGINE_DOMPARSER_H_INCLUDED */