1 /*

     2 * Copyright (c) 2003 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

    15 * A simple XML pull parsing interface for handling

    16 * non-unicode XML documents.

    17 *

    18 */

    19 

    20 

    21 #ifndef __XPP_API__

    22 #define __XPP_API__

    23 

    24 #include <e32base.h>

    25 

    26 /**

    27  * A simple XML pull parsing interface for handling

    28  * non-unicode XML documents.

    29  *

    30  * This interface is _conceptually_ similar to the

    31  * Common API for XML Pull Parsing version 1 Java

    32  * API specified at www.xmlpull.org.

    33  */

    34 class MXmlPullParser 

    35     { 

    36 public:

    37     /**

    38      * Parser states

    39      */

    40     enum TParserState

    41         {

    42         EStateStartDocument, /**< The XML input has been set */

    43         EStateStartTag,      /**< A start tag was read */

    44         EStateText,          /**< Element content was read */

    45         EStateEndTag,        /**< An end tag was read */

    46         EStateEndDocument,   /**< No more elements are available */

    47         EStateError          /**< The document is erroneous */

    48         };

    49 

    50     /**

    51      * Parser return codes (in addition to KErrNone and KErrNotFound)

    52      */

    53     enum TReturnCode

    54         {

    55         ERcWrongParserState = -101,   /**< The method is not applicable 

    56                                            in the current parser state */

    57         ERcDocumentError = -102,      /**< The document is invalid */

    58         ERcUnknown = -103             /**< Unknown return code */

    59         };

    60 

    61     /**

    62      * Sets the input(XML document) for the parser.

    63      *

    64      * @param aInput The XML document to parse

    65      */

    66     virtual void SetInput(const TDesC8& aInput) = 0;

    67     

    68     /**

    69      * Advances the parser to the next XML element

    70      * (tag or text) in the document. The State()

    71      * method should be used to find out the resulting

    72      * parser state.

    73      *

    74      * @return KErrNone if the NextL method succeeds,

    75      * one of TReturnCode values if an error occurs.

    76      * On unexceptional conditions, the method leaves

    77      * with one of the system-wide error codes.

    78      */

    79     virtual TInt NextL() = 0;

    80     

    81     /**

    82      * Returns the current state of the parser.

    83      *

    84      * @return The current state of the parser.

    85      * (one of the TParserState values).

    86      */

    87     virtual TParserState State() = 0;

    88 

    89     /**

    90      * Returns the name of the current element.

    91      * This method is only applicable if the parser

    92      * state is EStateStartTag, EStateEndTag or EStateText.

    93      * (jakovist added) or EStateEndDocument. 

    94      *

    95      * @param aName On return, contains the name

    96      * of the current element.

    97      * 

    98      * @return KErrNone if the method succeeds,

    99      * ERcWrongParserState if it fails.

   100      */

   101     virtual TInt Name(TPtrC8& aName) = 0;

   102 

   103     /**

   104      * Returns the XPath of the current element.

   105      * This method is only applicable if the parser

   106      * state is EStateStartTag, EStateEndTag or EStateText.

   107      *

   108      * @param aPath On return, contains the name

   109      * of the current element.

   110      * 

   111      * @return KErrNone if the method succeeds,

   112      * ERcWrongParserState if it fails.

   113      * On unexceptional conditions, the method leaves

   114      * with one of the system-wide error codes.

   115      */

   116     virtual TInt PathL(TPtrC8& aPath) = 0;

   117     

   118     /**

   119      * Returns the depth of the current element in the

   120      * XML document.

   121      * This method is only applicable if the parser

   122      * state is EStateStartTag, EStateEndTag or EStateText.

   123      *

   124      * @param aDepth On return, contains the depth

   125      * of the current element.

   126      * 

   127      * @return KErrNone if the method succeeds,

   128      * ERcWrongParserState if it fails.

   129      */

   130     virtual TInt Depth(TInt& aDepth) = 0;

   131 

   132     /**

   133      * Returns the number of the attributes in the

   134      * current start element. The method is only

   135      * applicable if the parser state is EStateStartTag.

   136      *

   137      * @param aCount On successful return, the number

   138      * of attributes.

   139      * 

   140      * @return KErrNone if the method is successful,

   141      * ERcWrongParserState if the method fails.

   142      */

   143     virtual TInt AttributeCount(TInt& aCount) = 0;

   144 

   145     /**

   146      * Returns the name of the specified attribute

   147      * of the current element. The method is only

   148      * applicable if the parser state is EStateStartTag.

   149      *

   150      * @param aIndex The index (between 0 and 

   151      * AttbuteCount() - 1) of the attribute whose

   152      * name is to be returned.

   153      * @param aValue On successful return, points

   154      * to the name of the specified attribute.

   155      * 

   156      * @return KErrNone if the attribute is found,

   157      * KErrNotFound if the specified attribute

   158      * cannot be found, ERcWrongParserState if 

   159      * the method fails.

   160      */

   161     virtual TInt AttributeName(TInt aIndex,

   162                                TPtrC8& aName) = 0;

   163 

   164     /**

   165      * Returns the value of the specified attribute

   166      * of the current element. The method is only

   167      * applicable if the parser state is EStateStartTag.

   168      *

   169      * @param aIndex The index (between 0 and 

   170      * AttbuteCount() - 1) of the attribute whose

   171      * value is to be returned.

   172      * @param aValue On successful return, points

   173      * to the value of the specified attribute.

   174      * 

   175      * @return KErrNone if the attribute is found,

   176      * KErrNotFound if the specified attribute

   177      * cannot be found, ERcWrongParserState if 

   178      * the method fails.

   179      */

   180     virtual TInt AttributeValuePredefEntitiesNotEscaped(TInt aIndex,

   181                                 TPtrC8& aValue) = 0;

   182 

   183     /**

   184      * Returns the value of the specified attribute

   185      * of the current element. The method is only

   186      * applicable if the parser state is EStateStartTag.

   187      *

   188      * @param aName The name of the attribute whose

   189      * value is to be returned

   190      * @param aValue On successful return, points

   191      * to the value of the specified attribute.

   192      * 

   193      * @return KErrNone if the attribute is found,

   194      * KErrNotFound if the specified attribute

   195      * cannot be found, ERcWrongParserState if 

   196      * the method fails.

   197      */

   198     virtual TInt AttributeValuePredefEntitiesNotEscaped(const TDesC8& aName,

   199                                 TPtrC8& aValue) = 0;

   200 

   201     /**

   202      * Returns the value of the specified attribute

   203      * of the current element. The method is only

   204      * applicable if the parser state is EStateStartTag.

   205      *

   206      * @param aIndex The index (between 0 and 

   207      * AttbuteCount() - 1) of the attribute whose

   208      * value is to be returned.

   209      * @param aValue On successful return, points

   210      * to the value of the specified attribute.

   211      * Character references have been escaped, i.e.

   212      * [   ->  [

   213      * ]  ->  ]

   214      * etc.

   215      * Also predefined entities have been escaped.

   216      * &lt;    ->  <

   217      * >    ->  >

   218      * &   ->  &

   219      * '  ->  '

   220      * "  ->  "

   221      * 

   222      * @return KErrNone if the attribute is found,

   223      * KErrNotFound if the specified attribute

   224      * cannot be found, ERcWrongParserState if 

   225      * the method fails.

   226      */

   227     virtual TInt AttributeValueL(TInt aIndex, 

   228                                 TPtrC8& aValue) = 0;

   229 

   230     /**

   231      * Returns the value of the specified attribute

   232      * of the current element. The method is only

   233      * applicable if the parser state is EStateStartTag.

   234      *

   235      * @param aName The name of the attribute whose

   236      * value is to be returned

   237      * @param aValue On successful return, points

   238      * to the value of the specified attribute.

   239      * Character references have been escaped, i.e.

   240      * [   ->  [

   241      * ]  ->  ]

   242      * etc.

   243      * Also predefined entities have been escaped.

   244      * &lt;    ->  <

   245      * >    ->  >

   246      * &   ->  &

   247      * '  ->  '

   248      * "  ->  "

   249      * 

   250      * @return KErrNone if the attribute is found,

   251      * KErrNotFound if the specified attribute

   252      * cannot be found, ERcWrongParserState if 

   253      * the method fails.

   254      */

   255     virtual TInt AttributeValueL(const TDesC8& aName, 

   256                                 TPtrC8& aValue) = 0;

   257 

   258     /**

   259      * Returns information as to whether the current

   260      * start tag is an empty element tag or not. The 

   261      * method is only applicable if the parser state 

   262      * is EStateStartTag.

   263      *

   264      * @param aIsEmptyElement On successful return, 

   265      * ETrue if the start tag is an empty element tag, 

   266      * EFalse otherwise.

   267      * 

   268      * @return KErrNone if the method succeeds,

   269      * ERcWrongParserState if the method fails.

   270      */

   271     virtual TInt IsEmptyElement(TBool& aIsEmptyElement) = 0;

   272 

   273     /**

   274      * Returns the text of the current element.

   275      * This method is only applicable if the parser

   276      * state is EStateText.

   277      *

   278      * @param aText On successful return, points

   279      * to the text of the current element.

   280      * 

   281      * @return KErrNone if the method succeeds,

   282      * ERcWrongParserState if the method fails.

   283      */

   284     virtual TInt TextPredefEntitiesNotEscaped(TPtrC8& aText) = 0;

   285 

   286     /**

   287      * Returns the text of the current element.

   288      * This method is only applicable if the parser

   289      * state is EStateText.

   290      *

   291      * @param aText On successful return, points

   292      * to the text of the current element.

   293      * Character references have been escaped, i.e.

   294      * [   ->  [

   295      * ]  ->  ]

   296      * etc.

   297      * Also predefined entities have been escaped.

   298      * &lt;    ->  <

   299      * >    ->  >

   300      * &   ->  &

   301      * '  ->  '

   302      * "  ->  "

   303      * 

   304      * @return KErrNone if the method succeeds,

   305      * ERcWrongParserState if the method fails.

   306      */

   307     virtual TInt TextL(TPtrC8& aText) = 0;

   308 

   309     /**

   310      * Returns the current position of a virtual "cursor"

   311      * that is used to read the XML document.

   312      *

   313      * @return The cursor position

   314      */

   315     virtual TInt Pos() = 0;

   316 

   317     /**

   318      * Returns the start position of the current element.

   319      *

   320      * @return The current element start position

   321      */

   322     virtual TInt CurrentElementPos() = 0;

   323 

   324     /**

   325      * Returns the length of the XML document.

   326      *

   327      * @return The length of the XML document.

   328      */

   329     virtual TInt Length() = 0;

   330 

   331     /**

   332      * Returns the specified part of the XML document

   333      * being parsed to the caller

   334      *

   335      * @param aStartPos The position of the first character

   336      * to return

   337      * 

   338      * @param aEndPos The position of the last character

   339      * to return.

   340      * 

   341      * @return A part of the XML document being parsed

   342      */

   343     virtual TPtrC8 DocPart(TInt aStartPos, TInt aEndPos) = 0;

   344     };

   345 

   346 #endif // __XPP_API__