/*

 * 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  CPosLandmarkParser class

 *

 */

 #ifndef CPOSLANDMARKPARSER_H

 #define CPOSLANDMARKPARSER_H

 #include <e32base.h>

 #include <f32file.h>

 #include "EPos_Landmarks.h"

 #include "EPos_CPosLandmark.h"

 #include "EPos_CPosLandmarkCategory.h"

 #include "EPos_CPosLmOperation.h"

 class CPosLandmarkParserExtension;

 /**

 *  Class used for parsing 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 a

 *  parser implementation which understands the requested landmark content.

 *

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

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

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

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

 *

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

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

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

 *

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

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

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

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

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

 *  landmarks.

 *

 *  If @ref CPosLandmarkParser 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 CPosLandmarkParser : public CBase

     {

     public:

         /**

         * Two-phased constructor.

         *

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

         * content which should be parsed. 

         *

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

         * @return A new instance of this class.

         *

         * @leave KErrNotSupported Content format is not supported.

         */

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

         /**

         * Destructor.

         */

         IMPORT_C virtual ~CPosLandmarkParser();

     public:

         /**

         * Sets the buffer to be parsed.

         *

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

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

         * to access the content.

         *

         * This call discards any previous parsing result.

         *

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

         */

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

         /**

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

         *

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

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

         * released either by deleting the parser object or if

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

         * is called for some new landmark content data.

         *

         * This call discards any previous parsing result.

         *

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

         */

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

         /**

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

         *

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

         * to access the content.

         *

         * This call discards any previous parsing result.

         *

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

         *

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

         */

         virtual void SetInputFileHandleL( RFile&  aFileHandle ) = 0;

         /**

         * Parse landmark content.

         *

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

         *

         * The landmark content to be parsed is specified in

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

         *

         * Any previously parsed data is discarded.

         *

         * 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, it will not be possible to retrieve any parsed data.

         *

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

         * invalid, the returned operation will fail with error code

         * @p KErrPosLmUnknownFormat.

         *

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

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

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

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

         * code @p EPosLmProtocolBreak.

         *

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

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

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

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

         *

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

         * @return A handle to the operation.

         *

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

         *   support indexing.

         *

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

         *   or file handle not yet specified. 

         */

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

         /**

         * Retrieve the total number of parsed landmarks.

         *

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

         * incrementally executed.

         *

         * @return The total number of parsed landmarks.

         */

         virtual TUint32 NumOfParsedLandmarks() const = 0;

         /**

         * Retrieve the first landmark collection data identifier.

         *

         * Landmark collection data is generic information about the landmark

         * collection.

         *

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

         * To retrieve the content of the collection data, call

         * @ref CollectionData.

         *

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

         *   if there is no landmark collection data detected.

         */

         virtual TPosLmCollectionDataId FirstCollectionDataId() const = 0;

         /**

         * Retrieve the next landmark collection data identifier.

         *

         * Landmark collection data is generic information about the landmark

         * collection.

         *

         * To retrieve the first collection data, call

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

         * data, call @ref CollectionData.

         *

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

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

         *   if there is no more landmark collection data detected.

         */

         virtual TPosLmCollectionDataId NextCollectionDataId(

             TPosLmCollectionDataId aCollectionData

         ) const = 0;

         /**

         * Retrieve a specific collection data.

         *

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

         * return an empty descriptor.

         *

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

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

         * @ref SetInputFileL or @ref SetInputFileHandleL.

         *

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

         * @return The requested collection data.

         */

         virtual TPtrC CollectionData( TPosLmCollectionDataId aDataId ) const = 0;

         /**

         * Retrieve a parsed landmark.

         *

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

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

         * landmarks, otherwise this function will panic with error code

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

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

         * built by supplying a parameter in @ref ParseContentL.

         *

         * If @a aLandmarkIndex parameter is omitted, or

         * @p KPosLastParsedLandmark is supplied, then this function will

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

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

         * will parse a new landmark.

         *

         * The client may retrieve the categories of the landmark by

         * calling @ref LandmarkCategoryLC and supplying the category ID

         * which can be obtained from the landmark object.

         *

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

         * changes will not be included when importing using

         * @ref CPosLandmarkDatabase::ImportLandmarksL.

         *

         * The client takes ownership of the returned landmark object.

         *

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

         * @return The requested landmark.

         *

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

         *   is not equal to @p KPosLastParsedLandmark.

         *

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

         *   and given index value is negative and 

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

         *   the number of parsed landmarks. 

         */

         virtual CPosLandmark* LandmarkLC(

             TUint  aLandmarkIndex = KPosLastParsedLandmark

         ) const = 0;

         /**

         * Retrieve a landmark category found in a parsed landmark.

         *

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

         * categories are retrieved by calling this function.

         *

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

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

         * the parsed landmark.

         *

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

         * changes will not be included when importing using

         * @ref CPosLandmarkDatabase::ImportLandmarksL.

         *

         * The client takes ownership of the returned category object.

         *

         * @param aCategoryId The ID of the landmark category.

         * @return The requested landmark category.

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

         *   landmark content.

         */

         virtual CPosLandmarkCategory* LandmarkCategoryLC(

             TPosLmItemId aCategoryId

         ) const = 0;

     protected:

         // C++ constructor.

         IMPORT_C CPosLandmarkParser();

     private:

         // Prohibit copy constructor

         CPosLandmarkParser( const CPosLandmarkParser& );

         // Prohibit assigment operator

         CPosLandmarkParser& operator= ( const CPosLandmarkParser& );

     private:

         CPosLandmarkParserExtension* iExtension;

         // Implementation Uid

         TUid iDtorIdKey;

     };

 #endif      // CPOSLANDMARKPARSER_H