diff -r 000000000000 -r 33413c0669b9 vpnengine/utlxml/inc/XppApi.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/vpnengine/utlxml/inc/XppApi.h Thu Dec 17 09:14:51 2009 +0200 @@ -0,0 +1,346 @@ +/* +* 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 + +/** + * 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__