diff -r 000000000000 -r 667063e416a2 locsrv_pub/landmarks_api/inc/EPos_CPosLandmarkParser.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/locsrv_pub/landmarks_api/inc/EPos_CPosLandmarkParser.h Tue Feb 02 01:06:48 2010 +0200 @@ -0,0 +1,320 @@ +/* +* 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 +#include +#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 + +