/*
* 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:  interface for Presence XML Serializer.
*
*/

#ifndef __MPENGXMLSERIALIZER_H
#define __MPENGXMLSERIALIZER_H

//  INCLUDES
#include <E32Std.h>


//CONSTANTS

/**
* Serializer panic reasons.
* @since 2.1
*/
enum TPEngSerializerPanics
    {
    EPEngSrlzr_AttributeNotAllowed = 0,
    EPEngSrlzr_EndTagNotAllowed = 1,
    EPEngSrlzr_EmptyInputString = 2,
    EPEngSrlzr_EndTagNameMismatch = 3,
    EPEngSrlzr_StateStackUnderflow = 4,
    EPEngSrlzr_XmlMarkupCharNotAllowed = 5,
    };

/**
* Serializer panic category.
* @since 2.1
*/
_LIT( KXmlSerializer, "XMLSerializ" );




//FORWARD DECLARATION
class MPEngXMLSerializer;


// FUNCTION PROTOTYPES

/**
 * Factory method to create XML Serializer.
 *
 * @since 3.0
 */
IMPORT_C MPEngXMLSerializer* CreateXmlSerializerL( TDes8& aBuffer );
IMPORT_C MPEngXMLSerializer* CreateXmlSerializerLC( TDes8& aBuffer );





//  CLASS DEFINITION
/**
* This class defines the interface for Presence XML Serializer.
* XML serializer is used for generating XML fragments.
*
* It offers features to write XML tags, XML attributes and actual
* XML fragment content.
*
* @since 2.1
*/
class MPEngXMLSerializer
    {
    public: //Element handling methods

        /**
         * Writes a start tag.
         *
         * Writes a start tag with the given name.
         * If aName is zero length descriptor,
         * panics in debug builds with EEmptyInputString
         * and release builds leaves with KErrArgument.
         *
         * @since 2.1
         * @param aName Tags name.
         * @return Self.
         */
        virtual MPEngXMLSerializer& StartTagL( const TDesC8& aName ) = 0;


        /**
         * Writes an attribute.
         *
         * Attributes must be written directly after starting
         * the tag with StartTagL() method. It is possible write
         * several attributes by issuing multiple calls to AttributeL().
         * If attribute isn't written directly after starting the tag,
         * panics in debug builds with EPEngSrlzr_AttributeNotAllowed and
         * leaves on release builds with KErrNotSupported.
         *
         * If aName is empty descriptor, panics in debug
         * builds with EPEngSrlzr_EmptyInputString and release
         * builds leaves with KErrArgument. However, aValue can
         * be empty descriptor.
         *
         * @since 2.1
         * @param aName The attribute name.
         * @param aValue The attribute value.
         * @return Self.
         */
        virtual MPEngXMLSerializer& AttributeL( const TDesC8& aName,
                                                const TDesC8& aValue ) = 0;


        /**
         * Writes end tag.
         *
         * Writes end tag with the given name.
         * (Closes thus lastly written start tag.)
         *
         * If there isn't any start tag to close, panics in debug
         * builds with EPEngSrlzr_EndTagNotAllowed and release builds
         * leaves with KErrNotSupported.
         *
         * If aName is zero length descriptor,
         * panics in debug builds with EPEngSrlzr_EmptyInputString
         * and release builds leaves with KErrArgument.
         *
         * If passed end tag name aName doesn't match corresponding
         * start tag name, panics in debug builds with
         * EPEngSrlzr_EndTagNameMismatch.
         * For performance reasons this check isn't done on
         * release builds ==> possible end tag name mismatches
         * are ignored in release builds.
         *
         * @since 2.1
         * @param aName Tag name.
         * @return Self.
         */
        virtual MPEngXMLSerializer& EndTagL( const TDesC8& aName ) = 0;




    public: //Content writing methods


        /**
         * Writes raw protocol value without _ANY_ encoding.
         *
         * Checks the written value doesn't contain XML markup characters.
         * If it contains, handles the error with panic:
         * EPEngSrlzr_XmlMarkupCharNotAllowed.
         *
         * @since 3.0
         * @param aValue Raw protocol value to write.
         * @return Self.
         */
        virtual MPEngXMLSerializer& RawValueL( const TDesC8& aValue ) = 0;


        /**
         * Writes 8 bit text.
         *
         * Performed steps:
         * 1. Escapes XML entities.
         *
         * @since 3.0
         * @param aText Text to write.
         * @return Self.
         */
        virtual MPEngXMLSerializer& NarrowTextL( const TDesC8& aText ) = 0;


        /**
         * Writes Unicode text.
         *
         * Performed steps:
         * 1. Converts text from Unicode to Utf8
         * 2. Escapes XML entities
         *
         * @since 3.0
         * @param aText Text to write.
         * @return Self.
         */
        virtual MPEngXMLSerializer& UnicodeTextL( const TDesC16& aText ) = 0;


        /**
         * Writes WV Address.
         *
         * Performed steps:
         * 1. Escapes WV Address characters
         * 2. Converts text from Unicode to Utf8
         * 3. Escape XML entities
         *
         * @since 3.0
         * @param aAddress Address to write.
         * @return Self.
         */
        virtual MPEngXMLSerializer& WvAddressL( const TDesC16& aAddress ) = 0;


        /**
         * Writes data in BASE64 format.
         *
         * Performed steps:
         * 1. Coverts data to BASE64 format
         *
         * @since 3.0
         * @param aData The data to write.
         * @return Self.
         */
        virtual MPEngXMLSerializer& Base64DataL( const TDesC8& aData ) = 0;






    public: //Serializer state handling methods

        /**
         * Stores serializer current state.
         *
         * Stores serializer current state to its internal
         * state stack. State consists from previously generated
         * XML fragment and other serializer internal data.
         *
         * States are stored to stack like structure and later
         * serializer state can be restored back to pushed state
         * or pushed state can be committed.
         *
         * On serializer destruction all previously pushed
         * states are committed automaticly.
         *
         * @since 2.1
         */
        virtual void PushSerializerStateL() = 0;

        /**
         * Commits topmost state in the state stack.
         *
         * Commits topmost state in the serializer
         * state stack. If there isn't any state to
         * commit, panics in debug builds with
         * EPEngSrlzr_StateStackUnderflow. In
         * release builds underflow is ignored.
         *
         * @since 2.1
         */
        virtual void CommitState() = 0;

        /**
         * Rollbacks the serializer state to topmost
         * state in the state stack.
         *
         * Rollbacks the serializer state to topmost
         * state in the state stack. If there isn't
         * any state to commit, panics in debug builds
         * with EPEngSrlzr_StateStackUnderflow. In
         * release builds underflow is ignored.
         *
         * @since 2.1
         */
        virtual void RollbackState() = 0;

        /**
         * Gets the count of pushed states.
         *
         * @since 2.1
         * @return Count of pushed states.
         */
        virtual TInt PushedStateCount() = 0;


    public: //Destructor & Cleanup support

        /**
         *  Release method.
         *  When called, deletes object and
         *  frees all its resources.
         *
         *  Concrete serializer 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 ~MPEngXMLSerializer() {}

    };

#endif      //__MPENGXMLSERIALIZER_H


//  End of File