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