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