/*
* Copyright (c) 2002-2007 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: Class used for encoding xml landmark content.
*
*/


#ifndef CPOSLMXMLENCODER_H
#define CPOSLMXMLENCODER_H

#include <EPos_CPosLandmarkEncoder.h>
#include "EPos_LmConverter.h"

class CPosLmOutput;

/**
*  Class used for encoding xml landmark content.
*
*  Output is written either to a buffer or to a file.
*
*  The basic protocol for encoding is to 1) define where to write the
*  output to by calling @ref SetUseOutputBufferL or @ref SetOutputFileL, 2)
*  optionally add collection data using @ref AddCollectionDataL, 3) add
*  landmark data to encode by using functions in @ref CPosLandmarkEncoder
*  and/or @ref CPosLandmarkDatabase::ExportLandmarksL and 4) finalize the
*  encoding by calling @ref FinalizeEncodingL. If this protocol is not followed
*  the client is panicked with code @p EPosLmProtocolBreak. Encoding can be
*  performed multiple times using the same encoder object.
*
*/
class CPosLmXmlEncoder : public CPosLandmarkEncoder
    {
    public:  

        /**
        * Destructor.
        */
        ~CPosLmXmlEncoder();

    public: // From CPosLandmarkEncoder

        CBufBase* SetUseOutputBufferL();

        void SetOutputFileL( const TDesC&  aOutputFile );

        void AddCollectionDataL(
            TPosLmCollectionDataId  aDataId,
            const TDesC&  aCollectionData );

        void AddLandmarkL( const CPosLandmark&  aLandmark );

        void AddCategoryForLatestLandmarkL( const CPosLandmarkCategory&  aCategory );

        CPosLmOperation* FinalizeEncodingL();

    protected:
    
        /** Writes start tags. At least root tag should be written */
        virtual void WriteStartTagsL() = 0;
        
        /** Writes collection name and description, if supported */
        virtual void WriteCollectionDataL( 
            const HBufC* aCollectionName,
            const HBufC* aCollectionDescription ) = 0;
        
        /** Writes landmark with categories */
        virtual void WriteLandmarkL( 
            const CPosLandmark& aLandmark, 
            const RPointerArray<const CPosLandmarkCategory>& aCategories ) = 0;
        
        /** Writes end tags. At least root tag closure should be written, but also
         *  any other tag added in WriteStartTagsL should be closed */
        virtual void WriteFinalTagsL() = 0;

        /** Returns string of tag name for given tag type */
        virtual TPtrC TagNameL( TPosXmlTagType aTagType ) = 0;

    protected:
      
        /**
         * Checks if the specified tag type is a leaf or a branch.
         *
         * @param aXmlTagType The tag type.
         * @return ETrue if the tag type is a leaf,
         *   EFalse if the tag type is a branch.
         */
         TBool IsTagLeaf( TPosXmlTagType aXmlTagType );

         /** Writes XML prolog */
         void WritePrologL();

         /** Writes start of XML tag with attributes string */
         void WriteSTagL( TPosXmlTagType aTagType, const TDesC& aAttributes );

         /** Writes end of XML tag */
         void WriteETagL( TPosXmlTagType aTagType );

         /** Writes full leaf tag with string value 
          *  @param aDes tag value 
          *  @param aTagType tag type */
         void WriteStringWithTagsL( const TDesC16& aDes, TPosXmlTagType aTagType );

         /** Writes full leaf tag with real value 
          *  @param aValue tag value 
          *  @param aTagType tag type */
         void WriteTRealWithTagsL( TReal aValue, TPosXmlTagType aTagType );

         /** Writes string value escaping prohibited characters
          *  @param aDes tag value */
         void WriteEscapedStringL( const TDesC& aDes );

    private:

        CBufBase* CreateOutPutBufferLC();

        void CreateOutputFileL( const TDesC&  aOutputFile );

        /** Starts encoding. Writes prolog string. */
        void InitializeEncodingL();
        
        void ResetEncoderL();

        HBufC16* IndentationLC();
        void ResetIndentation();
        
        /**
         * Get the prolog string.
         * Caller takes ownership of the returned string.
         *
         * @return The prolog string.
         */
        static HBufC16* PrologStringLC();
        
         /**
         * Get the start tag for the specified tag type.
         * Caller takes ownership of the returned string.
         *
         * @param aTagType The tag type.
         * @param aAttributes String of attributes if any needed.
         * @return The start tag.
         */
        HBufC16* STagStringLC( TPosXmlTagType aTagType, const TDesC& aAttributes );
        
         /**
         * Get the end tag for the specified tag type.
         * Caller takes ownership of the returned string.
         *
         * @param aTagType The tag type.
         * @return The end tag.
         */
        HBufC16* ETagStringLC( TPosXmlTagType aTagType );
        
        /** Dumps last added landmark with categories */
        void WriteLastLandmarkL();
        
    protected:
        CPosLmXmlEncoder();
        
    private:
        // Prohibit copy constructor
        CPosLmXmlEncoder( const CPosLmXmlEncoder& );
        // Prohibit assigment operator
        CPosLmXmlEncoder& operator= ( const CPosLmXmlEncoder& );

    protected:
        CPosLandmark* iLastLandmark;
        RPointerArray<const CPosLandmarkCategory> iCategories;
    
    private:    // Data

        enum TPosEncoderStatus
            {
            EPosUninitialized = 0,
            EPosInitialized,
            EPosCollectionInfoAdded,
            EPosLmInfoAdded
            };

        TPosEncoderStatus           iEncoderStatus;

        CPosLmOutput*               iOutput;

        HBufC*                      iCollectionDataName;
        HBufC*                      iCollectionDataDescription;

        TInt                        iIndentationDepth;
    };

#endif      // CPOSLMXMLENCODER_H