1 epos_cposlandmarkparser.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:  CPosLandmarkParser class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLANDMARKPARSER_H

    20 #define CPOSLANDMARKPARSER_H

    21 

    22 #include <e32base.h>

    23 #include <f32file.h>

    24 #include "EPos_Landmarks.h"

    25 #include "EPos_CPosLandmark.h"

    26 #include "EPos_CPosLandmarkCategory.h"

    27 #include "EPos_CPosLmOperation.h"

    28 

    29 class CPosLandmarkParserExtension;

    30 

    31 /**

    32 *  Class used for parsing landmark content.

    33 *

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

    35 *  the landmark content must be specified. The client will then receive a

    36 *  parser implementation which understands the requested landmark content.

    37 *

    38 *  The client specifies landmark content either in a buffer or in a file. The

    39 *  buffer/file is needed until the client no longer uses the parser object for

    40 *  accessing the parsed data. If the buffer/file is deleted or modified, it

    41 *  may not be possible to access the parsed landmark data.

    42 *

    43 *  @ref ParseContentL returns a @ref CPosLmOperation which means parsing can

    44 *  be run incrementally. Each call to @ref CPosLmOperation::NextStep parses

    45 *  one landmark. The landmark can be retrieved by calling @ref LandmarkLC.

    46 *

    47 *  Optionally, the client can specify that the parser should build an index.

    48 *  An index enables direct access to all landmarks when the content has been

    49 *  fully parsed. The content is fully parsed when CPosLmOperation::NextStep

    50 *  or CPosLmOperation::ExecuteL complete with KErrNone. The @ref LandmarkLC method

    51 *  then can be called with landmark index to directly access any of parsed

    52 *  landmarks.

    53 *

    54 *  If @ref CPosLandmarkParser is used, the client must call the global

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

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

    57 *  an ALLOC panic.

    58 *

    59 *  @lib eposlandmarks.lib

    60 *  @since S60 3.0

    61 */

    62 class CPosLandmarkParser : public CBase

    63     {

    64     public:

    65 

    66         /**

    67         * Two-phased constructor.

    68         *

    69         * The client must specify the type (e.g. the mime type) of the landmark

    70         * content which should be parsed. 

    71         *

    72         * @param[in] The mime-type of the content to parse.

    73         * @return A new instance of this class.

    74         *

    75         * @leave KErrNotSupported Content format is not supported.

    76         */

    77         IMPORT_C static CPosLandmarkParser* NewL( const TDesC8& aContentMimeType );

    78 

    79         /**

    80         * Destructor.

    81         */

    82         IMPORT_C virtual ~CPosLandmarkParser();

    83 

    84     public:

    85 

    86         /**

    87         * Sets the buffer to be parsed.

    88         *

    89         * The parser does not copy the data which means the buffer must not

    90         * be deleted or modified until the client no longer uses the parser

    91         * to access the content.

    92         *

    93         * This call discards any previous parsing result.

    94         *

    95         * @param[in] aBuffer The buffer containing the landmark content.

    96         */

    97         virtual void SetInputBuffer( const TDesC8& aBuffer ) = 0;

    98 

    99         /**

   100         * Opens the file with the landmark content to be parsed.

   101         *

   102         * The file is opened in read-only sharing mode which means the file

   103         * cannot be deleted or modified until the file is released. The file is

   104         * released either by deleting the parser object or if

   105         * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL

   106         * is called for some new landmark content data.

   107         *

   108         * This call discards any previous parsing result.

   109         *

   110         * @param[in] aFile The file containing the landmark content.

   111         */

   112         virtual void SetInputFileL( const TDesC& aFile ) = 0;

   113 

   114         /**

   115         * Sets a handle to the file which should be parsed.

   116         *

   117         * The file needs to be open until the client no longer uses the parser

   118         * to access the content.

   119         *

   120         * This call discards any previous parsing result.

   121         *

   122         * @param[in] aFileHandle The handle to the file which should be parsed.

   123         *

   124         * @leave  KErrAccessDenied  aFileHandle is opened in read-write mode, When KMZ file is getting parsed.

   125         */

   126         virtual void SetInputFileHandleL( RFile&  aFileHandle ) = 0;

   127 

   128         /**

   129         * Parse landmark content.

   130         *

   131         * @pre Input buffer or file or file handle has been specified. 

   132         *

   133         * The landmark content to be parsed is specified in

   134         * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL.

   135         *

   136         * Any previously parsed data is discarded.

   137         *

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

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

   140         * the progress of the operation.

   141         *

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

   143         *

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

   145         * is complete, it will not be possible to retrieve any parsed data.

   146         *

   147         * If the content is in unrecognized format, or if the content is

   148         * invalid, the returned operation will fail with error code

   149         * @p KErrPosLmUnknownFormat.

   150         *

   151         * If another content source is set by @ref SetInputBuffer,

   152         * @ref SetInputFileL or @ref SetInputFileHandleL, then this method

   153         * needs to be called again to get a new operation object. If the

   154         * previous operation object is still executed, it will panic with error

   155         * code @p EPosLmProtocolBreak.

   156         *

   157         * The client can specify that the parser should build an index while

   158         * parsing. Building an index uses more memory but it allows unlimited

   159         * direct access to all parsed data. If the parser does not support

   160         * indexing, this call will fail with error code @p KErrNotSupported.

   161         *

   162         * @param[in] aBuildIndex Specifies if the parser should build an index.

   163         * @return A handle to the operation.

   164         *

   165         * @leave KErrNotSupported aBuildIndex is ETrue, but parser does not

   166         *   support indexing.

   167         *

   168         * @panic "Landmarks Client"-EPosLmProtocolBreak Input buffer or file 

   169         *   or file handle not yet specified. 

   170         */

   171         virtual CPosLmOperation* ParseContentL( TBool  aBuildIndex = EFalse ) = 0;

   172 

   173         /**

   174         * Retrieve the total number of parsed landmarks.

   175         *

   176         * This function can also be called while @ref ParseContentL is

   177         * incrementally executed.

   178         *

   179         * @return The total number of parsed landmarks.

   180         */

   181         virtual TUint32 NumOfParsedLandmarks() const = 0;

   182 

   183         /**

   184         * Retrieve the first landmark collection data identifier.

   185         *

   186         * Landmark collection data is generic information about the landmark

   187         * collection.

   188         *

   189         * To retrieve the next collection data, call @ref NextCollectionDataId.

   190         * To retrieve the content of the collection data, call

   191         * @ref CollectionData.

   192         *

   193         * @return The first landmark collection data ID or @p EPosLmCollDataNone

   194         *   if there is no landmark collection data detected.

   195         */

   196         virtual TPosLmCollectionDataId FirstCollectionDataId() const = 0;

   197 

   198         /**

   199         * Retrieve the next landmark collection data identifier.

   200         *

   201         * Landmark collection data is generic information about the landmark

   202         * collection.

   203         *

   204         * To retrieve the first collection data, call

   205         * @ref FirstCollectionDataId. To retrieve the content of the collection

   206         * data, call @ref CollectionData.

   207         *

   208         * @param[in] aCollectionData Previous landmark collection data ID.

   209         * @return The next landmark collection data ID or @p EPosLmCollDataNone

   210         *   if there is no more landmark collection data detected.

   211         */

   212         virtual TPosLmCollectionDataId NextCollectionDataId(

   213             TPosLmCollectionDataId aCollectionData

   214         ) const = 0;

   215 

   216         /**

   217         * Retrieve a specific collection data.

   218         *

   219         * If the requested collection data is not found, this function will

   220         * return an empty descriptor.

   221         *

   222         * The returned descriptor pointer can be used as long as the parser

   223         * object exists and is not reset by calling @ref SetInputBuffer,

   224         * @ref SetInputFileL or @ref SetInputFileHandleL.

   225         *

   226         * @param[in] aDataId The collection data to retrieve.

   227         * @return The requested collection data.

   228         */

   229         virtual TPtrC CollectionData( TPosLmCollectionDataId aDataId ) const = 0;

   230 

   231         /**

   232         * Retrieve a parsed landmark.

   233         *

   234         * The client can supply an index of the landmark to retrieve. Index

   235         * must be a positive number and less than the number of parsed

   236         * landmarks, otherwise this function will panic with error code

   237         * @p EPosInvalidIndex. If no index has been built, this function

   238         * will leave with error code @p KErrNotFound. A landmark index is 

   239         * built by supplying a parameter in @ref ParseContentL.

   240         *

   241         * If @a aLandmarkIndex parameter is omitted, or

   242         * @p KPosLastParsedLandmark is supplied, then this function will

   243         * retrieve the last parsed landmark. This does not require that an

   244         * index has been built. Each @ref CPosLmOperation::NextStep call

   245         * will parse a new landmark.

   246         *

   247         * The client may retrieve the categories of the landmark by

   248         * calling @ref LandmarkCategoryLC and supplying the category ID

   249         * which can be obtained from the landmark object.

   250         *

   251         * @p Note that even if the returned landmark object is modified, the

   252         * changes will not be included when importing using

   253         * @ref CPosLandmarkDatabase::ImportLandmarksL.

   254         *

   255         * The client takes ownership of the returned landmark object.

   256         *

   257         * @param aLandmarkIndex The index of the landmark to retrieve.

   258         * @return The requested landmark.

   259         *

   260         * @leave KErrNotFound No index has been built and given index value 

   261         *   is not equal to @p KPosLastParsedLandmark.

   262         *

   263         * @panic "Landmarks Client"-EPosInvalidIndex When landmark index is used 

   264         *   and given index value is negative and 

   265         *   not equal to @p KPosLastParsedLandmark or greater or equal to 

   266         *   the number of parsed landmarks. 

   267         */

   268         virtual CPosLandmark* LandmarkLC(

   269             TUint  aLandmarkIndex = KPosLastParsedLandmark

   270         ) const = 0;

   271 

   272         /**

   273         * Retrieve a landmark category found in a parsed landmark.

   274         *

   275         * A landmark may include the IDs of some landmark categories. These

   276         * categories are retrieved by calling this function.

   277         *

   278         * @p Note that a category ID in this case is not the ID of a category

   279         * stored in a database, but the category ID specified in

   280         * the parsed landmark.

   281         *

   282         * @p Note that even if the returned category object is modified, the

   283         * changes will not be included when importing using

   284         * @ref CPosLandmarkDatabase::ImportLandmarksL.

   285         *

   286         * The client takes ownership of the returned category object.

   287         *

   288         * @param aCategoryId The ID of the landmark category.

   289         * @return The requested landmark category.

   290         * @leave KErrNotFound Passed category ID is not part of the parsed

   291         *   landmark content.

   292         */

   293         virtual CPosLandmarkCategory* LandmarkCategoryLC(

   294             TPosLmItemId aCategoryId

   295         ) const = 0;

   296 

   297     protected:

   298 

   299         // C++ constructor.

   300         IMPORT_C CPosLandmarkParser();

   301 

   302     private:

   303 

   304         // Prohibit copy constructor

   305         CPosLandmarkParser( const CPosLandmarkParser& );

   306         // Prohibit assigment operator

   307         CPosLandmarkParser& operator= ( const CPosLandmarkParser& );

   308 

   309     private:

   310 

   311         CPosLandmarkParserExtension* iExtension;

   312 

   313         // Implementation Uid

   314         TUid iDtorIdKey;

   315 

   316     };

   317 

   318 #endif      // CPOSLANDMARKPARSER_H

   319 

   320