/*
* Copyright (c) 2004 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:  XML Parser implementation
*
*/

#ifndef MPENGPARSER_H
#define MPENGPARSER_H

#include "PEngXMLTags.h"
#include "MPEngAdvTransactionStatus2.h"



//FORWARD DECLARATION
class MPEngXMLParser;




// FUNCTION PROTOTYPES

/**
 * Factory method to create XML Parser.
 *
 * @since 3.0
 */
IMPORT_C MPEngXMLParser* CreateXMLParserL();
IMPORT_C MPEngXMLParser* CreateXMLParserLC();





//  CLASS DEFINITION
/**
 * This class defines the interface for Presence XML Parser.
 * XML parser is used to parse XML data.
 *
 * @since 2.1
 */
class MPEngXMLParser
    {
    public: //Parsing functions


        /**
         * Decodes given XML data according to the given string to be found.
         * @param aBuffer Initial data to be parsed
         * @param aString The tag name to be searched
         * @param aTags Tells if the tags are included in the result
         * @param aLevel Restricts the parsing to a certain tag level, 0 means
         *                that there's no restrictions
         * @return TBool The boolean value of how decoding went.
         */
        virtual TBool DecodeL( const TDesC8& aBuffer,
                               const TDesC8& aString,
                               TBool aTags,
                               TInt aLevel = 0 ) = 0;


        /**
         * Gets the number of decode results.
         * @return TInt number of results.
         */
        virtual TInt Count() = 0;



        /**
         * Gets raw result from the decoded result array.
         *
         * @param aIndex the wanted result
         * @return TPtrC8 a pointer to the result data
         */
        virtual TPtrC8 ResultL( TInt aIndex = 0 ) = 0;



        /**
         * Gets narrow text from the decoded result array.
         *
         * Performed steps:
         * 1. UnEscapes XML entities.
         *
         * @param aIndex Index of wanted result.
         * @return Narrow text. Buffer ownership is returned to caller.
         */
        virtual HBufC8* ResultAsNarrowTextL( TInt aIndex = 0 ) = 0;



        /**
         * Gets unicode text from the decoded result array.
         *
         * Performed steps:
         * 1. UnEscapes XML entities.
         * 2. Converts text from Utf8 to Unicode.
         *
         * @param aIndex Index of wanted result.
         * @return Unicode text. Buffer ownership is returned to caller.
         */
        virtual HBufC16* ResultAsUnicodeTextL( TInt aIndex = 0 ) = 0;



        /**
         * Gets WV Address from the decoded result array.
         *
         * Performed steps:
         * 1. UnEscapes XML entities.
         * 2. Converts text from Utf8 to Unicode.
         * 3. UnEscapes WV Address characters
         *
         * @param aIndex Index of wanted result.
         * @return WV Address. Buffer ownership is returned to caller.
         */
        virtual HBufC16* ResultAsWVAddressL( TInt aIndex = 0 ) = 0;



        /**
         * Gets Base64Decodeddata from the decoded result array.
         *
         * Performed steps:
         * 1. Coverts data from the BASE64 format
         *
         * @param aIndex Index of wanted result.
         * @return Base64 decoded text. Buffer ownership is returned to caller.
         */
        virtual HBufC8* ResultAsBase64DecodedL( TInt aIndex = 0 ) = 0;




    public: //Transaction result parsing functions


        /**
         * Parses the transaction result from the XML data.
         * Overloaded version to allow client to define
         * wether the valid result structure is required or not.
         *
         * @param aBuffer The XML buffer containing the response
         * @param aTransactionOperation The TransactionOperation that
         * caused the possible detailed errors.
         * @param aStatus MPEngAdvTransactionStatus object where the
         * userIDs and return values are stored.
         * @param aResultRequired If ETrue, the valid result
         * structure is required. If EFalse, or valid result
         * structure is not required. If valid result
         * structure is required but it isnt found from XML,
         * parser generates KPEngNwErrInternalServerOrNetworkError.
         * On the return aResultRequired contains ETrue, if valid
         * structure was found. Else EFalse.
         * @return The main result value from transaction status.
         */
        virtual TInt ParseResultL( const TDesC8& aBuffer,
                                   TInt aTransactionOperation,
                                   MPEngAdvTransactionStatus2& aStatus,
                                   TBool& aResultRequired ) = 0;

        /**
         * Parses the transaction result from the XML data.
         * Overloaded version requiring the valid result
         * structure.
         *
         * @param aBuffer The XML buffer containing the response
         * @param aTransactionOperation The TransactionOperation that
         * caused the possible detailed errors.
         * @param aStatus MPEngAdvTransactionStatus object where the
         * userIDs and return values are stored.
         * @return The main result value from transaction status.
         */
        virtual TInt ParseResultL( const TDesC8& aBuffer,
                                   TInt aTransactionOperation,
                                   MPEngAdvTransactionStatus2& aStatus ) = 0;

        /**
         * Parses the transaction result from the XML data.
         * Client can pass the contact list id, where the results relate.
         * Requires the valid result structure.
         *
         * @param aBuffer The XML buffer containing the response
         * @param aTransactionOperation The TransactionOperation that
         * caused the possible detailed errors.
         * @param aStatus MPEngAdvTransactionStatus object where the
         * userIDs and return values are stored.
         * @param aContactList The name of the contact list this result was
         * attached to.
         * @return The main result value from transaction status.
         */
        virtual TInt ParseContactListResultL( const TDesC8& aBuffer,
                                              TInt aTransactionOperation,
                                              const TDesC& aContactList,
                                              MPEngAdvTransactionStatus2& aStatus ) = 0;




    public: //Destructor & Cleanup support

        /**
         *  Release method.
         *  When called, deletes object and
         *  frees all its resources.
         *
         *  Concrete parser object can be thus pushed
         *  on the CleanupStack using CleanupClosePushL().
         */
        virtual void Close() = 0;


        /**
         * Inline virtual destructor.
         * Concrete instancies can be deleted
         * trough this interface.
         */
        virtual ~MPEngXMLParser() {}


    };

#endif      //  MPENGPARSER_H

//  End of File