williamr@2: /*
williamr@2: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  CPosLandmarkEncoder class
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef CPOSLANDMARKENCODER_H
williamr@2: #define CPOSLANDMARKENCODER_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include "EPos_Landmarks.h"
williamr@2: #include "EPos_CPosLandmark.h"
williamr@2: #include "EPos_CPosLandmarkCategory.h"
williamr@2: #include "EPos_CPosLmOperation.h"
williamr@2: 
williamr@2: class CPosLandmarkEncoderExtension;
williamr@2: 
williamr@2: /**
williamr@2: *  Class used for encoding landmark content.
williamr@2: *
williamr@2: *  When creating an instance of this class, the type (e.g. the mime type) of
williamr@2: *  the landmark content must be specified. The client will then receive an
williamr@2: *  encoder implementation which understands the requested landmark content.
williamr@2: *
williamr@2: *  Output is written either to a buffer or to a file.
williamr@2: *
williamr@2: *  The basic protocol for encoding is to 
williamr@2: *  -# define where to write the output to by calling @ref SetUseOutputBufferL or 
williamr@2: *  @ref SetOutputFileL, 
williamr@2: *  -# optionally add collection data using @ref AddCollectionDataL,
williamr@2: *  -# add landmark data to encode by using functions in @ref CPosLandmarkEncoder
williamr@2: *  and/or @ref CPosLandmarkDatabase::ExportLandmarksL 
williamr@2: *  -# finalize the encoding by calling @ref FinalizeEncodingL. 
williamr@2: *
williamr@2: *  If this protocol is not followed
williamr@2: *  the client is panicked with error code @p EPosLmProtocolBreak. Encoding can
williamr@2: *  be performed multiple times using the same encoder object.
williamr@2: *
williamr@2: *  If @ref CPosLandmarkEncoder is used, the client must call the global
williamr@2: *  function @ref ReleaseLandmarkResources before terminating, in order to
williamr@2: *  release all used landmark resources, otherwise the client may receive
williamr@2: *  an ALLOC panic.
williamr@2: *
williamr@2: *  @lib eposlandmarks.lib
williamr@2: *  @since S60 3.0
williamr@2: */
williamr@2: class CPosLandmarkEncoder : public CBase
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor.
williamr@2:         *
williamr@2:         * The client must specify the type (e.g. the MIME type) of the content
williamr@2:         * format which should be used for encoding.
williamr@2:         *
williamr@2:         * @param[in] The MIME type of the encode format.
williamr@2:         * @return A new instance of this class.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported Content format is not supported.
williamr@2:         */
williamr@2:         IMPORT_C static CPosLandmarkEncoder* NewL( const TDesC8& aContentMimeType );
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CPosLandmarkEncoder();
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Encode to a buffer.
williamr@2:         *
williamr@2:         * This function returns a dynamic buffer which will be filled with
williamr@2:         * encoded landmark content. The client takes ownership of the buffer.
williamr@2:         *
williamr@2:         * The client must not delete the buffer until encoding is finalized.
williamr@2:         *
williamr@2:         * @return The output buffer.
williamr@2:         */
williamr@2:         virtual CBufBase* SetUseOutputBufferL() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Encode to a file.
williamr@2:         *
williamr@2:         * The client specifies an output file for the encoder. The encoder
williamr@2:         * will then write all encoded data to this file.
williamr@2:         *
williamr@2:         * The file will be opened in exclusive mode which means that the file
williamr@2:         * cannot be accessed until the file is closed. The file is closed when
williamr@2:         * @ref FinalizeEncodingL has been executed. The file is also closed
williamr@2:         * if a new encoding is initialized by a call to
williamr@2:         * @ref SetUseOutputBufferL or @ref SetOutputFileL. After this, further
williamr@2:         * encoding to the old file is not possible.
williamr@2:         *
williamr@2:         * @param[in] aOutputFile The file name to write the encoded data to.
williamr@2:         *
williamr@2:         * @leave KErrAlreadyExists Specified file already exists.
williamr@2:         */
williamr@2:         virtual void SetOutputFileL( const TDesC& aOutputFile ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Add landmark collection data to be encoded.
williamr@2:         *
williamr@2:         * @pre Output buffer or file is specified.
williamr@2:         *
williamr@2:         * Landmark collection data is generic information about the landmark
williamr@2:         * collection. It can for instance contain a name for the landmark
williamr@2:         * collection. Predefined collection attributes are defined by
williamr@2:         * @ref TPosLmCollectionDataId enumeration but also format specific
williamr@2:         * collection meta data can be defined.
williamr@2:         *
williamr@2:         * Collection data must be added before any landmarks are added.
williamr@2:         * Each collection ID can only be specified once.
williamr@2:         *
williamr@2:         * If the collection data is not a part of the chosen landmark encoding
williamr@2:         * format, it will be silently ignored.
williamr@2:         *
williamr@2:         * @param[in] aDataId Identifies which collection data to add.
williamr@2:         * @param[in] aCollectionData The collection data which should be added.
williamr@2:         *
williamr@2:         * @leave KErrAlreadyExists Collection data ID is specified twice.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosLmProtocolBreak 
williamr@2:         *   -# Output buffer or file not specified. 
williamr@2:         *   -# Collection data is added after some landmarks are added. 
williamr@2:         * @panic "Landmarks Client"-EPosLmInvalidArgument @p EPosLmCollDataNone is 
williamr@2:         *   specified as collection data ID.
williamr@2:         */
williamr@2:         virtual void AddCollectionDataL(
williamr@2:             TPosLmCollectionDataId aDataId,
williamr@2:             const TDesC& aCollectionData
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Add a landmark to be encoded.
williamr@2:         *
williamr@2:         * @pre Output buffer or file is specified.
williamr@2:         *
williamr@2:         * If the landmark contains any categories, those categories may be
williamr@2:         * added by calling @ref AddCategoryForLatestLandmarkL.
williamr@2:         *
williamr@2:         * The client can either call this function directly or pass this encoder
williamr@2:         * object to @ref CPosLandmarkDatabase::ExportLandmarksL.
williamr@2:         *
williamr@2:         * @param[in] aLandmark The landmark to add.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosLmProtocolBreak Output buffer or file not specified. 
williamr@2:         */
williamr@2:         virtual void AddLandmarkL( const CPosLandmark& aLandmark ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Add a landmark category for the most recently added landmark.
williamr@2:         *
williamr@2:         * @pre Output buffer or file is specified.
williamr@2:         *
williamr@2:         * The landmark category is added to the landmark which was most
williamr@2:         * recently added using @ref AddLandmarkL.
williamr@2:         *
williamr@2:         * The client can either call this function directly or pass this
williamr@2:         * encoder object to @ref CPosLandmarkDatabase::ExportLandmarksL.
williamr@2:         *
williamr@2:         * @param[in] aCategory The landmark category to add.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosLmProtocolBreak 
williamr@2:         *   -# Output buffer or file not specified. 
williamr@2:         *   -# No landmarks have been added yet.
williamr@2:         */
williamr@2:         virtual void AddCategoryForLatestLandmarkL(
williamr@2:             const CPosLandmarkCategory& aCategory
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Finalize the encode process.
williamr@2:         *
williamr@2:         * Writes any buffered data to the output buffer/file. If an output
williamr@2:         * buffer is used it is compressed so that unused memory is freed. If an
williamr@2:         * output file is used, it is closed.
williamr@2:         *
williamr@2:         * After finalizing, further encoding to the specified output is not
williamr@2:         * possible. To start a new encoding, @ref SetUseOutputBufferL or
williamr@2:         * @ref SetOutputFileL must be called.
williamr@2:         *
williamr@2:         * The function returns an operation object which can be run in
williamr@2:         * incremental mode. If it is run incrementally the client can supervise
williamr@2:         * the progress of the operation.
williamr@2:         *
williamr@2:         * The client takes ownership of the returned operation object.
williamr@2:         *
williamr@2:         * If the @ref CPosLmOperation object is deleted before the operation
williamr@2:         * is complete, finalize is cancelled. Further encoding will not be
williamr@2:         * possible.
williamr@2:         *
williamr@2:         * @return A handle to the operation.
williamr@2:         */
williamr@2:         virtual CPosLmOperation* FinalizeEncodingL() = 0;
williamr@2: 
williamr@2:     protected:
williamr@2: 
williamr@2:         // C++ constructor.
williamr@2:         IMPORT_C CPosLandmarkEncoder();
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // Prohibit copy constructor
williamr@2:         CPosLandmarkEncoder( const CPosLandmarkEncoder& );
williamr@2:         // Prohibit assigment operator
williamr@2:         CPosLandmarkEncoder& operator= ( const CPosLandmarkEncoder& );
williamr@2: 
williamr@2:     private:
williamr@2:         CPosLandmarkEncoderExtension* iExtension;
williamr@2: 
williamr@2:         // Implementation Uid
williamr@2:         TUid iDtorIdKey;
williamr@2:     };
williamr@2: 
williamr@2: #endif      // CPOSLANDMARKENCODER_H
williamr@2: 
williamr@2: