/*

* 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 "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.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