1 epos_cposlmdatabasemanager.h

     1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   CPosLmDatabaseManager class

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CPOSLMDATABASEMANAGER_H

    21 #define CPOSLMDATABASEMANAGER_H

    22 

    23 #include <e32base.h>

    24 #include <badesca.h>

    25 #include "EPos_TPosLmDatabaseEvent.h"

    26 #include "EPos_TPosLmDatabaseSettings.h"

    27 #include "EPos_HPosLmDatabaseInfo.h"

    28 

    29 

    30 /**

    31 *  This class is used to manage landmark databases.

    32 *

    33 *  @p CPosLmDatabaseManager contains functions for listing registering,

    34 *  unregistering, creating, deleting, copying landmark databases, etc.

    35 *  It also has functions for managing the default landmark database. The

    36 *  client can listen to events related to database management.

    37 *

    38 *  A database is local if it resides in the phone or in some device which

    39 *  is mapped to the phones file system. If a database is not local, it is

    40 *  remote.

    41 *

    42 *  The client refers to a database by URI. The URI consists of a protocol

    43 *  specifier and the database location: "protocol://location". If the

    44 *  client does not specify a protocol, "file://" is assumed.

    45 *

    46 *  For local landmark databases, the URI consists of the drive and the

    47 *  database file name, e.g. "c:landmarks.ldb". The path cannot be specified

    48 *  by the client. The extension of the database file name must be "ldb".

    49 *  If a path is included or if the file name extension is not .ldb",

    50 *  the client receives the error code @p KErrArgument. For local landmark

    51 *  databases, the client receives the error code @p KErrBadName if the

    52 *  file name is invalid and @p KErrNotReady if the drive specified in the URI

    53 *  does not exist.

    54 *

    55 *  If the client specifies a local database URI and does not specify the drive

    56 *  letter, e.g. "landmarks.ldb", default database drive is assumed.

    57 *

    58 *  Local databases are created by calling @ref CreateDatabaseL. "Bookmarks"

    59 *  to remote databases are created by calling @ref RegisterDatabaseL. After

    60 *  this they are listed by the database manager.

    61 *

    62 *  If @ref CPosLmDatabaseManager is used, the client must call the global

    63 *  function @ref ReleaseLandmarkResources before terminating, in order to

    64 *  release all used landmark resources, otherwise the client may receive

    65 *  an ALLOC panic.

    66 *

    67 *  @lib eposlmdbmanlib.lib

    68 *  @since S60 3.0

    69 */

    70 class CPosLmDatabaseManager : public CBase

    71     {

    72     public:

    73 

    74         /**

    75         * Two-phased constructor.

    76         *

    77         * This function requires @p ReadUserData capability.

    78         */

    79         IMPORT_C static CPosLmDatabaseManager* NewL();

    80 

    81         /**

    82         * Destructor.

    83         */

    84         IMPORT_C virtual ~CPosLmDatabaseManager();

    85 

    86     public:

    87 

    88         /**

    89         * Retrieves the URI of the default landmark database.

    90         *

    91         * The default landmark database is the one which is opened when calling

    92         * @p CPosLandmarkDatabase::OpenL without any parameters.

    93         *

    94         * Only "file"-protocol databases can be set as default.

    95         *

    96         * This function requires @p ReadUserData capability.

    97         *

    98         * @return The URI of the default landmark database. The client takes

    99         *   ownership of the descriptor object.

   100         */

   101         virtual HBufC* DefaultDatabaseUriLC() = 0;

   102 

   103         /**

   104         * Sets a landmark database as default.

   105         *

   106         * This database is opened the next time

   107         * @p CPosLandmarkDatabase::OpenL() called without parameters.

   108         *

   109         * To move the current default database to another drive, first use

   110         * @ref CopyDatabaseL to copy the database to the new drive, then use

   111         * @ref SetDefaultDatabaseUriL to set the new database as default and

   112         * finally, use @ref DeleteDatabaseL if the old default database should

   113         * be deleted.

   114         *

   115         * Only "file"-protocol databases can be set as default.

   116         *

   117         * This function requires @p WriteDeviceData capability.

   118         *

   119         * @param[in] aDatabaseUri The URI of the database which should be set as

   120         *   default.

   121         * @leave KErrNotSupported The protocol specified something else

   122         *   than "file://" as protocol in the URI.

   123         * @leave KErrArgument The URI is incorrect.

   124         * @leave KErrNotFound The landmark database which should be set as default

   125         *   does not exist.

   126         */

   127         virtual void SetDefaultDatabaseUriL( const TDesC& aDatabaseUri ) = 0;

   128 

   129         /**

   130         * Listens for database management events.

   131         *

   132         * This function is asynchronous and it completes the request

   133         * status when an event occurs. At this time, the client can read

   134         * event information from the retrieved event object.

   135         *

   136         * Event listening can be canceled by calling

   137         * @ref CancelNotifyDatabaseEvent.

   138         *

   139         * This function requires @p ReadUserData capability.

   140         *

   141         * @param[out] aEvent Contains the event information when an event

   142         *   occurs (request completes).

   143         * @param[out] aStatus Is completed with @p KErrNone if an event

   144         *   occurs or an error code if some error is encountered.

   145         */

   146         virtual void NotifyDatabaseEvent(

   147             TPosLmDatabaseEvent& aEvent,

   148             TRequestStatus& aStatus

   149         ) = 0;

   150 

   151         /**

   152         * Cancels a call to @ref NotifyDatabaseEvent.

   153         *

   154         * @return @p KErrNone if the request was successfully cancelled,

   155         *   otherwise a system wide error code.

   156         */

   157         virtual TInt CancelNotifyDatabaseEvent() = 0;

   158 

   159         /**

   160         * Retrieves the database URI associated with the last event.

   161         *

   162         * Some events, e.g. @p EPosLmDbDatabaseRegistered and

   163         * @p EPosLmDbDatabaseUnregistered, refer to a specific database. The

   164         * URI of the database can be retrieved through this function.

   165         *

   166         * If the URI should be retrieved, this function must be called before

   167         * @ref NotifyDatabaseEvent is called again to listen for the next

   168         * event.

   169         *

   170         * This function requires @p ReadUserData capability.

   171         *

   172         * @return The database URI associated with the event. The client takes

   173         *   ownership of the descriptor object.

   174         * @leave KErrNotFound There is no database URI associated with the event

   175         *   or, the database URI has been discarded because the client has called

   176         *   @ref NotifyDatabaseEvent again.

   177         */

   178         virtual HBufC* DatabaseUriFromLastEventLC() = 0;

   179 

   180         /**

   181         * Lists the URIs to all landmark databases known by the Landmarks

   182         * system.

   183         *

   184         * The client can specify a protocol string as input to this function.

   185         * The function then only returns a list of the databases which

   186         * are accessed through this protocol.

   187         *

   188         * The client takes ownership of the returned array.

   189         *

   190         * If no databases are found, an empty array is returned.

   191         *

   192         * This function requires @p ReadUserData capability.

   193         *

   194         * @param[in] aProtocol The protocol for which database URIs should be

   195         *   listed. If no protocol is specified, i.e. if an empty string is

   196         *   specified, all known database URIs are listed.

   197         * @return The list of database URIs.

   198         * @leave KErrNotSupported The protocol is not supported in the platform.

   199         */

   200         virtual CDesCArray* ListDatabasesLC( const TDesC& aProtocol = KNullDesC ) = 0;

   201 

   202         /**

   203         * Lists information about each landmark database known by the Landmarks

   204         * system.

   205         *

   206         * The client can specify a protocol string as input to this function.

   207         * The function then only returns information about the databases

   208         * which are accessed through this protocol.

   209         *

   210         * The client specifies an array which is populated by this function.

   211         * The client takes ownership of all information objects in the array.

   212         *

   213         * If no databases are found, an empty array is returned.

   214         *

   215         * This function requires @p ReadUserData capability.

   216         *

   217         * @param[out] aDatabaseInfoArray On return, contains information about

   218         *   the landmark databases. Any objects which are in the array when

   219         *   it is passed to this function are not removed.

   220         * @param[in] aProtocol The protocol for which database URIs should be

   221         *   listed. If no protocol is specified, i.e. if an empty string is

   222         *   specified, all known database URIs are listed.

   223         * @leave KErrNotSupported The protocol is not supported in the platform.

   224         */

   225         virtual void ListDatabasesL(

   226             RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,

   227             const TDesC& aProtocol = KNullDesC

   228         ) = 0;

   229 

   230         /**

   231         * Registers a landmark database.

   232         *

   233         * The landmark database is then returned when listing landmark

   234         * databases.

   235         *

   236         * For local landmark databases, this function leaves with error code

   237         * @p KErrNotSupported. To add a local database, the client must call

   238         * @ref CreateDatabaseL.

   239         *

   240         * The client supplies an information object containing the URI of the

   241         * database to register. The information object can also contain

   242         * database settings, e.g. a display name for the database.

   243         *

   244         * This function requires @p ReadUserData and @p WriteUserData

   245         * capabilities.

   246         *

   247         * @param[in,out] aDatabaseInfo Information about the landmark database to

   248         *   register. The information object will be updated with

   249         *   media type and drive information.

   250         *

   251         * @leave KErrNotSupported The protocol specified in the URI is not

   252         *   supported in the platform or the protocol does not allow

   253         *   registering landmark databases.

   254         * @leave KErrArgument The URI is incorrect.

   255         * @leave KErrAlreadyExists The database already exists in the registry.

   256         */

   257         virtual void RegisterDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

   258 

   259         /**

   260         * Unregisters a landmark database.

   261         *

   262         * After this, the landmark database is not returned when listing

   263         * landmark databases.

   264         *

   265         * For local landmark databases, this function leaves with error code

   266         * @p KErrNotSupported. To remove a local database, the client must call

   267         * @ref DeleteDatabaseL.

   268         *

   269         * This function requires @p ReadUserData and @p WriteUserData

   270         * capabilities.

   271         *

   272         * @param[in] aDatabaseUri The URI of the database to register.

   273         *

   274         * @leave KErrNotSupported The protocol specified in the URI is not

   275         *   supported in the platform or the protocol does not allow

   276         *   unregistering landmark databases.

   277         * @leave KErrArgument The URI is incorrect.

   278         */

   279         virtual void UnregisterDatabaseL( const TDesC& aDatabaseUri ) = 0;

   280 

   281         /**

   282         * Unregisters all landmark database which are accessed through a

   283         * certain protocol.

   284         *

   285         * After this, the landmark databases are not be returned when listing

   286         * landmark databases.

   287         *

   288         * For local landmark databases, this function leaves with error code

   289         * @p KErrNotSupported. To remove a local database, the client must call

   290         * @ref DeleteDatabaseL.

   291         *

   292         * This function requires @p ReadUserData and @p WriteUserData

   293         * capabilities.

   294         *

   295         * @param[in] aProtocol The protocol to unregister all databases for.

   296         *

   297         * @leave KErrNotSupported The protocol is not supported in the platform

   298         *   or the protocol does not allow unregistering landmark databases.

   299         * @leave KErrArgument The protocol is an empty string.

   300         */

   301         virtual void UnregisterAllDatabasesL( const TDesC& aProtocol ) = 0;

   302 

   303         /**

   304         * Modifies the settings for a landmark database.

   305         *

   306         * This function requires @p ReadUserData and @p WriteUserData

   307         * capabilities.

   308         *

   309         * @param[in] aDatabaseUri The URI of the database to modify settings for.

   310         * @param[in] aDatabaseSettings The new settings for the database.

   311         *

   312         * @leave KErrNotSupported The protocol specified in the URI is not

   313         *   supported in the platform.

   314         * @leave KErrNotFound The specified database is not found.

   315         * @leave KErrArgument The URI is incorrect.

   316         */

   317         virtual void ModifyDatabaseSettingsL(

   318             const TDesC& aDatabaseUri,

   319             const TPosLmDatabaseSettings& aDatabaseSettings

   320         ) = 0;

   321 

   322         /**

   323         * Retrieve information about a landmark database.

   324         *

   325         * This function requires @p ReadUserData capability.

   326         *

   327         * @param[in,out] aDatabaseInfo An information object containing the URI of the

   328         *   landmark database. On return, the object contains information about

   329         *   the landmark database, including any database settings.

   330         *

   331         * @leave KErrNotSupported The protocol specified in the URI is not

   332         *   supported in the platform.

   333         * @leave KErrNotFound The specified database is not found.

   334         * @leave KErrArgument The URI is incorrect.

   335         */

   336         virtual void GetDatabaseInfoL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

   337 

   338         /**

   339         * Checks if the specified landmark database exists.

   340         *

   341         * The database to check is specified by passing a URI to this function.

   342         * URI construction is described in the class description for

   343         * @ref CPosLmDatabaseManager. The URI must point to a database which is

   344         * handled by this database manager, i.e. not a remote location.

   345         *

   346         * This function requires @p ReadUserData capability. If the database is

   347         * remote, @p NetworkServices capability is also needed.

   348         *

   349         * @param[in] aDatabaseUri The URI of the database which should be checked

   350         *   for existence.

   351         * @return @p ETrue if the database exists, otherwise @p EFalse.

   352         *

   353         * @leave KErrNotSupported The protocol specified in the URI is not

   354         *   supported.

   355         * @leave KErrArgument The URI is incorrect.

   356         */

   357         virtual TBool DatabaseExistsL( const TDesC&  aDatabaseUri ) = 0;

   358 

   359         /**

   360         * Creates a landmark database.

   361         *

   362         * This function requires @p ReadUserData and @p WriteUserData

   363         * capabilities. If the database is remote, @p NetworkServices

   364         * capability is also needed.

   365         *

   366         * @param aDatabaseInfo Information about the landmark database to

   367         *   create. The information object will be updated with

   368         *   media type and drive information.

   369         *

   370         * @leave KErrNotSupported The protocol specified in the URI is not

   371         *   supported.

   372         * @leave KErrArgument The URI is incorrect.

   373         * @leave KErrAlreadyExists There is already a database at this URI.

   374         */

   375         virtual void CreateDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

   376 

   377         /**

   378         * Deletes a landmark database.

   379         *

   380         * The database to delete is specified by passing a URI to this

   381         * function. URI construction is described in the class description for

   382         * @ref CPosLmDatabaseManager.

   383         *

   384         * If the specified database does not exist, the call is ignored.

   385         *

   386         * This function requires @p ReadUserData and @p WriteUserData

   387         * capabilities. If the database is remote, @p NetworkServices

   388         * capability is also needed.

   389         *

   390         * @param aDatabaseUri The URI of the database to delete.

   391         *

   392         * @leave KErrNotSupported The protocol specified in the URI is not

   393         *   supported.

   394         * @leave KErrArgument The URI is incorrect.

   395         * @leave KErrInUse The database is in use by some client.

   396         * @leave KErrAccessDenied The database is read-only.

   397         */

   398         virtual void DeleteDatabaseL( const TDesC& aDatabaseUri ) = 0;

   399 

   400         /**

   401         * Copies a landmark database to a new location.

   402         *

   403         * Database locations are specified as URIs. URI construction is

   404         * described in the class description for @ref CPosLmDatabaseManager.

   405         * Target URI protocol must be the same as source URI protocol.

   406         *

   407         * This function requires @p ReadUserData and @p WriteUserData

   408         * capabilities. If the databases are remote, @p NetworkServices

   409         * capability is also needed.

   410         *

   411         * @param[in] aSourceUri The URI of the database to copy.

   412         * @param[in] aTargetUri The URI of the new database location.

   413         *

   414         * @leave KErrNotSupported The protocol specified in the a URI is not

   415         *   supported.

   416         * @leave KErrArgument A URI is incorrect.

   417         * @leave KErrAlreadyExists There is already a database at the target URI.

   418         * @leave KErrInUse There is a write-lock on the database, e.g. some client

   419         *   is currently modifying the database.

   420         * @leave KErrNotFound There is no database at the source URI.

   421         */

   422         virtual void CopyDatabaseL(

   423             const TDesC& aSourceUri,

   424             const TDesC& aTargetUri

   425         ) = 0;

   426 

   427     protected:

   428 

   429         // C++ constructor.

   430         IMPORT_C CPosLmDatabaseManager();

   431 

   432     private:

   433 

   434         // Prohibit copy constructor

   435         CPosLmDatabaseManager( const CPosLmDatabaseManager& );

   436         // Prohibit assigment operator

   437         CPosLmDatabaseManager& operator= ( const CPosLmDatabaseManager& );

   438 

   439     private:

   440 

   441         // Implementation Uid

   442         TUid iDtorIdKey;

   443     };

   444 

   445 #endif      // CPOSLMDATABASEMANAGER_H

   446 

   447