1.1 --- a/epoc32/include/mw/epos_cposlmdatabasemanager.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/epos_cposlmdatabasemanager.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,447 @@
1.4 -epos_cposlmdatabasemanager.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: CPosLmDatabaseManager class
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +#ifndef CPOSLMDATABASEMANAGER_H
1.25 +#define CPOSLMDATABASEMANAGER_H
1.26 +
1.27 +#include <e32base.h>
1.28 +#include <badesca.h>
1.29 +#include "EPos_TPosLmDatabaseEvent.h"
1.30 +#include "EPos_TPosLmDatabaseSettings.h"
1.31 +#include "EPos_HPosLmDatabaseInfo.h"
1.32 +
1.33 +
1.34 +/**
1.35 +* This class is used to manage landmark databases.
1.36 +*
1.37 +* @p CPosLmDatabaseManager contains functions for listing registering,
1.38 +* unregistering, creating, deleting, copying landmark databases, etc.
1.39 +* It also has functions for managing the default landmark database. The
1.40 +* client can listen to events related to database management.
1.41 +*
1.42 +* A database is local if it resides in the phone or in some device which
1.43 +* is mapped to the phones file system. If a database is not local, it is
1.44 +* remote.
1.45 +*
1.46 +* The client refers to a database by URI. The URI consists of a protocol
1.47 +* specifier and the database location: "protocol://location". If the
1.48 +* client does not specify a protocol, "file://" is assumed.
1.49 +*
1.50 +* For local landmark databases, the URI consists of the drive and the
1.51 +* database file name, e.g. "c:landmarks.ldb". The path cannot be specified
1.52 +* by the client. The extension of the database file name must be "ldb".
1.53 +* If a path is included or if the file name extension is not .ldb",
1.54 +* the client receives the error code @p KErrArgument. For local landmark
1.55 +* databases, the client receives the error code @p KErrBadName if the
1.56 +* file name is invalid and @p KErrNotReady if the drive specified in the URI
1.57 +* does not exist.
1.58 +*
1.59 +* If the client specifies a local database URI and does not specify the drive
1.60 +* letter, e.g. "landmarks.ldb", default database drive is assumed.
1.61 +*
1.62 +* Local databases are created by calling @ref CreateDatabaseL. "Bookmarks"
1.63 +* to remote databases are created by calling @ref RegisterDatabaseL. After
1.64 +* this they are listed by the database manager.
1.65 +*
1.66 +* If @ref CPosLmDatabaseManager is used, the client must call the global
1.67 +* function @ref ReleaseLandmarkResources before terminating, in order to
1.68 +* release all used landmark resources, otherwise the client may receive
1.69 +* an ALLOC panic.
1.70 +*
1.71 +* @lib eposlmdbmanlib.lib
1.72 +* @since S60 3.0
1.73 +*/
1.74 +class CPosLmDatabaseManager : public CBase
1.75 + {
1.76 + public:
1.77 +
1.78 + /**
1.79 + * Two-phased constructor.
1.80 + *
1.81 + * This function requires @p ReadUserData capability.
1.82 + */
1.83 + IMPORT_C static CPosLmDatabaseManager* NewL();
1.84 +
1.85 + /**
1.86 + * Destructor.
1.87 + */
1.88 + IMPORT_C virtual ~CPosLmDatabaseManager();
1.89 +
1.90 + public:
1.91 +
1.92 + /**
1.93 + * Retrieves the URI of the default landmark database.
1.94 + *
1.95 + * The default landmark database is the one which is opened when calling
1.96 + * @p CPosLandmarkDatabase::OpenL without any parameters.
1.97 + *
1.98 + * Only "file"-protocol databases can be set as default.
1.99 + *
1.100 + * This function requires @p ReadUserData capability.
1.101 + *
1.102 + * @return The URI of the default landmark database. The client takes
1.103 + * ownership of the descriptor object.
1.104 + */
1.105 + virtual HBufC* DefaultDatabaseUriLC() = 0;
1.106 +
1.107 + /**
1.108 + * Sets a landmark database as default.
1.109 + *
1.110 + * This database is opened the next time
1.111 + * @p CPosLandmarkDatabase::OpenL() called without parameters.
1.112 + *
1.113 + * To move the current default database to another drive, first use
1.114 + * @ref CopyDatabaseL to copy the database to the new drive, then use
1.115 + * @ref SetDefaultDatabaseUriL to set the new database as default and
1.116 + * finally, use @ref DeleteDatabaseL if the old default database should
1.117 + * be deleted.
1.118 + *
1.119 + * Only "file"-protocol databases can be set as default.
1.120 + *
1.121 + * This function requires @p WriteDeviceData capability.
1.122 + *
1.123 + * @param[in] aDatabaseUri The URI of the database which should be set as
1.124 + * default.
1.125 + * @leave KErrNotSupported The protocol specified something else
1.126 + * than "file://" as protocol in the URI.
1.127 + * @leave KErrArgument The URI is incorrect.
1.128 + * @leave KErrNotFound The landmark database which should be set as default
1.129 + * does not exist.
1.130 + */
1.131 + virtual void SetDefaultDatabaseUriL( const TDesC& aDatabaseUri ) = 0;
1.132 +
1.133 + /**
1.134 + * Listens for database management events.
1.135 + *
1.136 + * This function is asynchronous and it completes the request
1.137 + * status when an event occurs. At this time, the client can read
1.138 + * event information from the retrieved event object.
1.139 + *
1.140 + * Event listening can be canceled by calling
1.141 + * @ref CancelNotifyDatabaseEvent.
1.142 + *
1.143 + * This function requires @p ReadUserData capability.
1.144 + *
1.145 + * @param[out] aEvent Contains the event information when an event
1.146 + * occurs (request completes).
1.147 + * @param[out] aStatus Is completed with @p KErrNone if an event
1.148 + * occurs or an error code if some error is encountered.
1.149 + */
1.150 + virtual void NotifyDatabaseEvent(
1.151 + TPosLmDatabaseEvent& aEvent,
1.152 + TRequestStatus& aStatus
1.153 + ) = 0;
1.154 +
1.155 + /**
1.156 + * Cancels a call to @ref NotifyDatabaseEvent.
1.157 + *
1.158 + * @return @p KErrNone if the request was successfully cancelled,
1.159 + * otherwise a system wide error code.
1.160 + */
1.161 + virtual TInt CancelNotifyDatabaseEvent() = 0;
1.162 +
1.163 + /**
1.164 + * Retrieves the database URI associated with the last event.
1.165 + *
1.166 + * Some events, e.g. @p EPosLmDbDatabaseRegistered and
1.167 + * @p EPosLmDbDatabaseUnregistered, refer to a specific database. The
1.168 + * URI of the database can be retrieved through this function.
1.169 + *
1.170 + * If the URI should be retrieved, this function must be called before
1.171 + * @ref NotifyDatabaseEvent is called again to listen for the next
1.172 + * event.
1.173 + *
1.174 + * This function requires @p ReadUserData capability.
1.175 + *
1.176 + * @return The database URI associated with the event. The client takes
1.177 + * ownership of the descriptor object.
1.178 + * @leave KErrNotFound There is no database URI associated with the event
1.179 + * or, the database URI has been discarded because the client has called
1.180 + * @ref NotifyDatabaseEvent again.
1.181 + */
1.182 + virtual HBufC* DatabaseUriFromLastEventLC() = 0;
1.183 +
1.184 + /**
1.185 + * Lists the URIs to all landmark databases known by the Landmarks
1.186 + * system.
1.187 + *
1.188 + * The client can specify a protocol string as input to this function.
1.189 + * The function then only returns a list of the databases which
1.190 + * are accessed through this protocol.
1.191 + *
1.192 + * The client takes ownership of the returned array.
1.193 + *
1.194 + * If no databases are found, an empty array is returned.
1.195 + *
1.196 + * This function requires @p ReadUserData capability.
1.197 + *
1.198 + * @param[in] aProtocol The protocol for which database URIs should be
1.199 + * listed. If no protocol is specified, i.e. if an empty string is
1.200 + * specified, all known database URIs are listed.
1.201 + * @return The list of database URIs.
1.202 + * @leave KErrNotSupported The protocol is not supported in the platform.
1.203 + */
1.204 + virtual CDesCArray* ListDatabasesLC( const TDesC& aProtocol = KNullDesC ) = 0;
1.205 +
1.206 + /**
1.207 + * Lists information about each landmark database known by the Landmarks
1.208 + * system.
1.209 + *
1.210 + * The client can specify a protocol string as input to this function.
1.211 + * The function then only returns information about the databases
1.212 + * which are accessed through this protocol.
1.213 + *
1.214 + * The client specifies an array which is populated by this function.
1.215 + * The client takes ownership of all information objects in the array.
1.216 + *
1.217 + * If no databases are found, an empty array is returned.
1.218 + *
1.219 + * This function requires @p ReadUserData capability.
1.220 + *
1.221 + * @param[out] aDatabaseInfoArray On return, contains information about
1.222 + * the landmark databases. Any objects which are in the array when
1.223 + * it is passed to this function are not removed.
1.224 + * @param[in] aProtocol The protocol for which database URIs should be
1.225 + * listed. If no protocol is specified, i.e. if an empty string is
1.226 + * specified, all known database URIs are listed.
1.227 + * @leave KErrNotSupported The protocol is not supported in the platform.
1.228 + */
1.229 + virtual void ListDatabasesL(
1.230 + RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,
1.231 + const TDesC& aProtocol = KNullDesC
1.232 + ) = 0;
1.233 +
1.234 + /**
1.235 + * Registers a landmark database.
1.236 + *
1.237 + * The landmark database is then returned when listing landmark
1.238 + * databases.
1.239 + *
1.240 + * For local landmark databases, this function leaves with error code
1.241 + * @p KErrNotSupported. To add a local database, the client must call
1.242 + * @ref CreateDatabaseL.
1.243 + *
1.244 + * The client supplies an information object containing the URI of the
1.245 + * database to register. The information object can also contain
1.246 + * database settings, e.g. a display name for the database.
1.247 + *
1.248 + * This function requires @p ReadUserData and @p WriteUserData
1.249 + * capabilities.
1.250 + *
1.251 + * @param[in,out] aDatabaseInfo Information about the landmark database to
1.252 + * register. The information object will be updated with
1.253 + * media type and drive information.
1.254 + *
1.255 + * @leave KErrNotSupported The protocol specified in the URI is not
1.256 + * supported in the platform or the protocol does not allow
1.257 + * registering landmark databases.
1.258 + * @leave KErrArgument The URI is incorrect.
1.259 + * @leave KErrAlreadyExists The database already exists in the registry.
1.260 + */
1.261 + virtual void RegisterDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
1.262 +
1.263 + /**
1.264 + * Unregisters a landmark database.
1.265 + *
1.266 + * After this, the landmark database is not returned when listing
1.267 + * landmark databases.
1.268 + *
1.269 + * For local landmark databases, this function leaves with error code
1.270 + * @p KErrNotSupported. To remove a local database, the client must call
1.271 + * @ref DeleteDatabaseL.
1.272 + *
1.273 + * This function requires @p ReadUserData and @p WriteUserData
1.274 + * capabilities.
1.275 + *
1.276 + * @param[in] aDatabaseUri The URI of the database to register.
1.277 + *
1.278 + * @leave KErrNotSupported The protocol specified in the URI is not
1.279 + * supported in the platform or the protocol does not allow
1.280 + * unregistering landmark databases.
1.281 + * @leave KErrArgument The URI is incorrect.
1.282 + */
1.283 + virtual void UnregisterDatabaseL( const TDesC& aDatabaseUri ) = 0;
1.284 +
1.285 + /**
1.286 + * Unregisters all landmark database which are accessed through a
1.287 + * certain protocol.
1.288 + *
1.289 + * After this, the landmark databases are not be returned when listing
1.290 + * landmark databases.
1.291 + *
1.292 + * For local landmark databases, this function leaves with error code
1.293 + * @p KErrNotSupported. To remove a local database, the client must call
1.294 + * @ref DeleteDatabaseL.
1.295 + *
1.296 + * This function requires @p ReadUserData and @p WriteUserData
1.297 + * capabilities.
1.298 + *
1.299 + * @param[in] aProtocol The protocol to unregister all databases for.
1.300 + *
1.301 + * @leave KErrNotSupported The protocol is not supported in the platform
1.302 + * or the protocol does not allow unregistering landmark databases.
1.303 + * @leave KErrArgument The protocol is an empty string.
1.304 + */
1.305 + virtual void UnregisterAllDatabasesL( const TDesC& aProtocol ) = 0;
1.306 +
1.307 + /**
1.308 + * Modifies the settings for a landmark database.
1.309 + *
1.310 + * This function requires @p ReadUserData and @p WriteUserData
1.311 + * capabilities.
1.312 + *
1.313 + * @param[in] aDatabaseUri The URI of the database to modify settings for.
1.314 + * @param[in] aDatabaseSettings The new settings for the database.
1.315 + *
1.316 + * @leave KErrNotSupported The protocol specified in the URI is not
1.317 + * supported in the platform.
1.318 + * @leave KErrNotFound The specified database is not found.
1.319 + * @leave KErrArgument The URI is incorrect.
1.320 + */
1.321 + virtual void ModifyDatabaseSettingsL(
1.322 + const TDesC& aDatabaseUri,
1.323 + const TPosLmDatabaseSettings& aDatabaseSettings
1.324 + ) = 0;
1.325 +
1.326 + /**
1.327 + * Retrieve information about a landmark database.
1.328 + *
1.329 + * This function requires @p ReadUserData capability.
1.330 + *
1.331 + * @param[in,out] aDatabaseInfo An information object containing the URI of the
1.332 + * landmark database. On return, the object contains information about
1.333 + * the landmark database, including any database settings.
1.334 + *
1.335 + * @leave KErrNotSupported The protocol specified in the URI is not
1.336 + * supported in the platform.
1.337 + * @leave KErrNotFound The specified database is not found.
1.338 + * @leave KErrArgument The URI is incorrect.
1.339 + */
1.340 + virtual void GetDatabaseInfoL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
1.341 +
1.342 + /**
1.343 + * Checks if the specified landmark database exists.
1.344 + *
1.345 + * The database to check is specified by passing a URI to this function.
1.346 + * URI construction is described in the class description for
1.347 + * @ref CPosLmDatabaseManager. The URI must point to a database which is
1.348 + * handled by this database manager, i.e. not a remote location.
1.349 + *
1.350 + * This function requires @p ReadUserData capability. If the database is
1.351 + * remote, @p NetworkServices capability is also needed.
1.352 + *
1.353 + * @param[in] aDatabaseUri The URI of the database which should be checked
1.354 + * for existence.
1.355 + * @return @p ETrue if the database exists, otherwise @p EFalse.
1.356 + *
1.357 + * @leave KErrNotSupported The protocol specified in the URI is not
1.358 + * supported.
1.359 + * @leave KErrArgument The URI is incorrect.
1.360 + */
1.361 + virtual TBool DatabaseExistsL( const TDesC& aDatabaseUri ) = 0;
1.362 +
1.363 + /**
1.364 + * Creates a landmark database.
1.365 + *
1.366 + * This function requires @p ReadUserData and @p WriteUserData
1.367 + * capabilities. If the database is remote, @p NetworkServices
1.368 + * capability is also needed.
1.369 + *
1.370 + * @param aDatabaseInfo Information about the landmark database to
1.371 + * create. The information object will be updated with
1.372 + * media type and drive information.
1.373 + *
1.374 + * @leave KErrNotSupported The protocol specified in the URI is not
1.375 + * supported.
1.376 + * @leave KErrArgument The URI is incorrect.
1.377 + * @leave KErrAlreadyExists There is already a database at this URI.
1.378 + */
1.379 + virtual void CreateDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
1.380 +
1.381 + /**
1.382 + * Deletes a landmark database.
1.383 + *
1.384 + * The database to delete is specified by passing a URI to this
1.385 + * function. URI construction is described in the class description for
1.386 + * @ref CPosLmDatabaseManager.
1.387 + *
1.388 + * If the specified database does not exist, the call is ignored.
1.389 + *
1.390 + * This function requires @p ReadUserData and @p WriteUserData
1.391 + * capabilities. If the database is remote, @p NetworkServices
1.392 + * capability is also needed.
1.393 + *
1.394 + * @param aDatabaseUri The URI of the database to delete.
1.395 + *
1.396 + * @leave KErrNotSupported The protocol specified in the URI is not
1.397 + * supported.
1.398 + * @leave KErrArgument The URI is incorrect.
1.399 + * @leave KErrInUse The database is in use by some client.
1.400 + * @leave KErrAccessDenied The database is read-only.
1.401 + */
1.402 + virtual void DeleteDatabaseL( const TDesC& aDatabaseUri ) = 0;
1.403 +
1.404 + /**
1.405 + * Copies a landmark database to a new location.
1.406 + *
1.407 + * Database locations are specified as URIs. URI construction is
1.408 + * described in the class description for @ref CPosLmDatabaseManager.
1.409 + * Target URI protocol must be the same as source URI protocol.
1.410 + *
1.411 + * This function requires @p ReadUserData and @p WriteUserData
1.412 + * capabilities. If the databases are remote, @p NetworkServices
1.413 + * capability is also needed.
1.414 + *
1.415 + * @param[in] aSourceUri The URI of the database to copy.
1.416 + * @param[in] aTargetUri The URI of the new database location.
1.417 + *
1.418 + * @leave KErrNotSupported The protocol specified in the a URI is not
1.419 + * supported.
1.420 + * @leave KErrArgument A URI is incorrect.
1.421 + * @leave KErrAlreadyExists There is already a database at the target URI.
1.422 + * @leave KErrInUse There is a write-lock on the database, e.g. some client
1.423 + * is currently modifying the database.
1.424 + * @leave KErrNotFound There is no database at the source URI.
1.425 + */
1.426 + virtual void CopyDatabaseL(
1.427 + const TDesC& aSourceUri,
1.428 + const TDesC& aTargetUri
1.429 + ) = 0;
1.430 +
1.431 + protected:
1.432 +
1.433 + // C++ constructor.
1.434 + IMPORT_C CPosLmDatabaseManager();
1.435 +
1.436 + private:
1.437 +
1.438 + // Prohibit copy constructor
1.439 + CPosLmDatabaseManager( const CPosLmDatabaseManager& );
1.440 + // Prohibit assigment operator
1.441 + CPosLmDatabaseManager& operator= ( const CPosLmDatabaseManager& );
1.442 +
1.443 + private:
1.444 +
1.445 + // Implementation Uid
1.446 + TUid iDtorIdKey;
1.447 + };
1.448 +
1.449 +#endif // CPOSLMDATABASEMANAGER_H
1.450 +
1.451 +