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@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  CPosLandmarkParser class
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef CPOSLANDMARKPARSER_H
williamr@2: #define CPOSLANDMARKPARSER_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <f32file.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 CPosLandmarkParserExtension;
williamr@2: 
williamr@2: /**
williamr@2: *  Class used for parsing 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 a
williamr@2: *  parser implementation which understands the requested landmark content.
williamr@2: *
williamr@2: *  The client specifies landmark content either in a buffer or in a file. The
williamr@2: *  buffer/file is needed until the client no longer uses the parser object for
williamr@2: *  accessing the parsed data. If the buffer/file is deleted or modified, it
williamr@2: *  may not be possible to access the parsed landmark data.
williamr@2: *
williamr@2: *  @ref ParseContentL returns a @ref CPosLmOperation which means parsing can
williamr@2: *  be run incrementally. Each call to @ref CPosLmOperation::NextStep parses
williamr@2: *  one landmark. The landmark can be retrieved by calling @ref LandmarkLC.
williamr@2: *
williamr@2: *  Optionally, the client can specify that the parser should build an index.
williamr@2: *  An index enables direct access to all landmarks when the content has been
williamr@2: *  fully parsed. The content is fully parsed when CPosLmOperation::NextStep
williamr@2: *  or CPosLmOperation::ExecuteL complete with KErrNone. The @ref LandmarkLC method
williamr@2: *  then can be called with landmark index to directly access any of parsed
williamr@2: *  landmarks.
williamr@2: *
williamr@2: *  If @ref CPosLandmarkParser 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 CPosLandmarkParser : 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 landmark
williamr@2:         * content which should be parsed. 
williamr@2:         *
williamr@2:         * @param[in] The mime-type of the content to parse.
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 CPosLandmarkParser* NewL( const TDesC8& aContentMimeType );
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CPosLandmarkParser();
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Sets the buffer to be parsed.
williamr@2:         *
williamr@2:         * The parser does not copy the data which means the buffer must not
williamr@2:         * be deleted or modified until the client no longer uses the parser
williamr@2:         * to access the content.
williamr@2:         *
williamr@2:         * This call discards any previous parsing result.
williamr@2:         *
williamr@2:         * @param[in] aBuffer The buffer containing the landmark content.
williamr@2:         */
williamr@2:         virtual void SetInputBuffer( const TDesC8& aBuffer ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Opens the file with the landmark content to be parsed.
williamr@2:         *
williamr@2:         * The file is opened in read-only sharing mode which means the file
williamr@2:         * cannot be deleted or modified until the file is released. The file is
williamr@2:         * released either by deleting the parser object or if
williamr@2:         * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL
williamr@2:         * is called for some new landmark content data.
williamr@2:         *
williamr@2:         * This call discards any previous parsing result.
williamr@2:         *
williamr@2:         * @param[in] aFile The file containing the landmark content.
williamr@2:         */
williamr@2:         virtual void SetInputFileL( const TDesC& aFile ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Sets a handle to the file which should be parsed.
williamr@2:         *
williamr@2:         * The file needs to be open until the client no longer uses the parser
williamr@2:         * to access the content.
williamr@2:         *
williamr@2:         * This call discards any previous parsing result.
williamr@2:         *
williamr@2:         * @param[in] aFileHandle The handle to the file which should be parsed.
williamr@2:         *
williamr@2:         * @leave  KErrAccessDenied  aFileHandle is opened in read-write mode, When KMZ file is getting parsed.
williamr@2:         */
williamr@2:         virtual void SetInputFileHandleL( RFile&  aFileHandle ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Parse landmark content.
williamr@2:         *
williamr@2:         * @pre Input buffer or file or file handle has been specified. 
williamr@2:         *
williamr@2:         * The landmark content to be parsed is specified in
williamr@2:         * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL.
williamr@2:         *
williamr@2:         * Any previously parsed data is discarded.
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, it will not be possible to retrieve any parsed data.
williamr@2:         *
williamr@2:         * If the content is in unrecognized format, or if the content is
williamr@2:         * invalid, the returned operation will fail with error code
williamr@2:         * @p KErrPosLmUnknownFormat.
williamr@2:         *
williamr@2:         * If another content source is set by @ref SetInputBuffer,
williamr@2:         * @ref SetInputFileL or @ref SetInputFileHandleL, then this method
williamr@2:         * needs to be called again to get a new operation object. If the
williamr@2:         * previous operation object is still executed, it will panic with error
williamr@2:         * code @p EPosLmProtocolBreak.
williamr@2:         *
williamr@2:         * The client can specify that the parser should build an index while
williamr@2:         * parsing. Building an index uses more memory but it allows unlimited
williamr@2:         * direct access to all parsed data. If the parser does not support
williamr@2:         * indexing, this call will fail with error code @p KErrNotSupported.
williamr@2:         *
williamr@2:         * @param[in] aBuildIndex Specifies if the parser should build an index.
williamr@2:         * @return A handle to the operation.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported aBuildIndex is ETrue, but parser does not
williamr@2:         *   support indexing.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosLmProtocolBreak Input buffer or file 
williamr@2:         *   or file handle not yet specified. 
williamr@2:         */
williamr@2:         virtual CPosLmOperation* ParseContentL( TBool  aBuildIndex = EFalse ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve the total number of parsed landmarks.
williamr@2:         *
williamr@2:         * This function can also be called while @ref ParseContentL is
williamr@2:         * incrementally executed.
williamr@2:         *
williamr@2:         * @return The total number of parsed landmarks.
williamr@2:         */
williamr@2:         virtual TUint32 NumOfParsedLandmarks() const = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve the first landmark collection data identifier.
williamr@2:         *
williamr@2:         * Landmark collection data is generic information about the landmark
williamr@2:         * collection.
williamr@2:         *
williamr@2:         * To retrieve the next collection data, call @ref NextCollectionDataId.
williamr@2:         * To retrieve the content of the collection data, call
williamr@2:         * @ref CollectionData.
williamr@2:         *
williamr@2:         * @return The first landmark collection data ID or @p EPosLmCollDataNone
williamr@2:         *   if there is no landmark collection data detected.
williamr@2:         */
williamr@2:         virtual TPosLmCollectionDataId FirstCollectionDataId() const = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve the next landmark collection data identifier.
williamr@2:         *
williamr@2:         * Landmark collection data is generic information about the landmark
williamr@2:         * collection.
williamr@2:         *
williamr@2:         * To retrieve the first collection data, call
williamr@2:         * @ref FirstCollectionDataId. To retrieve the content of the collection
williamr@2:         * data, call @ref CollectionData.
williamr@2:         *
williamr@2:         * @param[in] aCollectionData Previous landmark collection data ID.
williamr@2:         * @return The next landmark collection data ID or @p EPosLmCollDataNone
williamr@2:         *   if there is no more landmark collection data detected.
williamr@2:         */
williamr@2:         virtual TPosLmCollectionDataId NextCollectionDataId(
williamr@2:             TPosLmCollectionDataId aCollectionData
williamr@2:         ) const = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve a specific collection data.
williamr@2:         *
williamr@2:         * If the requested collection data is not found, this function will
williamr@2:         * return an empty descriptor.
williamr@2:         *
williamr@2:         * The returned descriptor pointer can be used as long as the parser
williamr@2:         * object exists and is not reset by calling @ref SetInputBuffer,
williamr@2:         * @ref SetInputFileL or @ref SetInputFileHandleL.
williamr@2:         *
williamr@2:         * @param[in] aDataId The collection data to retrieve.
williamr@2:         * @return The requested collection data.
williamr@2:         */
williamr@2:         virtual TPtrC CollectionData( TPosLmCollectionDataId aDataId ) const = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve a parsed landmark.
williamr@2:         *
williamr@2:         * The client can supply an index of the landmark to retrieve. Index
williamr@2:         * must be a positive number and less than the number of parsed
williamr@2:         * landmarks, otherwise this function will panic with error code
williamr@2:         * @p EPosInvalidIndex. If no index has been built, this function
williamr@2:         * will leave with error code @p KErrNotFound. A landmark index is 
williamr@2:         * built by supplying a parameter in @ref ParseContentL.
williamr@2:         *
williamr@2:         * If @a aLandmarkIndex parameter is omitted, or
williamr@2:         * @p KPosLastParsedLandmark is supplied, then this function will
williamr@2:         * retrieve the last parsed landmark. This does not require that an
williamr@2:         * index has been built. Each @ref CPosLmOperation::NextStep call
williamr@2:         * will parse a new landmark.
williamr@2:         *
williamr@2:         * The client may retrieve the categories of the landmark by
williamr@2:         * calling @ref LandmarkCategoryLC and supplying the category ID
williamr@2:         * which can be obtained from the landmark object.
williamr@2:         *
williamr@2:         * @p Note that even if the returned landmark object is modified, the
williamr@2:         * changes will not be included when importing using
williamr@2:         * @ref CPosLandmarkDatabase::ImportLandmarksL.
williamr@2:         *
williamr@2:         * The client takes ownership of the returned landmark object.
williamr@2:         *
williamr@2:         * @param aLandmarkIndex The index of the landmark to retrieve.
williamr@2:         * @return The requested landmark.
williamr@2:         *
williamr@2:         * @leave KErrNotFound No index has been built and given index value 
williamr@2:         *   is not equal to @p KPosLastParsedLandmark.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosInvalidIndex When landmark index is used 
williamr@2:         *   and given index value is negative and 
williamr@2:         *   not equal to @p KPosLastParsedLandmark or greater or equal to 
williamr@2:         *   the number of parsed landmarks. 
williamr@2:         */
williamr@2:         virtual CPosLandmark* LandmarkLC(
williamr@2:             TUint  aLandmarkIndex = KPosLastParsedLandmark
williamr@2:         ) const = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve a landmark category found in a parsed landmark.
williamr@2:         *
williamr@2:         * A landmark may include the IDs of some landmark categories. These
williamr@2:         * categories are retrieved by calling this function.
williamr@2:         *
williamr@2:         * @p Note that a category ID in this case is not the ID of a category
williamr@2:         * stored in a database, but the category ID specified in
williamr@2:         * the parsed landmark.
williamr@2:         *
williamr@2:         * @p Note that even if the returned category object is modified, the
williamr@2:         * changes will not be included when importing using
williamr@2:         * @ref CPosLandmarkDatabase::ImportLandmarksL.
williamr@2:         *
williamr@2:         * The client takes ownership of the returned category object.
williamr@2:         *
williamr@2:         * @param aCategoryId The ID of the landmark category.
williamr@2:         * @return The requested landmark category.
williamr@2:         * @leave KErrNotFound Passed category ID is not part of the parsed
williamr@2:         *   landmark content.
williamr@2:         */
williamr@2:         virtual CPosLandmarkCategory* LandmarkCategoryLC(
williamr@2:             TPosLmItemId aCategoryId
williamr@2:         ) const = 0;
williamr@2: 
williamr@2:     protected:
williamr@2: 
williamr@2:         // C++ constructor.
williamr@2:         IMPORT_C CPosLandmarkParser();
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // Prohibit copy constructor
williamr@2:         CPosLandmarkParser( const CPosLandmarkParser& );
williamr@2:         // Prohibit assigment operator
williamr@2:         CPosLandmarkParser& operator= ( const CPosLandmarkParser& );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         CPosLandmarkParserExtension* iExtension;
williamr@2: 
williamr@2:         // Implementation Uid
williamr@2:         TUid iDtorIdKey;
williamr@2: 
williamr@2:     };
williamr@2: 
williamr@2: #endif      // CPOSLANDMARKPARSER_H
williamr@2: 
williamr@2: