/*
* 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.
* < -> <
* > -> >
* & -> &
* ' -> '
* " -> "
*
* @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.
* < -> <
* > -> >
* & -> &
* ' -> '
* " -> "
*
* @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.
* < -> <
* > -> >
* & -> &
* ' -> '
* " -> "
*
* @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__