1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/EPos_CPosLandmarkDatabase.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,825 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: CPosLandmarkDatabase class
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CPOSLANDMARKDATABASE_H
1.23 +#define CPOSLANDMARKDATABASE_H
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <s32strm.h>
1.27 +#include "EPos_Landmarks.h"
1.28 +#include "EPos_CPosLandmark.h"
1.29 +#include "EPos_CPosLmPartialReadParameters.h"
1.30 +#include "EPos_CPosLmItemIterator.h"
1.31 +#include "EPos_TPosLmSortPref.h"
1.32 +#include "EPos_CPosLmOperation.h"
1.33 +
1.34 +class CPosLandmarkParser;
1.35 +class CPosLandmarkEncoder;
1.36 +
1.37 +
1.38 +/**
1.39 +* Handle to a landmark database.
1.40 +*
1.41 +* This class contains functions for creating, iterating, reading, modifying
1.42 +* and deleting landmarks.
1.43 +*
1.44 +* Operations on the database may fail with error code @p KErrCorrupt if the
1.45 +* database is damaged. The client can try to recover the database by calling
1.46 +* @ref CPosLandmarkDatabase::InitializeL().
1.47 +*
1.48 +* Operations on the database may fail with error code @p KErrLocked if another
1.49 +* client is writing to the database. Write operations can also fail with this
1.50 +* error code if another client is currently reading from the database.
1.51 +*
1.52 +* If @ref CPosLandmarkDatabase is used, the client must call the global
1.53 +* function @ref ReleaseLandmarkResources() before terminating in order to
1.54 +* release all used landmark resources, otherwise the client may receive
1.55 +* an ALLOC panic.
1.56 +*
1.57 +* @p NetworkServices capability is required for remote databases.
1.58 +*
1.59 +* @since S60 3.0
1.60 +* @lib eposlandmarks.lib.
1.61 +*/
1.62 +class CPosLandmarkDatabase : public CBase
1.63 + {
1.64 + public:
1.65 +
1.66 + /**
1.67 + * Bitmap for specifying a group of transfer options
1.68 + * defined by @ref _TAttributes.
1.69 + */
1.70 + typedef TUint TTransferOptions;
1.71 +
1.72 + /**
1.73 + * Specifies options for importing and exporting landmarks.
1.74 + */
1.75 + enum _TTransferOptions
1.76 + {
1.77 + EDefaultOptions = 0 /**<
1.78 + None of the transfer option flags are set. */,
1.79 + EIncludeCategories = 0x01 /**<
1.80 + Export/Import the categories of the landmarks. */,
1.81 + EIncludeGlobalCategoryNames = 0x02 /**<
1.82 + Only useful in combination with EIncludeCategories.
1.83 + If set, global category names will be used in export/import
1.84 + even if user has renamed them. For import it means that the
1.85 + names of the global categories in the database are overwritten
1.86 + by the imported names. For export it means that predefined
1.87 + names of global categories in the current language will be
1.88 + exported instead of user-defined names. */,
1.89 + ESupressCategoryCreation = 0x04 /**<
1.90 + Only useful in combination with EIncludeCategories.
1.91 + If set, no new categories are created in the database when
1.92 + importing landmarks. This means that connections from
1.93 + imported landmarks will be established only to already
1.94 + existing categories, according to the import information. */
1.95 + };
1.96 +
1.97 + /**
1.98 + * Encapsulates size information for a landmark database.
1.99 + */
1.100 + struct TSize
1.101 + {
1.102 + TInt iFileSize; /**<
1.103 + The size of the database in bytes. */
1.104 + TReal32 iUsage; /**<
1.105 + How many percent of the database which is currently in use.
1.106 + This value lies in the interval [0.0, 1.0]. */
1.107 + };
1.108 +
1.109 + public:
1.110 +
1.111 + /**
1.112 + * Opens the default landmark database.
1.113 + *
1.114 + * The client takes ownership of the returned database handle.
1.115 + *
1.116 + * The database may have to be initialized before it can be used, see
1.117 + * @ref IsInitializingNeeded and @ref InitializeL.
1.118 + *
1.119 + * This function requires @p ReadUserData capability.
1.120 + *
1.121 + * @returns A handle to the open database.
1.122 + */
1.123 + IMPORT_C static CPosLandmarkDatabase* OpenL();
1.124 +
1.125 + /**
1.126 + * Opens a specific landmark database.
1.127 + *
1.128 + * The client refers to a database by URI. The URI consists of a
1.129 + * protocol specifier and the database location: "protocol://location".
1.130 + * If the client does not specify a protocol, "file://" will be assumed.
1.131 + *
1.132 + * For local landmark databases, the URI consists of the drive and the
1.133 + * database file name, e.g. "c:landmarks.ldb". The path cannot be
1.134 + * specified by the client. The extension of the database file name must
1.135 + * be "ldb" otherwise the client will get the error @p KErrArgument.
1.136 + *
1.137 + * If the client specifies a local database and does not specify the
1.138 + * drive letter, e.g. "landmarks.ldb", default database drive will be assumed.
1.139 + *
1.140 + * The client takes ownership of the returned database handle.
1.141 + *
1.142 + * The database may have to be initialized before it can be used, see
1.143 + * @ref IsInitializingNeeded and @ref InitializeL.
1.144 + *
1.145 + * This function requires @p ReadUserData capability.
1.146 + *
1.147 + * @param[in] aDatabaseUri The URI of the database to open.
1.148 + * @returns A handle to the open database.
1.149 + *
1.150 + * @leave KErrArgument Extension of the local database name is not "ldb".
1.151 + * @leave KErrNotSupported The protocol specified in URI is not supported.
1.152 + */
1.153 + IMPORT_C static CPosLandmarkDatabase* OpenL(
1.154 + const TDesC& aDatabaseUri
1.155 + );
1.156 +
1.157 + /**
1.158 + * Destructor.
1.159 + */
1.160 + IMPORT_C virtual ~CPosLandmarkDatabase();
1.161 +
1.162 + public:
1.163 +
1.164 + /**
1.165 + * Checks if the database is in need of initialization.
1.166 + *
1.167 + * If the database needs to be initialized, the client must call
1.168 + * @ref InitializeL, otherwise the database may not be possible to
1.169 + * access. Access functions may leave with @p KErrPosLmNotInitialized.
1.170 + *
1.171 + * Initialization may be needed also if the database becomes damaged.
1.172 + * The client can then try to call @ref InitializeL to try to recover
1.173 + * the database.
1.174 + *
1.175 + * @returns @p ETrue if the database is in need of initialization,
1.176 + * otherwise @p EFalse.
1.177 + */
1.178 + virtual TBool IsInitializingNeeded() const = 0;
1.179 +
1.180 + /**
1.181 + * Initializes the database.
1.182 + *
1.183 + * This function may have to be called right after the database is
1.184 + * opened. @ref IsInitializingNeeded can be called to find out if
1.185 + * initialization is needed.
1.186 + *
1.187 + * If the database becomes damaged, the client can call
1.188 + * @ref InitializeL to try to recover the database.
1.189 + *
1.190 + * It is ok to call @InitializeL even if initialization is not needed.
1.191 + * In this case, the operation will not do anything.
1.192 + *
1.193 + * If the database needs to be initialized, the client must call
1.194 + * @ref InitializeL, otherwise the database may not be possible to
1.195 + * access. Access functions may leave with @p KErrPosLmNotInitialized.
1.196 + *
1.197 + * The function returns an operation object which can be run in
1.198 + * incremental mode. If it is run incrementally the client can supervise
1.199 + * the progress of the operation.
1.200 + *
1.201 + * If the @ref CPosLmOperation object is deleted before the operation
1.202 + * is complete, it is possible that the database is not yet initialized.
1.203 + *
1.204 + * The client takes ownership of the returned operation object.
1.205 + *
1.206 + * This function requires @p ReadUserData capability.
1.207 + *
1.208 + * @returns A handle to the operation.
1.209 + */
1.210 + virtual CPosLmOperation* InitializeL() = 0;
1.211 +
1.212 + /**
1.213 + * Reads a landmark from the database.
1.214 + *
1.215 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.216 + *
1.217 + * The client takes ownership of the returned database landmark object.
1.218 + *
1.219 + * This function requires @p ReadUserData capability.
1.220 + *
1.221 + * @param The ID of the landmark to read.
1.222 + * @returns The requested landmark. The landmark object is put on the
1.223 + * cleanup stack.
1.224 + *
1.225 + * @leave KErrNotFound The requested landmark does not exist in the database.
1.226 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.227 + */
1.228 + virtual CPosLandmark* ReadLandmarkLC(
1.229 + TPosLmItemId aLandmarkId
1.230 + ) = 0;
1.231 +
1.232 + /**
1.233 + * Returns an object for iterating the landmarks in the database.
1.234 + *
1.235 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.236 + *
1.237 + * The iterator object is reset, so that the first
1.238 + * @ref CPosLmItemIterator::NextL call will return the first landmark
1.239 + * ID.
1.240 + *
1.241 + * The client takes ownership of the returned iterator object.
1.242 + *
1.243 + * This function requires @p ReadUserData capability.
1.244 + *
1.245 + * @return The landmark iterator.
1.246 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.247 + */
1.248 + virtual CPosLmItemIterator* LandmarkIteratorL() = 0;
1.249 +
1.250 + /**
1.251 + * Returns an object for iterating the landmarks in the database.
1.252 + *
1.253 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.254 + *
1.255 + * The iterator object is reset, so that the first
1.256 + * @ref CPosLmItemIterator::NextL call will return the first landmark
1.257 + * ID.
1.258 + *
1.259 + * This overload of the iterator function takes a sort preference object
1.260 + * as input. The sort preference object specifies how the landmarks
1.261 + * should be sorted by the iterator. Only sorting by landmark name is supported.
1.262 + *
1.263 + * The client takes ownership of the returned iterator object.
1.264 + *
1.265 + * This function requires @p ReadUserData capability.
1.266 + *
1.267 + * @param[in] aSortPref A sort preference object.
1.268 + * @return The landmark iterator.
1.269 + *
1.270 + * @leave KErrNotSupported Sorting by another attribute than name is
1.271 + * requested.
1.272 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.273 + */
1.274 + virtual CPosLmItemIterator* LandmarkIteratorL(
1.275 + const TPosLmSortPref& aSortPref
1.276 + ) = 0;
1.277 +
1.278 + /**
1.279 + * Adds a new landmark to the database and returns its ID.
1.280 + *
1.281 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.282 + *
1.283 + * A landmark can contain the IDs of the categories it belongs to. If
1.284 + * any of these categories does not exist in the database, the add
1.285 + * operation will still complete successfully but the category which
1.286 + * was not found will be ignored.
1.287 + *
1.288 + * This function requires @p ReadUserData and @p WriteUserData
1.289 + * capabilities.
1.290 + *
1.291 + * @post Landmark is added to the database and landmark object
1.292 + * has database item set (CPosLandmark::LandmarkId()).
1.293 + *
1.294 + * @param[in,out] aLandmark The landmark to add.
1.295 + * @return The ID of the new landmark.
1.296 + *
1.297 + * @leave KErrAccessDenied The database is read-only.
1.298 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.299 + */
1.300 + virtual TPosLmItemId AddLandmarkL(
1.301 + CPosLandmark& aLandmark
1.302 + ) = 0;
1.303 +
1.304 + /**
1.305 + * Updates a landmark in the database.
1.306 + *
1.307 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.308 + *
1.309 + * Only landmark objects containing full landmark information can be
1.310 + * used to update a landmark. If a partial landmark (see
1.311 + * @ref ReadPartialLandmarkLC and @ref CPosLandmark::IsPartial) is
1.312 + * passed to this function it will leave with @p KErrArgument.
1.313 + *
1.314 + * Note that any updates in the database made since the landmark
1.315 + * object was read from the database will be overwritten by this
1.316 + * operation.
1.317 + *
1.318 + * A landmark can contain the IDs of the categories it belongs to. If
1.319 + * any of these categories does not exist in the database, the update
1.320 + * operation will still complete successfully but the category which
1.321 + * was not found will be ignored.
1.322 + *
1.323 + * This function requires @p ReadUserData and @p WriteUserData
1.324 + * capabilities.
1.325 + *
1.326 + * @param[in] aLandmark The new landmark data.
1.327 + *
1.328 + * @leave KErrArgument A partial landmark is passed.
1.329 + * @leave KErrAccessDenied The database is read-only.
1.330 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.331 + */
1.332 + virtual void UpdateLandmarkL(
1.333 + const CPosLandmark& aLandmark
1.334 + ) = 0;
1.335 +
1.336 + /**
1.337 + * Removes a landmark from the database.
1.338 + *
1.339 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.340 + *
1.341 + * If the landmark does not exist in the database, nothing happens.
1.342 + *
1.343 + * This function requires @p ReadUserData and @p WriteUserData
1.344 + * capabilities.
1.345 + *
1.346 + * @param aLandmarkId The ID of the landmark to remove.
1.347 + *
1.348 + * @leave KErrAccessDenied The database is read-only.
1.349 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.350 + */
1.351 + virtual void RemoveLandmarkL(
1.352 + TPosLmItemId aLandmarkId
1.353 + ) = 0;
1.354 +
1.355 + /**
1.356 + * Removes a set of landmarks from the database.
1.357 + *
1.358 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.359 + *
1.360 + * If any of the specified landmarks don't exist in the database,
1.361 + * nothing happens for those landmarks.
1.362 + *
1.363 + * The function returns an operation object which can be run in
1.364 + * incremental mode. If it is run incrementally the client can supervise
1.365 + * the progress of the operation.
1.366 + *
1.367 + * If the @ref CPosLmOperation object is deleted before the operation
1.368 + * is complete, it is possible that only a subset of the landmarks
1.369 + * have been deleted.
1.370 + *
1.371 + * The client takes ownership of the returned operation object.
1.372 + *
1.373 + * While removing landmarks, this operation will acquire a write-lock on
1.374 + * the database.
1.375 + *
1.376 + * This function requires @p ReadUserData and @p WriteUserData
1.377 + * capabilities.
1.378 + *
1.379 + * @param[in] aLandmarkIdArray The IDs of the landmarks to remove.
1.380 + * @returns A handle to the operation.
1.381 + *
1.382 + * @leave KErrAccessDenied The database is read-only.
1.383 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.384 + */
1.385 + virtual CPosLmOperation* RemoveLandmarksL(
1.386 + const RArray<TPosLmItemId>& aLandmarkIdArray
1.387 + ) = 0;
1.388 +
1.389 + /**
1.390 + * Removes all landmarks from the database.
1.391 + *
1.392 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.393 + *
1.394 + * The function returns an operation object which can be run in
1.395 + * incremental mode. If it is run incrementally the client can supervise
1.396 + * the progress of the operation.
1.397 + *
1.398 + * If the @ref CPosLmOperation object is deleted before the operation
1.399 + * is complete, it is possible that only a subset of the landmarks
1.400 + * have been deleted.
1.401 + *
1.402 + * The client takes ownership of the returned operation object.
1.403 + *
1.404 + * While removing landmarks, this operation will acquire a write-lock on
1.405 + * the database.
1.406 + *
1.407 + * This function requires @p ReadUserData and @p WriteUserData
1.408 + * capabilities.
1.409 + *
1.410 + * @returns A handle to the operation.
1.411 + *
1.412 + * @leave KErrAccessDenied The database is read-only.
1.413 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.414 + */
1.415 + virtual CPosLmOperation* RemoveAllLandmarksL() = 0;
1.416 +
1.417 + /**
1.418 + * Returns the partial read parameters for this database handle.
1.419 + *
1.420 + * Partial read parameters are used to define which landmark data should
1.421 + * be returned when @ref ReadPartialLandmarkLC is called.
1.422 + *
1.423 + * The client takes ownership of the returned parameter object.
1.424 + *
1.425 + * @returns The current partial read parameters.
1.426 + */
1.427 + virtual CPosLmPartialReadParameters* PartialReadParametersLC() = 0;
1.428 +
1.429 + /**
1.430 + * Sets the partial read parameters for this database handle.
1.431 + *
1.432 + * Partial read parameters are used to define which landmark data should
1.433 + * be returned when @ref ReadPartialLandmarkLC is called.
1.434 + *
1.435 + * @param[in] aPartialSettings The new partial read parameters.
1.436 + */
1.437 + virtual void SetPartialReadParametersL(
1.438 + const CPosLmPartialReadParameters& aPartialSettings
1.439 + ) = 0;
1.440 +
1.441 + /**
1.442 + * Reads partial data from a landmark in the database.
1.443 + *
1.444 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.445 + *
1.446 + * Partial settings define which landmark data should be returned in
1.447 + * this call. Partial read attributes are defined by calling
1.448 + * @ref SetPartialReadParametersL. If no partial read parameters have
1.449 + * been set, the landmarks will not contain any attributes.
1.450 + *
1.451 + * The client takes ownership of the returned landmark object.
1.452 + *
1.453 + * This function requires @p ReadUserData capability.
1.454 + *
1.455 + * @param The ID of the landmark to read.
1.456 + * @returns The requested landmark. The landmark object will only
1.457 + * contain the attributes defined in the partial read attributes. The
1.458 + * landmark object is put on the cleanup stack.
1.459 + *
1.460 + * @leave KErrNotFound The requested landmark does not exist in the database.
1.461 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.462 + */
1.463 + virtual CPosLandmark* ReadPartialLandmarkLC(
1.464 + TPosLmItemId aLandmarkId
1.465 + ) = 0;
1.466 +
1.467 + /**
1.468 + * Reads partial data from a set of landmarks in the database.
1.469 + *
1.470 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.471 + *
1.472 + * Partial settings define which landmark data should be read. Partial
1.473 + * read attributes are defined by calling @ref SetPartialReadParametersL.
1.474 + * If no partial read parameters have been set, the landmarks will not
1.475 + * contain any attributes.
1.476 + *
1.477 + * Note that the returned data may be very big if all attributes in
1.478 + * each landmark are requested. A typical use for this function is to
1.479 + * retrieve the names for a set of landmarks.
1.480 + *
1.481 + * When the request is completed, the result can be retrieved by calling
1.482 + * @ref TakePreparedPartialLandmarksL.
1.483 + *
1.484 + * The function returns an operation object which can be run in
1.485 + * incremental mode. If it is run incrementally the client can supervise
1.486 + * the progress of the operation.
1.487 + *
1.488 + * The client takes ownership of the returned operation object.
1.489 + *
1.490 + * While preparing landmark information, this operation will acquire a
1.491 + * read-lock on the database.
1.492 + *
1.493 + * This function requires @p ReadUserData capability.
1.494 + *
1.495 + * @param[in] aLandmarkIdArray An array with IDs of the landmarks to read.
1.496 + * @returns A handle to the operation.
1.497 + *
1.498 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.499 + */
1.500 + virtual CPosLmOperation* PreparePartialLandmarksL(
1.501 + const RArray<TPosLmItemId>& aLandmarkIdArray
1.502 + ) = 0;
1.503 +
1.504 + /**
1.505 + * Fetches the result from a call to @ref PreparePartialLandmarksL.
1.506 + *
1.507 + * @pre A call to this function must be preceeded by successful call to
1.508 + * @ref PreparePartialLandmarksL.
1.509 + *
1.510 + * The returned array will have the same length as the ID array passed
1.511 + * in the @ref PreparePartialLandmarksL call and it will have the same
1.512 + * order.
1.513 + *
1.514 + * If reading a landmark failed during preparation, the corresponding
1.515 + * pointer value in the returned array will be NULL. For instance,
1.516 + * reading can fail if the specified ID does not exist in the database.
1.517 + *
1.518 + * The client takes ownership of the returned array object including
1.519 + * the contained landmark objects.
1.520 + *
1.521 + * @param[in] aPreparePartialLandmarkOperation The operation object returned
1.522 + * by the @ref PreparePartialLandmarksL function.
1.523 + *
1.524 + * @returns An array containing the prepared partial landmark objects.
1.525 + *
1.526 + * @leave KErrNotFound @ref PreparePartialLandmarksL hasn't been called yet or
1.527 + * it didn't succeed or this function has been called already since then.
1.528 + */
1.529 + virtual CArrayPtr<CPosLandmark>* TakePreparedPartialLandmarksL(
1.530 + CPosLmOperation* aPreparePartialLandmarkOperation
1.531 + ) = 0;
1.532 +
1.533 + /**
1.534 + * Returns a URI which points to the landmark database storage.
1.535 + *
1.536 + * The URI may point to a file in the terminal file system or on a
1.537 + * remote file.
1.538 + *
1.539 + * The client takes ownership of the returned descriptor.
1.540 + *
1.541 + * @returns The database URI. The URI is put on the cleanup stack.
1.542 + */
1.543 + virtual HBufC* DatabaseUriLC() = 0;
1.544 +
1.545 + /**
1.546 + * Returns size information for the database.
1.547 + *
1.548 + * This function requires @p ReadUserData capability.
1.549 + *
1.550 + * @returns Size information for the database.
1.551 + */
1.552 + virtual TSize SizeL() = 0;
1.553 +
1.554 + /**
1.555 + * Compacts the landmark database.
1.556 + *
1.557 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.558 + *
1.559 + * Compaction means that any unused space in the database is removed.
1.560 + *
1.561 + * The function returns an operation object which can be run in
1.562 + * incremental mode. If it is run incrementally the client can supervise
1.563 + * the progress of the operation.
1.564 + *
1.565 + * The client takes ownership of the returned operation object.
1.566 + *
1.567 + * This function requires @p ReadUserData and @p WriteUserData
1.568 + * capabilities.
1.569 + *
1.570 + * @returns A handle to the operation.
1.571 + *
1.572 + * @leave KErrAccessDenied The database is read-only.
1.573 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.574 + */
1.575 + virtual CPosLmOperation* CompactL() = 0;
1.576 +
1.577 + /**
1.578 + * Listens for database events.
1.579 + *
1.580 + * This function is asynchronous and it will complete the request
1.581 + * status when an event occurs. At this time @p aEvent input parameter
1.582 + * is updated and the client can read event information from it.
1.583 + *
1.584 + * Event listening can be cancelled by calling
1.585 + * @ref CancelNotifyDatabaseEvent.
1.586 + *
1.587 + * This function requires @p ReadUserData capability.
1.588 + *
1.589 + * @param[out] aEvent Upon completion contains the event information.
1.590 + * @param[out] aStatus Upon completion contains status of the request.
1.591 + * @p KErrNotSupported if events are not supported.
1.592 + * @p KErrNone if an event occured, otherwise an error code if some error was encountered.
1.593 + *
1.594 + * @panic "Landmarks Client"-EPosEventNotifierAlreadyHasOutstandingRequest
1.595 + * Client already has an outstanding @ref NotifyDatabaseEvent request.
1.596 + */
1.597 + virtual void NotifyDatabaseEvent(
1.598 + TPosLmEvent& aEvent,
1.599 + TRequestStatus& aStatus
1.600 + ) = 0;
1.601 +
1.602 + /**
1.603 + * Cancels a call to @ref NotifyDatabaseEvent.
1.604 + *
1.605 + * This function requires @p ReadUserData capability.
1.606 + *
1.607 + * @return @p KErrNone if the request was successfully cancelled,
1.608 + * otherwise a system wide error code.
1.609 + */
1.610 + virtual TInt CancelNotifyDatabaseEvent() = 0;
1.611 +
1.612 + /**
1.613 + * Exports a number of landmarks.
1.614 + *
1.615 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.616 + *
1.617 + * To export a set of landmarks, the client must first create a
1.618 + * @ref CPosLandmarkEncoder object for the landmark content format in
1.619 + * which the landmarks should be encoded. The client can add some
1.620 + * information of the landmark collection in the encoder as well.
1.621 + *
1.622 + * The client must also provide a list of the landmarks which should be
1.623 + * exported. If one of the landmarks are not found in the database, the returned
1.624 + * operation fails with error code @p KErrNotFound.
1.625 + *
1.626 + * The client does not have to add any landmarks to the encoder object.
1.627 + * This function will add the ones specified in the ID array.
1.628 + *
1.629 + * The function returns an operation object which can be run in
1.630 + * incremental mode. If it is run incrementally the client can supervise
1.631 + * the progress of the operation.
1.632 + *
1.633 + * If the @ref CPosLmOperation object is deleted before the operation
1.634 + * is complete, it is possible that only a subset of the landmarks have
1.635 + * been exported.
1.636 + *
1.637 + * The client takes ownership of the returned operation object.
1.638 + *
1.639 + * When all landmarks have been exported the client must finalize
1.640 + * encoding by calling @ref CPosLandmarkEncoder::FinalizeEncodingL.
1.641 + *
1.642 + * This function requires @p ReadUserData capability.
1.643 + *
1.644 + * @param[in] aLandmarkEncoder A landmark encoder object.
1.645 + * @param[in] aLandmarkIdArray The landmarks which should be exported.
1.646 + * @param[in] aTransferOptions A bitmap representing the options for the
1.647 + * export operation. The bitmap values are defined by
1.648 + * @ref _TTransferOptions.
1.649 + *
1.650 + * @returns A handle to the operation.
1.651 + *
1.652 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.653 + *
1.654 + * @panic "Landmarks Client"-EPosLmInvalidArgument
1.655 + * Client specified invalid transfer option values.
1.656 + */
1.657 + virtual CPosLmOperation* ExportLandmarksL(
1.658 + CPosLandmarkEncoder& aLandmarkEncoder,
1.659 + const RArray<TPosLmItemId>& aLandmarkIdArray,
1.660 + TTransferOptions aTransferOptions
1.661 + ) = 0;
1.662 +
1.663 + /**
1.664 + * Import a set of landmarks.
1.665 + *
1.666 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.667 + *
1.668 + * To import landmark content, the client must first create a parser
1.669 + * object which can parse the landmark content. The client does not have
1.670 + * to call @ref CPosLandmarkParser::ParseContentL first. If the content
1.671 + * is not already parsed, this will be handled by the import operation.
1.672 + *
1.673 + * The function returns an operation object which can be run in
1.674 + * incremental mode. If it is run incrementally the client can supervise
1.675 + * the progress of the operation.
1.676 + *
1.677 + * If the @ref CPosLmOperation object is deleted before the operation
1.678 + * is complete, it is possible that only a subset of the landmarks have
1.679 + * been imported.
1.680 + *
1.681 + * The client takes ownership of the returned operation object.
1.682 + *
1.683 + * After completion @ref ImportedLandmarksIteratorL can be called to
1.684 + * retrieve the IDs of the added landmarks.
1.685 + *
1.686 + * The @p NextStep function in the operation object cannot be executed
1.687 + * synchronously using @p User::WaitForRequest. Doing so may cause the
1.688 + * operation to hang. @p NextStep must be run using an active object
1.689 + * for this operation.
1.690 + *
1.691 + * This function requires @p ReadUserData and @p WriteUserData
1.692 + * capabilities.
1.693 + *
1.694 + * @param[in] aLandmarkParser An object which can parse landmark content.
1.695 + * @param[in] aTransferOptions A bitmap representing the options for the
1.696 + * import operation. The bitmap values are defined by
1.697 + * @ref _TTransferOptions.
1.698 + *
1.699 + * @returns A handle to the operation.
1.700 + *
1.701 + * @leave KErrAccessDenied The database is read-only.
1.702 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.703 + *
1.704 + * @panic "Landmarks Client"-EPosLmInvalidArgument
1.705 + * Client specified invalid transfer option values.
1.706 + */
1.707 + virtual CPosLmOperation* ImportLandmarksL(
1.708 + CPosLandmarkParser& aLandmarkParser,
1.709 + TTransferOptions aTransferOptions
1.710 + ) = 0;
1.711 +
1.712 + /**
1.713 + * Import a set of landmarks.
1.714 + *
1.715 + * @pre Database is initialized (see @ref IsInitializingNeeded).
1.716 + *
1.717 + * To import landmark content, the client must first create a parser
1.718 + * object which can parse the landmark content. The client does not have
1.719 + * to call @ref CPosLandmarkParser::ParseContentL first. If the content
1.720 + * is not already parsed, this will be handled by the import operation.
1.721 + *
1.722 + * In this overload of the function, the client can pass an array
1.723 + * defining a subset of the landmarks in the parser object. This way
1.724 + * the client can select to import only a part of the landmark content.
1.725 + *
1.726 + * The function returns an operation object which can be run in
1.727 + * incremental mode. If it is run incrementally the client can supervise
1.728 + * the progress of the operation.
1.729 + *
1.730 + * If the @ref CPosLmOperation object is deleted before the operation
1.731 + * is complete, it is possible that only a subset of the landmarks have
1.732 + * been imported.
1.733 + *
1.734 + * The client takes ownership of the returned operation object.
1.735 + *
1.736 + * After completion @ref ImportedLandmarksIteratorL can be called to
1.737 + * retrieve the IDs of the added landmarks.
1.738 + *
1.739 + * The @p NextStep function in the operation object cannot be executed
1.740 + * synchronously using @p User::WaitForRequest. Doing so may cause the
1.741 + * operation to hang. @p NextStep must be run using an active object
1.742 + * for this operation.
1.743 + *
1.744 + * This function requires @p ReadUserData and @p WriteUserData
1.745 + * capabilities.
1.746 + *
1.747 + * @param[in] aLandmarkParser An object which can parse landmark content.
1.748 + * @param[in] aLandmarkSelection An array defining which of the parsed
1.749 + * landmarks to import. The array items refer to the order in which
1.750 + * @ref CPosLandmarkParser accesses the landmarks. 0 means the first
1.751 + * parsed landmark, 1 means the second, etc. If the parser supports
1.752 + * indexing, these numbers correspond to the index values used to
1.753 + * access the landmarks in @ref CPosLandmarkParser::LandmarkLC. The
1.754 + * index values must be less than the number of landmarks accessed by
1.755 + * the parser, otherwise the operation object will panic with error
1.756 + * code @p EPosInvalidIndex during execution. @p Note: The indexes
1.757 + * can be used regardless of whether the parser supports indexing or
1.758 + * not.
1.759 + * @param aTransferOptions A bitmap representing the options for the
1.760 + * import operation. The bitmap values are defined by
1.761 + * @ref _TTransferOptions.
1.762 + * @returns A handle to the operation.
1.763 + *
1.764 + * @leave KErrAccessDenied The database is read-only.
1.765 + * @leave KErrPosLmNotInitialized Database is not yet initialized.
1.766 + *
1.767 + * @panic "Landmarks Client"-EPosLmInvalidArgument
1.768 + * Client specified invalid transfer option values.
1.769 + */
1.770 + virtual CPosLmOperation* ImportLandmarksL(
1.771 + CPosLandmarkParser& aLandmarkParser,
1.772 + const RArray<TUint>& aLandmarkSelection,
1.773 + TTransferOptions aTransferOptions
1.774 + ) = 0;
1.775 +
1.776 + /**
1.777 + * Returns an object for iterating the landmarks added in an import
1.778 + * operation.
1.779 + *
1.780 + * To import landmarks @ref ImportLandmarksL is used.
1.781 + *
1.782 + * If @ref ImportedLandmarksIteratorL is called before the
1.783 + * @ref ImportLandmarksL operation has completed, the iterator will
1.784 + * iterate the landmarks imported so far. Landmarks imported after
1.785 + * the iterator is obtained will not affect the iterator. A new
1.786 + * iterator must be obtained to iterate these new landmarks.
1.787 + *
1.788 + * The client takes ownership of the returned iterator object.
1.789 + *
1.790 + * @param[in] aImportOperation This object is returned by
1.791 + * @ref ImportLandmarksL methods.
1.792 + * @returns An object for iterating the landmarks added in the latest
1.793 + * import operation.
1.794 + */
1.795 + virtual CPosLmItemIterator* ImportedLandmarksIteratorL(
1.796 + CPosLmOperation* aImportOperation
1.797 + ) = 0;
1.798 +
1.799 + /**
1.800 + * @internal */
1.801 + /*
1.802 + * Returns the database access implementation ID.
1.803 + *
1.804 + * @returns The @ref CPosLandmarkDatabase implementation ID.
1.805 + */
1.806 + TUid ImplementationId() const;
1.807 +
1.808 + protected:
1.809 +
1.810 + // C++ constructor.
1.811 + IMPORT_C CPosLandmarkDatabase();
1.812 +
1.813 + private:
1.814 +
1.815 + // Prohibit copy constructor
1.816 + CPosLandmarkDatabase( const CPosLandmarkDatabase& );
1.817 + // Prohibit assigment operator
1.818 + CPosLandmarkDatabase& operator= ( const CPosLandmarkDatabase& );
1.819 +
1.820 + protected:
1.821 +
1.822 + // Implementation Uid
1.823 + TUid iDtorIdKey;
1.824 + };
1.825 +
1.826 +#endif // CPOSLANDMARKDATABASE_H
1.827 +
1.828 +