epoc32/include/mw/epos_cposlmdatabasemanager.h
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
child 4 837f303aceeb
     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 +