williamr@2: /*
williamr@2: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:   CPosLmDatabaseManager class
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef CPOSLMDATABASEMANAGER_H
williamr@2: #define CPOSLMDATABASEMANAGER_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <badesca.h>
williamr@2: #include "EPos_TPosLmDatabaseEvent.h"
williamr@2: #include "EPos_TPosLmDatabaseSettings.h"
williamr@2: #include "EPos_HPosLmDatabaseInfo.h"
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: *  This class is used to manage landmark databases.
williamr@2: *
williamr@2: *  @p CPosLmDatabaseManager contains functions for listing registering,
williamr@2: *  unregistering, creating, deleting, copying landmark databases, etc.
williamr@2: *  It also has functions for managing the default landmark database. The
williamr@2: *  client can listen to events related to database management.
williamr@2: *
williamr@2: *  A database is local if it resides in the phone or in some device which
williamr@2: *  is mapped to the phones file system. If a database is not local, it is
williamr@2: *  remote.
williamr@2: *
williamr@2: *  The client refers to a database by URI. The URI consists of a protocol
williamr@2: *  specifier and the database location: "protocol://location". If the
williamr@2: *  client does not specify a protocol, "file://" is assumed.
williamr@2: *
williamr@2: *  For local landmark databases, the URI consists of the drive and the
williamr@2: *  database file name, e.g. "c:landmarks.ldb". The path cannot be specified
williamr@2: *  by the client. The extension of the database file name must be "ldb".
williamr@2: *  If a path is included or if the file name extension is not .ldb",
williamr@2: *  the client receives the error code @p KErrArgument. For local landmark
williamr@2: *  databases, the client receives the error code @p KErrBadName if the
williamr@2: *  file name is invalid and @p KErrNotReady if the drive specified in the URI
williamr@2: *  does not exist.
williamr@2: *
williamr@2: *  If the client specifies a local database URI and does not specify the drive
williamr@2: *  letter, e.g. "landmarks.ldb", default database drive is assumed.
williamr@2: *
williamr@2: *  Local databases are created by calling @ref CreateDatabaseL. "Bookmarks"
williamr@2: *  to remote databases are created by calling @ref RegisterDatabaseL. After
williamr@2: *  this they are listed by the database manager.
williamr@2: *
williamr@2: *  If @ref CPosLmDatabaseManager is used, the client must call the global
williamr@2: *  function @ref ReleaseLandmarkResources before terminating, in order to
williamr@2: *  release all used landmark resources, otherwise the client may receive
williamr@2: *  an ALLOC panic.
williamr@2: *
williamr@2: *  @lib eposlmdbmanlib.lib
williamr@2: *  @since S60 3.0
williamr@2: */
williamr@2: class CPosLmDatabaseManager : public CBase
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         */
williamr@2:         IMPORT_C static CPosLmDatabaseManager* NewL();
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CPosLmDatabaseManager();
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieves the URI of the default landmark database.
williamr@2:         *
williamr@2:         * The default landmark database is the one which is opened when calling
williamr@2:         * @p CPosLandmarkDatabase::OpenL without any parameters.
williamr@2:         *
williamr@2:         * Only "file"-protocol databases can be set as default.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @return The URI of the default landmark database. The client takes
williamr@2:         *   ownership of the descriptor object.
williamr@2:         */
williamr@2:         virtual HBufC* DefaultDatabaseUriLC() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Sets a landmark database as default.
williamr@2:         *
williamr@2:         * This database is opened the next time
williamr@2:         * @p CPosLandmarkDatabase::OpenL() called without parameters.
williamr@2:         *
williamr@2:         * To move the current default database to another drive, first use
williamr@2:         * @ref CopyDatabaseL to copy the database to the new drive, then use
williamr@2:         * @ref SetDefaultDatabaseUriL to set the new database as default and
williamr@2:         * finally, use @ref DeleteDatabaseL if the old default database should
williamr@2:         * be deleted.
williamr@2:         *
williamr@2:         * Only "file"-protocol databases can be set as default.
williamr@2:         *
williamr@2:         * This function requires @p WriteDeviceData capability.
williamr@2:         *
williamr@2:         * @param[in] aDatabaseUri The URI of the database which should be set as
williamr@2:         *   default.
williamr@2:         * @leave KErrNotSupported The protocol specified something else
williamr@2:         *   than "file://" as protocol in the URI.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         * @leave KErrNotFound The landmark database which should be set as default
williamr@2:         *   does not exist.
williamr@2:         */
williamr@2:         virtual void SetDefaultDatabaseUriL( const TDesC& aDatabaseUri ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Listens for database management events.
williamr@2:         *
williamr@2:         * This function is asynchronous and it completes the request
williamr@2:         * status when an event occurs. At this time, the client can read
williamr@2:         * event information from the retrieved event object.
williamr@2:         *
williamr@2:         * Event listening can be canceled by calling
williamr@2:         * @ref CancelNotifyDatabaseEvent.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @param[out] aEvent Contains the event information when an event
williamr@2:         *   occurs (request completes).
williamr@2:         * @param[out] aStatus Is completed with @p KErrNone if an event
williamr@2:         *   occurs or an error code if some error is encountered.
williamr@2:         */
williamr@2:         virtual void NotifyDatabaseEvent(
williamr@2:             TPosLmDatabaseEvent& aEvent,
williamr@2:             TRequestStatus& aStatus
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Cancels a call to @ref NotifyDatabaseEvent.
williamr@2:         *
williamr@2:         * @return @p KErrNone if the request was successfully cancelled,
williamr@2:         *   otherwise a system wide error code.
williamr@2:         */
williamr@2:         virtual TInt CancelNotifyDatabaseEvent() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieves the database URI associated with the last event.
williamr@2:         *
williamr@2:         * Some events, e.g. @p EPosLmDbDatabaseRegistered and
williamr@2:         * @p EPosLmDbDatabaseUnregistered, refer to a specific database. The
williamr@2:         * URI of the database can be retrieved through this function.
williamr@2:         *
williamr@2:         * If the URI should be retrieved, this function must be called before
williamr@2:         * @ref NotifyDatabaseEvent is called again to listen for the next
williamr@2:         * event.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @return The database URI associated with the event. The client takes
williamr@2:         *   ownership of the descriptor object.
williamr@2:         * @leave KErrNotFound There is no database URI associated with the event
williamr@2:         *   or, the database URI has been discarded because the client has called
williamr@2:         *   @ref NotifyDatabaseEvent again.
williamr@2:         */
williamr@2:         virtual HBufC* DatabaseUriFromLastEventLC() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Lists the URIs to all landmark databases known by the Landmarks
williamr@2:         * system.
williamr@2:         *
williamr@2:         * The client can specify a protocol string as input to this function.
williamr@2:         * The function then only returns a list of the databases which
williamr@2:         * are accessed through this protocol.
williamr@2:         *
williamr@2:         * The client takes ownership of the returned array.
williamr@2:         *
williamr@2:         * If no databases are found, an empty array is returned.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @param[in] aProtocol The protocol for which database URIs should be
williamr@2:         *   listed. If no protocol is specified, i.e. if an empty string is
williamr@2:         *   specified, all known database URIs are listed.
williamr@2:         * @return The list of database URIs.
williamr@2:         * @leave KErrNotSupported The protocol is not supported in the platform.
williamr@2:         */
williamr@2:         virtual CDesCArray* ListDatabasesLC( const TDesC& aProtocol = KNullDesC ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Lists information about each landmark database known by the Landmarks
williamr@2:         * system.
williamr@2:         *
williamr@2:         * The client can specify a protocol string as input to this function.
williamr@2:         * The function then only returns information about the databases
williamr@2:         * which are accessed through this protocol.
williamr@2:         *
williamr@2:         * The client specifies an array which is populated by this function.
williamr@2:         * The client takes ownership of all information objects in the array.
williamr@2:         *
williamr@2:         * If no databases are found, an empty array is returned.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @param[out] aDatabaseInfoArray On return, contains information about
williamr@2:         *   the landmark databases. Any objects which are in the array when
williamr@2:         *   it is passed to this function are not removed.
williamr@2:         * @param[in] aProtocol The protocol for which database URIs should be
williamr@2:         *   listed. If no protocol is specified, i.e. if an empty string is
williamr@2:         *   specified, all known database URIs are listed.
williamr@2:         * @leave KErrNotSupported The protocol is not supported in the platform.
williamr@2:         */
williamr@2:         virtual void ListDatabasesL(
williamr@2:             RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,
williamr@2:             const TDesC& aProtocol = KNullDesC
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Registers a landmark database.
williamr@2:         *
williamr@2:         * The landmark database is then returned when listing landmark
williamr@2:         * databases.
williamr@2:         *
williamr@2:         * For local landmark databases, this function leaves with error code
williamr@2:         * @p KErrNotSupported. To add a local database, the client must call
williamr@2:         * @ref CreateDatabaseL.
williamr@2:         *
williamr@2:         * The client supplies an information object containing the URI of the
williamr@2:         * database to register. The information object can also contain
williamr@2:         * database settings, e.g. a display name for the database.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities.
williamr@2:         *
williamr@2:         * @param[in,out] aDatabaseInfo Information about the landmark database to
williamr@2:         *   register. The information object will be updated with
williamr@2:         *   media type and drive information.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported in the platform or the protocol does not allow
williamr@2:         *   registering landmark databases.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         * @leave KErrAlreadyExists The database already exists in the registry.
williamr@2:         */
williamr@2:         virtual void RegisterDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Unregisters a landmark database.
williamr@2:         *
williamr@2:         * After this, the landmark database is not returned when listing
williamr@2:         * landmark databases.
williamr@2:         *
williamr@2:         * For local landmark databases, this function leaves with error code
williamr@2:         * @p KErrNotSupported. To remove a local database, the client must call
williamr@2:         * @ref DeleteDatabaseL.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities.
williamr@2:         *
williamr@2:         * @param[in] aDatabaseUri The URI of the database to register.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported in the platform or the protocol does not allow
williamr@2:         *   unregistering landmark databases.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         */
williamr@2:         virtual void UnregisterDatabaseL( const TDesC& aDatabaseUri ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Unregisters all landmark database which are accessed through a
williamr@2:         * certain protocol.
williamr@2:         *
williamr@2:         * After this, the landmark databases are not be returned when listing
williamr@2:         * landmark databases.
williamr@2:         *
williamr@2:         * For local landmark databases, this function leaves with error code
williamr@2:         * @p KErrNotSupported. To remove a local database, the client must call
williamr@2:         * @ref DeleteDatabaseL.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities.
williamr@2:         *
williamr@2:         * @param[in] aProtocol The protocol to unregister all databases for.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol is not supported in the platform
williamr@2:         *   or the protocol does not allow unregistering landmark databases.
williamr@2:         * @leave KErrArgument The protocol is an empty string.
williamr@2:         */
williamr@2:         virtual void UnregisterAllDatabasesL( const TDesC& aProtocol ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Modifies the settings for a landmark database.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities.
williamr@2:         *
williamr@2:         * @param[in] aDatabaseUri The URI of the database to modify settings for.
williamr@2:         * @param[in] aDatabaseSettings The new settings for the database.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported in the platform.
williamr@2:         * @leave KErrNotFound The specified database is not found.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         */
williamr@2:         virtual void ModifyDatabaseSettingsL(
williamr@2:             const TDesC& aDatabaseUri,
williamr@2:             const TPosLmDatabaseSettings& aDatabaseSettings
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Retrieve information about a landmark database.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability.
williamr@2:         *
williamr@2:         * @param[in,out] aDatabaseInfo An information object containing the URI of the
williamr@2:         *   landmark database. On return, the object contains information about
williamr@2:         *   the landmark database, including any database settings.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported in the platform.
williamr@2:         * @leave KErrNotFound The specified database is not found.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         */
williamr@2:         virtual void GetDatabaseInfoL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Checks if the specified landmark database exists.
williamr@2:         *
williamr@2:         * The database to check is specified by passing a URI to this function.
williamr@2:         * URI construction is described in the class description for
williamr@2:         * @ref CPosLmDatabaseManager. The URI must point to a database which is
williamr@2:         * handled by this database manager, i.e. not a remote location.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData capability. If the database is
williamr@2:         * remote, @p NetworkServices capability is also needed.
williamr@2:         *
williamr@2:         * @param[in] aDatabaseUri The URI of the database which should be checked
williamr@2:         *   for existence.
williamr@2:         * @return @p ETrue if the database exists, otherwise @p EFalse.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         */
williamr@2:         virtual TBool DatabaseExistsL( const TDesC&  aDatabaseUri ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Creates a landmark database.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities. If the database is remote, @p NetworkServices
williamr@2:         * capability is also needed.
williamr@2:         *
williamr@2:         * @param aDatabaseInfo Information about the landmark database to
williamr@2:         *   create. The information object will be updated with
williamr@2:         *   media type and drive information.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         * @leave KErrAlreadyExists There is already a database at this URI.
williamr@2:         */
williamr@2:         virtual void CreateDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Deletes a landmark database.
williamr@2:         *
williamr@2:         * The database to delete is specified by passing a URI to this
williamr@2:         * function. URI construction is described in the class description for
williamr@2:         * @ref CPosLmDatabaseManager.
williamr@2:         *
williamr@2:         * If the specified database does not exist, the call is ignored.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities. If the database is remote, @p NetworkServices
williamr@2:         * capability is also needed.
williamr@2:         *
williamr@2:         * @param aDatabaseUri The URI of the database to delete.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the URI is not
williamr@2:         *   supported.
williamr@2:         * @leave KErrArgument The URI is incorrect.
williamr@2:         * @leave KErrInUse The database is in use by some client.
williamr@2:         * @leave KErrAccessDenied The database is read-only.
williamr@2:         */
williamr@2:         virtual void DeleteDatabaseL( const TDesC& aDatabaseUri ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Copies a landmark database to a new location.
williamr@2:         *
williamr@2:         * Database locations are specified as URIs. URI construction is
williamr@2:         * described in the class description for @ref CPosLmDatabaseManager.
williamr@2:         * Target URI protocol must be the same as source URI protocol.
williamr@2:         *
williamr@2:         * This function requires @p ReadUserData and @p WriteUserData
williamr@2:         * capabilities. If the databases are remote, @p NetworkServices
williamr@2:         * capability is also needed.
williamr@2:         *
williamr@2:         * @param[in] aSourceUri The URI of the database to copy.
williamr@2:         * @param[in] aTargetUri The URI of the new database location.
williamr@2:         *
williamr@2:         * @leave KErrNotSupported The protocol specified in the a URI is not
williamr@2:         *   supported.
williamr@2:         * @leave KErrArgument A URI is incorrect.
williamr@2:         * @leave KErrAlreadyExists There is already a database at the target URI.
williamr@2:         * @leave KErrInUse There is a write-lock on the database, e.g. some client
williamr@2:         *   is currently modifying the database.
williamr@2:         * @leave KErrNotFound There is no database at the source URI.
williamr@2:         */
williamr@2:         virtual void CopyDatabaseL(
williamr@2:             const TDesC& aSourceUri,
williamr@2:             const TDesC& aTargetUri
williamr@2:         ) = 0;
williamr@2: 
williamr@2:     protected:
williamr@2: 
williamr@2:         // C++ constructor.
williamr@2:         IMPORT_C CPosLmDatabaseManager();
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // Prohibit copy constructor
williamr@2:         CPosLmDatabaseManager( const CPosLmDatabaseManager& );
williamr@2:         // Prohibit assigment operator
williamr@2:         CPosLmDatabaseManager& operator= ( const CPosLmDatabaseManager& );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // Implementation Uid
williamr@2:         TUid iDtorIdKey;
williamr@2:     };
williamr@2: 
williamr@2: #endif      // CPOSLMDATABASEMANAGER_H
williamr@2: 
williamr@2: