1.1 --- a/epoc32/include/mw/epos_cposlandmarkparser.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/epos_cposlandmarkparser.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,320 @@
1.4 -epos_cposlandmarkparser.h
1.5 +/*
1.6 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: CPosLandmarkParser class
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef CPOSLANDMARKPARSER_H
1.24 +#define CPOSLANDMARKPARSER_H
1.25 +
1.26 +#include <e32base.h>
1.27 +#include <f32file.h>
1.28 +#include "EPos_Landmarks.h"
1.29 +#include "EPos_CPosLandmark.h"
1.30 +#include "EPos_CPosLandmarkCategory.h"
1.31 +#include "EPos_CPosLmOperation.h"
1.32 +
1.33 +class CPosLandmarkParserExtension;
1.34 +
1.35 +/**
1.36 +* Class used for parsing landmark content.
1.37 +*
1.38 +* When creating an instance of this class, the type (e.g. the mime type) of
1.39 +* the landmark content must be specified. The client will then receive a
1.40 +* parser implementation which understands the requested landmark content.
1.41 +*
1.42 +* The client specifies landmark content either in a buffer or in a file. The
1.43 +* buffer/file is needed until the client no longer uses the parser object for
1.44 +* accessing the parsed data. If the buffer/file is deleted or modified, it
1.45 +* may not be possible to access the parsed landmark data.
1.46 +*
1.47 +* @ref ParseContentL returns a @ref CPosLmOperation which means parsing can
1.48 +* be run incrementally. Each call to @ref CPosLmOperation::NextStep parses
1.49 +* one landmark. The landmark can be retrieved by calling @ref LandmarkLC.
1.50 +*
1.51 +* Optionally, the client can specify that the parser should build an index.
1.52 +* An index enables direct access to all landmarks when the content has been
1.53 +* fully parsed. The content is fully parsed when CPosLmOperation::NextStep
1.54 +* or CPosLmOperation::ExecuteL complete with KErrNone. The @ref LandmarkLC method
1.55 +* then can be called with landmark index to directly access any of parsed
1.56 +* landmarks.
1.57 +*
1.58 +* If @ref CPosLandmarkParser is used, the client must call the global
1.59 +* function @ref ReleaseLandmarkResources before terminating, in order to
1.60 +* release all used landmark resources, otherwise the client may receive
1.61 +* an ALLOC panic.
1.62 +*
1.63 +* @lib eposlandmarks.lib
1.64 +* @since S60 3.0
1.65 +*/
1.66 +class CPosLandmarkParser : public CBase
1.67 + {
1.68 + public:
1.69 +
1.70 + /**
1.71 + * Two-phased constructor.
1.72 + *
1.73 + * The client must specify the type (e.g. the mime type) of the landmark
1.74 + * content which should be parsed.
1.75 + *
1.76 + * @param[in] The mime-type of the content to parse.
1.77 + * @return A new instance of this class.
1.78 + *
1.79 + * @leave KErrNotSupported Content format is not supported.
1.80 + */
1.81 + IMPORT_C static CPosLandmarkParser* NewL( const TDesC8& aContentMimeType );
1.82 +
1.83 + /**
1.84 + * Destructor.
1.85 + */
1.86 + IMPORT_C virtual ~CPosLandmarkParser();
1.87 +
1.88 + public:
1.89 +
1.90 + /**
1.91 + * Sets the buffer to be parsed.
1.92 + *
1.93 + * The parser does not copy the data which means the buffer must not
1.94 + * be deleted or modified until the client no longer uses the parser
1.95 + * to access the content.
1.96 + *
1.97 + * This call discards any previous parsing result.
1.98 + *
1.99 + * @param[in] aBuffer The buffer containing the landmark content.
1.100 + */
1.101 + virtual void SetInputBuffer( const TDesC8& aBuffer ) = 0;
1.102 +
1.103 + /**
1.104 + * Opens the file with the landmark content to be parsed.
1.105 + *
1.106 + * The file is opened in read-only sharing mode which means the file
1.107 + * cannot be deleted or modified until the file is released. The file is
1.108 + * released either by deleting the parser object or if
1.109 + * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL
1.110 + * is called for some new landmark content data.
1.111 + *
1.112 + * This call discards any previous parsing result.
1.113 + *
1.114 + * @param[in] aFile The file containing the landmark content.
1.115 + */
1.116 + virtual void SetInputFileL( const TDesC& aFile ) = 0;
1.117 +
1.118 + /**
1.119 + * Sets a handle to the file which should be parsed.
1.120 + *
1.121 + * The file needs to be open until the client no longer uses the parser
1.122 + * to access the content.
1.123 + *
1.124 + * This call discards any previous parsing result.
1.125 + *
1.126 + * @param[in] aFileHandle The handle to the file which should be parsed.
1.127 + *
1.128 + * @leave KErrAccessDenied aFileHandle is opened in read-write mode, When KMZ file is getting parsed.
1.129 + */
1.130 + virtual void SetInputFileHandleL( RFile& aFileHandle ) = 0;
1.131 +
1.132 + /**
1.133 + * Parse landmark content.
1.134 + *
1.135 + * @pre Input buffer or file or file handle has been specified.
1.136 + *
1.137 + * The landmark content to be parsed is specified in
1.138 + * @ref SetInputBuffer, @ref SetInputFileL or @ref SetInputFileHandleL.
1.139 + *
1.140 + * Any previously parsed data is discarded.
1.141 + *
1.142 + * The function returns an operation object which can be run in
1.143 + * incremental mode. If it is run incrementally the client can supervise
1.144 + * the progress of the operation.
1.145 + *
1.146 + * The client takes ownership of the returned operation object.
1.147 + *
1.148 + * If the @ref CPosLmOperation object is deleted before the operation
1.149 + * is complete, it will not be possible to retrieve any parsed data.
1.150 + *
1.151 + * If the content is in unrecognized format, or if the content is
1.152 + * invalid, the returned operation will fail with error code
1.153 + * @p KErrPosLmUnknownFormat.
1.154 + *
1.155 + * If another content source is set by @ref SetInputBuffer,
1.156 + * @ref SetInputFileL or @ref SetInputFileHandleL, then this method
1.157 + * needs to be called again to get a new operation object. If the
1.158 + * previous operation object is still executed, it will panic with error
1.159 + * code @p EPosLmProtocolBreak.
1.160 + *
1.161 + * The client can specify that the parser should build an index while
1.162 + * parsing. Building an index uses more memory but it allows unlimited
1.163 + * direct access to all parsed data. If the parser does not support
1.164 + * indexing, this call will fail with error code @p KErrNotSupported.
1.165 + *
1.166 + * @param[in] aBuildIndex Specifies if the parser should build an index.
1.167 + * @return A handle to the operation.
1.168 + *
1.169 + * @leave KErrNotSupported aBuildIndex is ETrue, but parser does not
1.170 + * support indexing.
1.171 + *
1.172 + * @panic "Landmarks Client"-EPosLmProtocolBreak Input buffer or file
1.173 + * or file handle not yet specified.
1.174 + */
1.175 + virtual CPosLmOperation* ParseContentL( TBool aBuildIndex = EFalse ) = 0;
1.176 +
1.177 + /**
1.178 + * Retrieve the total number of parsed landmarks.
1.179 + *
1.180 + * This function can also be called while @ref ParseContentL is
1.181 + * incrementally executed.
1.182 + *
1.183 + * @return The total number of parsed landmarks.
1.184 + */
1.185 + virtual TUint32 NumOfParsedLandmarks() const = 0;
1.186 +
1.187 + /**
1.188 + * Retrieve the first landmark collection data identifier.
1.189 + *
1.190 + * Landmark collection data is generic information about the landmark
1.191 + * collection.
1.192 + *
1.193 + * To retrieve the next collection data, call @ref NextCollectionDataId.
1.194 + * To retrieve the content of the collection data, call
1.195 + * @ref CollectionData.
1.196 + *
1.197 + * @return The first landmark collection data ID or @p EPosLmCollDataNone
1.198 + * if there is no landmark collection data detected.
1.199 + */
1.200 + virtual TPosLmCollectionDataId FirstCollectionDataId() const = 0;
1.201 +
1.202 + /**
1.203 + * Retrieve the next landmark collection data identifier.
1.204 + *
1.205 + * Landmark collection data is generic information about the landmark
1.206 + * collection.
1.207 + *
1.208 + * To retrieve the first collection data, call
1.209 + * @ref FirstCollectionDataId. To retrieve the content of the collection
1.210 + * data, call @ref CollectionData.
1.211 + *
1.212 + * @param[in] aCollectionData Previous landmark collection data ID.
1.213 + * @return The next landmark collection data ID or @p EPosLmCollDataNone
1.214 + * if there is no more landmark collection data detected.
1.215 + */
1.216 + virtual TPosLmCollectionDataId NextCollectionDataId(
1.217 + TPosLmCollectionDataId aCollectionData
1.218 + ) const = 0;
1.219 +
1.220 + /**
1.221 + * Retrieve a specific collection data.
1.222 + *
1.223 + * If the requested collection data is not found, this function will
1.224 + * return an empty descriptor.
1.225 + *
1.226 + * The returned descriptor pointer can be used as long as the parser
1.227 + * object exists and is not reset by calling @ref SetInputBuffer,
1.228 + * @ref SetInputFileL or @ref SetInputFileHandleL.
1.229 + *
1.230 + * @param[in] aDataId The collection data to retrieve.
1.231 + * @return The requested collection data.
1.232 + */
1.233 + virtual TPtrC CollectionData( TPosLmCollectionDataId aDataId ) const = 0;
1.234 +
1.235 + /**
1.236 + * Retrieve a parsed landmark.
1.237 + *
1.238 + * The client can supply an index of the landmark to retrieve. Index
1.239 + * must be a positive number and less than the number of parsed
1.240 + * landmarks, otherwise this function will panic with error code
1.241 + * @p EPosInvalidIndex. If no index has been built, this function
1.242 + * will leave with error code @p KErrNotFound. A landmark index is
1.243 + * built by supplying a parameter in @ref ParseContentL.
1.244 + *
1.245 + * If @a aLandmarkIndex parameter is omitted, or
1.246 + * @p KPosLastParsedLandmark is supplied, then this function will
1.247 + * retrieve the last parsed landmark. This does not require that an
1.248 + * index has been built. Each @ref CPosLmOperation::NextStep call
1.249 + * will parse a new landmark.
1.250 + *
1.251 + * The client may retrieve the categories of the landmark by
1.252 + * calling @ref LandmarkCategoryLC and supplying the category ID
1.253 + * which can be obtained from the landmark object.
1.254 + *
1.255 + * @p Note that even if the returned landmark object is modified, the
1.256 + * changes will not be included when importing using
1.257 + * @ref CPosLandmarkDatabase::ImportLandmarksL.
1.258 + *
1.259 + * The client takes ownership of the returned landmark object.
1.260 + *
1.261 + * @param aLandmarkIndex The index of the landmark to retrieve.
1.262 + * @return The requested landmark.
1.263 + *
1.264 + * @leave KErrNotFound No index has been built and given index value
1.265 + * is not equal to @p KPosLastParsedLandmark.
1.266 + *
1.267 + * @panic "Landmarks Client"-EPosInvalidIndex When landmark index is used
1.268 + * and given index value is negative and
1.269 + * not equal to @p KPosLastParsedLandmark or greater or equal to
1.270 + * the number of parsed landmarks.
1.271 + */
1.272 + virtual CPosLandmark* LandmarkLC(
1.273 + TUint aLandmarkIndex = KPosLastParsedLandmark
1.274 + ) const = 0;
1.275 +
1.276 + /**
1.277 + * Retrieve a landmark category found in a parsed landmark.
1.278 + *
1.279 + * A landmark may include the IDs of some landmark categories. These
1.280 + * categories are retrieved by calling this function.
1.281 + *
1.282 + * @p Note that a category ID in this case is not the ID of a category
1.283 + * stored in a database, but the category ID specified in
1.284 + * the parsed landmark.
1.285 + *
1.286 + * @p Note that even if the returned category object is modified, the
1.287 + * changes will not be included when importing using
1.288 + * @ref CPosLandmarkDatabase::ImportLandmarksL.
1.289 + *
1.290 + * The client takes ownership of the returned category object.
1.291 + *
1.292 + * @param aCategoryId The ID of the landmark category.
1.293 + * @return The requested landmark category.
1.294 + * @leave KErrNotFound Passed category ID is not part of the parsed
1.295 + * landmark content.
1.296 + */
1.297 + virtual CPosLandmarkCategory* LandmarkCategoryLC(
1.298 + TPosLmItemId aCategoryId
1.299 + ) const = 0;
1.300 +
1.301 + protected:
1.302 +
1.303 + // C++ constructor.
1.304 + IMPORT_C CPosLandmarkParser();
1.305 +
1.306 + private:
1.307 +
1.308 + // Prohibit copy constructor
1.309 + CPosLandmarkParser( const CPosLandmarkParser& );
1.310 + // Prohibit assigment operator
1.311 + CPosLandmarkParser& operator= ( const CPosLandmarkParser& );
1.312 +
1.313 + private:
1.314 +
1.315 + CPosLandmarkParserExtension* iExtension;
1.316 +
1.317 + // Implementation Uid
1.318 + TUid iDtorIdKey;
1.319 +
1.320 + };
1.321 +
1.322 +#endif // CPOSLANDMARKPARSER_H
1.323 +
1.324 +