1 epos_cposlandmarkencoder.h

     1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CPosLandmarkEncoder class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLANDMARKENCODER_H

    20 #define CPOSLANDMARKENCODER_H

    21 

    22 #include <e32base.h>

    23 #include "EPos_Landmarks.h"

    24 #include "EPos_CPosLandmark.h"

    25 #include "EPos_CPosLandmarkCategory.h"

    26 #include "EPos_CPosLmOperation.h"

    27 

    28 class CPosLandmarkEncoderExtension;

    29 

    30 /**

    31 *  Class used for encoding landmark content.

    32 *

    33 *  When creating an instance of this class, the type (e.g. the mime type) of

    34 *  the landmark content must be specified. The client will then receive an

    35 *  encoder implementation which understands the requested landmark content.

    36 *

    37 *  Output is written either to a buffer or to a file.

    38 *

    39 *  The basic protocol for encoding is to 

    40 *  -# define where to write the output to by calling @ref SetUseOutputBufferL or 

    41 *  @ref SetOutputFileL, 

    42 *  -# optionally add collection data using @ref AddCollectionDataL,

    43 *  -# add landmark data to encode by using functions in @ref CPosLandmarkEncoder

    44 *  and/or @ref CPosLandmarkDatabase::ExportLandmarksL 

    45 *  -# finalize the encoding by calling @ref FinalizeEncodingL. 

    46 *

    47 *  If this protocol is not followed

    48 *  the client is panicked with error code @p EPosLmProtocolBreak. Encoding can

    49 *  be performed multiple times using the same encoder object.

    50 *

    51 *  If @ref CPosLandmarkEncoder is used, the client must call the global

    52 *  function @ref ReleaseLandmarkResources before terminating, in order to

    53 *  release all used landmark resources, otherwise the client may receive

    54 *  an ALLOC panic.

    55 *

    56 *  @lib eposlandmarks.lib

    57 *  @since S60 3.0

    58 */

    59 class CPosLandmarkEncoder : public CBase

    60     {

    61     public:

    62 

    63         /**

    64         * Two-phased constructor.

    65         *

    66         * The client must specify the type (e.g. the MIME type) of the content

    67         * format which should be used for encoding.

    68         *

    69         * @param[in] The MIME type of the encode format.

    70         * @return A new instance of this class.

    71         *

    72         * @leave KErrNotSupported Content format is not supported.

    73         */

    74         IMPORT_C static CPosLandmarkEncoder* NewL( const TDesC8& aContentMimeType );

    75 

    76         /**

    77         * Destructor.

    78         */

    79         IMPORT_C virtual ~CPosLandmarkEncoder();

    80 

    81     public:

    82 

    83         /**

    84         * Encode to a buffer.

    85         *

    86         * This function returns a dynamic buffer which will be filled with

    87         * encoded landmark content. The client takes ownership of the buffer.

    88         *

    89         * The client must not delete the buffer until encoding is finalized.

    90         *

    91         * @return The output buffer.

    92         */

    93         virtual CBufBase* SetUseOutputBufferL() = 0;

    94 

    95         /**

    96         * Encode to a file.

    97         *

    98         * The client specifies an output file for the encoder. The encoder

    99         * will then write all encoded data to this file.

   100         *

   101         * The file will be opened in exclusive mode which means that the file

   102         * cannot be accessed until the file is closed. The file is closed when

   103         * @ref FinalizeEncodingL has been executed. The file is also closed

   104         * if a new encoding is initialized by a call to

   105         * @ref SetUseOutputBufferL or @ref SetOutputFileL. After this, further

   106         * encoding to the old file is not possible.

   107         *

   108         * @param[in] aOutputFile The file name to write the encoded data to.

   109         *

   110         * @leave KErrAlreadyExists Specified file already exists.

   111         */

   112         virtual void SetOutputFileL( const TDesC& aOutputFile ) = 0;

   113 

   114         /**

   115         * Add landmark collection data to be encoded.

   116         *

   117         * @pre Output buffer or file is specified.

   118         *

   119         * Landmark collection data is generic information about the landmark

   120         * collection. It can for instance contain a name for the landmark

   121         * collection. Predefined collection attributes are defined by

   122         * @ref TPosLmCollectionDataId enumeration but also format specific

   123         * collection meta data can be defined.

   124         *

   125         * Collection data must be added before any landmarks are added.

   126         * Each collection ID can only be specified once.

   127         *

   128         * If the collection data is not a part of the chosen landmark encoding

   129         * format, it will be silently ignored.

   130         *

   131         * @param[in] aDataId Identifies which collection data to add.

   132         * @param[in] aCollectionData The collection data which should be added.

   133         *

   134         * @leave KErrAlreadyExists Collection data ID is specified twice.

   135         *

   136         * @panic "Landmarks Client"-EPosLmProtocolBreak 

   137         *   -# Output buffer or file not specified. 

   138         *   -# Collection data is added after some landmarks are added. 

   139         * @panic "Landmarks Client"-EPosLmInvalidArgument @p EPosLmCollDataNone is 

   140         *   specified as collection data ID.

   141         */

   142         virtual void AddCollectionDataL(

   143             TPosLmCollectionDataId aDataId,

   144             const TDesC& aCollectionData

   145         ) = 0;

   146 

   147         /**

   148         * Add a landmark to be encoded.

   149         *

   150         * @pre Output buffer or file is specified.

   151         *

   152         * If the landmark contains any categories, those categories may be

   153         * added by calling @ref AddCategoryForLatestLandmarkL.

   154         *

   155         * The client can either call this function directly or pass this encoder

   156         * object to @ref CPosLandmarkDatabase::ExportLandmarksL.

   157         *

   158         * @param[in] aLandmark The landmark to add.

   159         *

   160         * @panic "Landmarks Client"-EPosLmProtocolBreak Output buffer or file not specified. 

   161         */

   162         virtual void AddLandmarkL( const CPosLandmark& aLandmark ) = 0;

   163 

   164         /**

   165         * Add a landmark category for the most recently added landmark.

   166         *

   167         * @pre Output buffer or file is specified.

   168         *

   169         * The landmark category is added to the landmark which was most

   170         * recently added using @ref AddLandmarkL.

   171         *

   172         * The client can either call this function directly or pass this

   173         * encoder object to @ref CPosLandmarkDatabase::ExportLandmarksL.

   174         *

   175         * @param[in] aCategory The landmark category to add.

   176         *

   177         * @panic "Landmarks Client"-EPosLmProtocolBreak 

   178         *   -# Output buffer or file not specified. 

   179         *   -# No landmarks have been added yet.

   180         */

   181         virtual void AddCategoryForLatestLandmarkL(

   182             const CPosLandmarkCategory& aCategory

   183         ) = 0;

   184 

   185         /**

   186         * Finalize the encode process.

   187         *

   188         * Writes any buffered data to the output buffer/file. If an output

   189         * buffer is used it is compressed so that unused memory is freed. If an

   190         * output file is used, it is closed.

   191         *

   192         * After finalizing, further encoding to the specified output is not

   193         * possible. To start a new encoding, @ref SetUseOutputBufferL or

   194         * @ref SetOutputFileL must be called.

   195         *

   196         * The function returns an operation object which can be run in

   197         * incremental mode. If it is run incrementally the client can supervise

   198         * the progress of the operation.

   199         *

   200         * The client takes ownership of the returned operation object.

   201         *

   202         * If the @ref CPosLmOperation object is deleted before the operation

   203         * is complete, finalize is cancelled. Further encoding will not be

   204         * possible.

   205         *

   206         * @return A handle to the operation.

   207         */

   208         virtual CPosLmOperation* FinalizeEncodingL() = 0;

   209 

   210     protected:

   211 

   212         // C++ constructor.

   213         IMPORT_C CPosLandmarkEncoder();

   214 

   215     private:

   216 

   217         // Prohibit copy constructor

   218         CPosLandmarkEncoder( const CPosLandmarkEncoder& );

   219         // Prohibit assigment operator

   220         CPosLandmarkEncoder& operator= ( const CPosLandmarkEncoder& );

   221 

   222     private:

   223         CPosLandmarkEncoderExtension* iExtension;

   224 

   225         // Implementation Uid

   226         TUid iDtorIdKey;

   227     };

   228 

   229 #endif      // CPOSLANDMARKENCODER_H

   230 

   231