/*
* Copyright (c) 2005-2006 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:  CPosLandmarkEncoder class
*
*/


#ifndef CPOSLANDMARKENCODER_H
#define CPOSLANDMARKENCODER_H

#include <e32base.h>
#include "EPos_Landmarks.h"
#include "EPos_CPosLandmark.h"
#include "EPos_CPosLandmarkCategory.h"
#include "EPos_CPosLmOperation.h"

class CPosLandmarkEncoderExtension;

/**
*  Class used for encoding landmark content.
*
*  When creating an instance of this class, the type (e.g. the mime type) of
*  the landmark content must be specified. The client will then receive an
*  encoder implementation which understands the requested landmark content.
*
*  Output is written either to a buffer or to a file.
*
*  The basic protocol for encoding is to 
*  -# define where to write the output to by calling @ref SetUseOutputBufferL or 
*  @ref SetOutputFileL, 
*  -# optionally add collection data using @ref AddCollectionDataL,
*  -# add landmark data to encode by using functions in @ref CPosLandmarkEncoder
*  and/or @ref CPosLandmarkDatabase::ExportLandmarksL 
*  -# finalize the encoding by calling @ref FinalizeEncodingL. 
*
*  If this protocol is not followed
*  the client is panicked with error code @p EPosLmProtocolBreak. Encoding can
*  be performed multiple times using the same encoder object.
*
*  If @ref CPosLandmarkEncoder is used, the client must call the global
*  function @ref ReleaseLandmarkResources before terminating, in order to
*  release all used landmark resources, otherwise the client may receive
*  an ALLOC panic.
*
*  @lib eposlandmarks.lib
*  @since S60 3.0
*/
class CPosLandmarkEncoder : public CBase
    {
    public:

        /**
        * Two-phased constructor.
        *
        * The client must specify the type (e.g. the MIME type) of the content
        * format which should be used for encoding.
        *
        * @param[in] The MIME type of the encode format.
        * @return A new instance of this class.
        *
        * @leave KErrNotSupported Content format is not supported.
        */
        IMPORT_C static CPosLandmarkEncoder* NewL( const TDesC8& aContentMimeType );

        /**
        * Destructor.
        */
        IMPORT_C virtual ~CPosLandmarkEncoder();

    public:

        /**
        * Encode to a buffer.
        *
        * This function returns a dynamic buffer which will be filled with
        * encoded landmark content. The client takes ownership of the buffer.
        *
        * The client must not delete the buffer until encoding is finalized.
        *
        * @return The output buffer.
        */
        virtual CBufBase* SetUseOutputBufferL() = 0;

        /**
        * Encode to a file.
        *
        * The client specifies an output file for the encoder. The encoder
        * will then write all encoded data to this file.
        *
        * The file will be opened in exclusive mode which means that the file
        * cannot be accessed until the file is closed. The file is closed when
        * @ref FinalizeEncodingL has been executed. The file is also closed
        * if a new encoding is initialized by a call to
        * @ref SetUseOutputBufferL or @ref SetOutputFileL. After this, further
        * encoding to the old file is not possible.
        *
        * @param[in] aOutputFile The file name to write the encoded data to.
        *
        * @leave KErrAlreadyExists Specified file already exists.
        */
        virtual void SetOutputFileL( const TDesC& aOutputFile ) = 0;

        /**
        * Add landmark collection data to be encoded.
        *
        * @pre Output buffer or file is specified.
        *
        * Landmark collection data is generic information about the landmark
        * collection. It can for instance contain a name for the landmark
        * collection. Predefined collection attributes are defined by
        * @ref TPosLmCollectionDataId enumeration but also format specific
        * collection meta data can be defined.
        *
        * Collection data must be added before any landmarks are added.
        * Each collection ID can only be specified once.
        *
        * If the collection data is not a part of the chosen landmark encoding
        * format, it will be silently ignored.
        *
        * @param[in] aDataId Identifies which collection data to add.
        * @param[in] aCollectionData The collection data which should be added.
        *
        * @leave KErrAlreadyExists Collection data ID is specified twice.
        *
        * @panic "Landmarks Client"-EPosLmProtocolBreak 
        *   -# Output buffer or file not specified. 
        *   -# Collection data is added after some landmarks are added. 
        * @panic "Landmarks Client"-EPosLmInvalidArgument @p EPosLmCollDataNone is 
        *   specified as collection data ID.
        */
        virtual void AddCollectionDataL(
            TPosLmCollectionDataId aDataId,
            const TDesC& aCollectionData
        ) = 0;

        /**
        * Add a landmark to be encoded.
        *
        * @pre Output buffer or file is specified.
        *
        * If the landmark contains any categories, those categories may be
        * added by calling @ref AddCategoryForLatestLandmarkL.
        *
        * The client can either call this function directly or pass this encoder
        * object to @ref CPosLandmarkDatabase::ExportLandmarksL.
        *
        * @param[in] aLandmark The landmark to add.
        *
        * @panic "Landmarks Client"-EPosLmProtocolBreak Output buffer or file not specified. 
        */
        virtual void AddLandmarkL( const CPosLandmark& aLandmark ) = 0;

        /**
        * Add a landmark category for the most recently added landmark.
        *
        * @pre Output buffer or file is specified.
        *
        * The landmark category is added to the landmark which was most
        * recently added using @ref AddLandmarkL.
        *
        * The client can either call this function directly or pass this
        * encoder object to @ref CPosLandmarkDatabase::ExportLandmarksL.
        *
        * @param[in] aCategory The landmark category to add.
        *
        * @panic "Landmarks Client"-EPosLmProtocolBreak 
        *   -# Output buffer or file not specified. 
        *   -# No landmarks have been added yet.
        */
        virtual void AddCategoryForLatestLandmarkL(
            const CPosLandmarkCategory& aCategory
        ) = 0;

        /**
        * Finalize the encode process.
        *
        * Writes any buffered data to the output buffer/file. If an output
        * buffer is used it is compressed so that unused memory is freed. If an
        * output file is used, it is closed.
        *
        * After finalizing, further encoding to the specified output is not
        * possible. To start a new encoding, @ref SetUseOutputBufferL or
        * @ref SetOutputFileL must be called.
        *
        * The function returns an operation object which can be run in
        * incremental mode. If it is run incrementally the client can supervise
        * the progress of the operation.
        *
        * The client takes ownership of the returned operation object.
        *
        * If the @ref CPosLmOperation object is deleted before the operation
        * is complete, finalize is cancelled. Further encoding will not be
        * possible.
        *
        * @return A handle to the operation.
        */
        virtual CPosLmOperation* FinalizeEncodingL() = 0;

    protected:

        // C++ constructor.
        IMPORT_C CPosLandmarkEncoder();

    private:

        // Prohibit copy constructor
        CPosLandmarkEncoder( const CPosLandmarkEncoder& );
        // Prohibit assigment operator
        CPosLandmarkEncoder& operator= ( const CPosLandmarkEncoder& );

    private:
        CPosLandmarkEncoderExtension* iExtension;

        // Implementation Uid
        TUid iDtorIdKey;
    };

#endif      // CPOSLANDMARKENCODER_H