/*

* Copyright (c) 2003 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  

* A simple XML pull parsing interface for handling

* non-unicode XML documents.

*

*/

#ifndef __XPP_API__

#define __XPP_API__

#include <e32base.h>

/**

 * A simple XML pull parsing interface for handling

 * non-unicode XML documents.

 *

 * This interface is _conceptually_ similar to the

 * Common API for XML Pull Parsing version 1 Java

 * API specified at www.xmlpull.org.

 */

class MXmlPullParser 

    { 

public:

    /**

     * Parser states

     */

    enum TParserState

        {

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

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

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

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

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

        EStateError          /**< The document is erroneous */

        };

    /**

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

     */

    enum TReturnCode

        {

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

                                           in the current parser state */

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

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

        };

    /**

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

     *

     * @param aInput The XML document to parse

     */

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

    /**

     * Advances the parser to the next XML element

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

     * method should be used to find out the resulting

     * parser state.

     *

     * @return KErrNone if the NextL method succeeds,

     * one of TReturnCode values if an error occurs.

     * On unexceptional conditions, the method leaves

     * with one of the system-wide error codes.

     */

    virtual TInt NextL() = 0;

    /**

     * Returns the current state of the parser.

     *

     * @return The current state of the parser.

     * (one of the TParserState values).

     */

    virtual TParserState State() = 0;

    /**

     * Returns the name of the current element.

     * This method is only applicable if the parser

     * state is EStateStartTag, EStateEndTag or EStateText.

     * (jakovist added) or EStateEndDocument. 

     *

     * @param aName On return, contains the name

     * of the current element.

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if it fails.

     */

    virtual TInt Name(TPtrC8& aName) = 0;

    /**

     * Returns the XPath of the current element.

     * This method is only applicable if the parser

     * state is EStateStartTag, EStateEndTag or EStateText.

     *

     * @param aPath On return, contains the name

     * of the current element.

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if it fails.

     * On unexceptional conditions, the method leaves

     * with one of the system-wide error codes.

     */

    virtual TInt PathL(TPtrC8& aPath) = 0;

    /**

     * Returns the depth of the current element in the

     * XML document.

     * This method is only applicable if the parser

     * state is EStateStartTag, EStateEndTag or EStateText.

     *

     * @param aDepth On return, contains the depth

     * of the current element.

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if it fails.

     */

    virtual TInt Depth(TInt& aDepth) = 0;

    /**

     * Returns the number of the attributes in the

     * current start element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aCount On successful return, the number

     * of attributes.

     * 

     * @return KErrNone if the method is successful,

     * ERcWrongParserState if the method fails.

     */

    virtual TInt AttributeCount(TInt& aCount) = 0;

    /**

     * Returns the name of the specified attribute

     * of the current element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aIndex The index (between 0 and 

     * AttbuteCount() - 1) of the attribute whose

     * name is to be returned.

     * @param aValue On successful return, points

     * to the name of the specified attribute.

     * 

     * @return KErrNone if the attribute is found,

     * KErrNotFound if the specified attribute

     * cannot be found, ERcWrongParserState if 

     * the method fails.

     */

    virtual TInt AttributeName(TInt aIndex,

                               TPtrC8& aName) = 0;

    /**

     * Returns the value of the specified attribute

     * of the current element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aIndex The index (between 0 and 

     * AttbuteCount() - 1) of the attribute whose

     * value is to be returned.

     * @param aValue On successful return, points

     * to the value of the specified attribute.

     * 

     * @return KErrNone if the attribute is found,

     * KErrNotFound if the specified attribute

     * cannot be found, ERcWrongParserState if 

     * the method fails.

     */

    virtual TInt AttributeValuePredefEntitiesNotEscaped(TInt aIndex,

                                TPtrC8& aValue) = 0;

    /**

     * Returns the value of the specified attribute

     * of the current element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aName The name of the attribute whose

     * value is to be returned

     * @param aValue On successful return, points

     * to the value of the specified attribute.

     * 

     * @return KErrNone if the attribute is found,

     * KErrNotFound if the specified attribute

     * cannot be found, ERcWrongParserState if 

     * the method fails.

     */

    virtual TInt AttributeValuePredefEntitiesNotEscaped(const TDesC8& aName,

                                TPtrC8& aValue) = 0;

    /**

     * Returns the value of the specified attribute

     * of the current element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aIndex The index (between 0 and 

     * AttbuteCount() - 1) of the attribute whose

     * value is to be returned.

     * @param aValue On successful return, points

     * to the value of the specified attribute.

     * Character references have been escaped, i.e.

     * [   ->  [

     * ]  ->  ]

     * etc.

     * Also predefined entities have been escaped.

     * &lt;    ->  <

     * >    ->  >

     * &   ->  &

     * '  ->  '

     * "  ->  "

     * 

     * @return KErrNone if the attribute is found,

     * KErrNotFound if the specified attribute

     * cannot be found, ERcWrongParserState if 

     * the method fails.

     */

    virtual TInt AttributeValueL(TInt aIndex, 

                                TPtrC8& aValue) = 0;

    /**

     * Returns the value of the specified attribute

     * of the current element. The method is only

     * applicable if the parser state is EStateStartTag.

     *

     * @param aName The name of the attribute whose

     * value is to be returned

     * @param aValue On successful return, points

     * to the value of the specified attribute.

     * Character references have been escaped, i.e.

     * [   ->  [

     * ]  ->  ]

     * etc.

     * Also predefined entities have been escaped.

     * &lt;    ->  <

     * >    ->  >

     * &   ->  &

     * '  ->  '

     * "  ->  "

     * 

     * @return KErrNone if the attribute is found,

     * KErrNotFound if the specified attribute

     * cannot be found, ERcWrongParserState if 

     * the method fails.

     */

    virtual TInt AttributeValueL(const TDesC8& aName, 

                                TPtrC8& aValue) = 0;

    /**

     * Returns information as to whether the current

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

     * method is only applicable if the parser state 

     * is EStateStartTag.

     *

     * @param aIsEmptyElement On successful return, 

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

     * EFalse otherwise.

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if the method fails.

     */

    virtual TInt IsEmptyElement(TBool& aIsEmptyElement) = 0;

    /**

     * Returns the text of the current element.

     * This method is only applicable if the parser

     * state is EStateText.

     *

     * @param aText On successful return, points

     * to the text of the current element.

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if the method fails.

     */

    virtual TInt TextPredefEntitiesNotEscaped(TPtrC8& aText) = 0;

    /**

     * Returns the text of the current element.

     * This method is only applicable if the parser

     * state is EStateText.

     *

     * @param aText On successful return, points

     * to the text of the current element.

     * Character references have been escaped, i.e.

     * [   ->  [

     * ]  ->  ]

     * etc.

     * Also predefined entities have been escaped.

     * &lt;    ->  <

     * >    ->  >

     * &   ->  &

     * '  ->  '

     * "  ->  "

     * 

     * @return KErrNone if the method succeeds,

     * ERcWrongParserState if the method fails.

     */

    virtual TInt TextL(TPtrC8& aText) = 0;

    /**

     * Returns the current position of a virtual "cursor"

     * that is used to read the XML document.

     *

     * @return The cursor position

     */

    virtual TInt Pos() = 0;

    /**

     * Returns the start position of the current element.

     *

     * @return The current element start position

     */

    virtual TInt CurrentElementPos() = 0;

    /**

     * Returns the length of the XML document.

     *

     * @return The length of the XML document.

     */

    virtual TInt Length() = 0;

    /**

     * Returns the specified part of the XML document

     * being parsed to the caller

     *

     * @param aStartPos The position of the first character

     * to return

     * 

     * @param aEndPos The position of the last character

     * to return.

     * 

     * @return A part of the XML document being parsed

     */

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

    };

#endif // __XPP_API__