/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   CPosLmDatabaseManager class

*

*/

#ifndef CPOSLMDATABASEMANAGER_H

#define CPOSLMDATABASEMANAGER_H

#include <e32base.h>

#include <badesca.h>

#include "EPos_TPosLmDatabaseEvent.h"

#include "EPos_TPosLmDatabaseSettings.h"

#include "EPos_HPosLmDatabaseInfo.h"

/**

*  This class is used to manage landmark databases.

*

*  @p CPosLmDatabaseManager contains functions for listing registering,

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

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

*  client can listen to events related to database management.

*

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

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

*  remote.

*

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

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

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

*

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

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

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

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

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

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

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

*  does not exist.

*

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

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

*

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

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

*  this they are listed by the database manager.

*

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

*  function @ref ReleaseLandmarkResources before terminating, in order to

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

*  an ALLOC panic.

*

*  @lib eposlmdbmanlib.lib

*  @since S60 3.0

*/

class CPosLmDatabaseManager : public CBase

    {

    public:

        /**

        * Two-phased constructor.

        *

        * This function requires @p ReadUserData capability.

        */

        IMPORT_C static CPosLmDatabaseManager* NewL();

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CPosLmDatabaseManager();

    public:

        /**

        * Retrieves the URI of the default landmark database.

        *

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

        * @p CPosLandmarkDatabase::OpenL without any parameters.

        *

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

        *

        * This function requires @p ReadUserData capability.

        *

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

        *   ownership of the descriptor object.

        */

        virtual HBufC* DefaultDatabaseUriLC() = 0;

        /**

        * Sets a landmark database as default.

        *

        * This database is opened the next time

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

        *

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

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

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

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

        * be deleted.

        *

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

        *

        * This function requires @p WriteDeviceData capability.

        *

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

        *   default.

        * @leave KErrNotSupported The protocol specified something else

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

        * @leave KErrArgument The URI is incorrect.

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

        *   does not exist.

        */

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

        /**

        * Listens for database management events.

        *

        * This function is asynchronous and it completes the request

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

        * event information from the retrieved event object.

        *

        * Event listening can be canceled by calling

        * @ref CancelNotifyDatabaseEvent.

        *

        * This function requires @p ReadUserData capability.

        *

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

        *   occurs (request completes).

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

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

        */

        virtual void NotifyDatabaseEvent(

            TPosLmDatabaseEvent& aEvent,

            TRequestStatus& aStatus

        ) = 0;

        /**

        * Cancels a call to @ref NotifyDatabaseEvent.

        *

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

        *   otherwise a system wide error code.

        */

        virtual TInt CancelNotifyDatabaseEvent() = 0;

        /**

        * Retrieves the database URI associated with the last event.

        *

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

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

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

        *

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

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

        * event.

        *

        * This function requires @p ReadUserData capability.

        *

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

        *   ownership of the descriptor object.

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

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

        *   @ref NotifyDatabaseEvent again.

        */

        virtual HBufC* DatabaseUriFromLastEventLC() = 0;

        /**

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

        * system.

        *

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

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

        * are accessed through this protocol.

        *

        * The client takes ownership of the returned array.

        *

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

        *

        * This function requires @p ReadUserData capability.

        *

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

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

        *   specified, all known database URIs are listed.

        * @return The list of database URIs.

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

        */

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

        /**

        * Lists information about each landmark database known by the Landmarks

        * system.

        *

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

        * The function then only returns information about the databases

        * which are accessed through this protocol.

        *

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

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

        *

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

        *

        * This function requires @p ReadUserData capability.

        *

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

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

        *   it is passed to this function are not removed.

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

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

        *   specified, all known database URIs are listed.

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

        */

        virtual void ListDatabasesL(

            RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,

            const TDesC& aProtocol = KNullDesC

        ) = 0;

        /**

        * Registers a landmark database.

        *

        * The landmark database is then returned when listing landmark

        * databases.

        *

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

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

        * @ref CreateDatabaseL.

        *

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

        * database to register. The information object can also contain

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

        *

        * This function requires @p ReadUserData and @p WriteUserData

        * capabilities.

        *

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

        *   register. The information object will be updated with

        *   media type and drive information.

        *

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

        *   supported in the platform or the protocol does not allow

        *   registering landmark databases.

        * @leave KErrArgument The URI is incorrect.

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

        */

        virtual void RegisterDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

        /**

        * Unregisters a landmark database.

        *

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

        * landmark databases.

        *

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

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

        * @ref DeleteDatabaseL.

        *

        * This function requires @p ReadUserData and @p WriteUserData

        * capabilities.

        *

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

        *

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

        *   supported in the platform or the protocol does not allow

        *   unregistering landmark databases.

        * @leave KErrArgument The URI is incorrect.

        */

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

        /**

        * Unregisters all landmark database which are accessed through a

        * certain protocol.

        *

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

        * landmark databases.

        *

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

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

        * @ref DeleteDatabaseL.

        *

        * This function requires @p ReadUserData and @p WriteUserData

        * capabilities.

        *

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

        *

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

        *   or the protocol does not allow unregistering landmark databases.

        * @leave KErrArgument The protocol is an empty string.

        */

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

        /**

        * Modifies the settings for a landmark database.

        *

        * This function requires @p ReadUserData and @p WriteUserData

        * capabilities.

        *

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

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

        *

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

        *   supported in the platform.

        * @leave KErrNotFound The specified database is not found.

        * @leave KErrArgument The URI is incorrect.

        */

        virtual void ModifyDatabaseSettingsL(

            const TDesC& aDatabaseUri,

            const TPosLmDatabaseSettings& aDatabaseSettings

        ) = 0;

        /**

        * Retrieve information about a landmark database.

        *

        * This function requires @p ReadUserData capability.

        *

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

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

        *   the landmark database, including any database settings.

        *

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

        *   supported in the platform.

        * @leave KErrNotFound The specified database is not found.

        * @leave KErrArgument The URI is incorrect.

        */

        virtual void GetDatabaseInfoL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

        /**

        * Checks if the specified landmark database exists.

        *

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

        * URI construction is described in the class description for

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

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

        *

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

        * remote, @p NetworkServices capability is also needed.

        *

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

        *   for existence.

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

        *

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

        *   supported.

        * @leave KErrArgument The URI is incorrect.

        */

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

        /**

        * Creates a landmark database.

        *

        * This function requires @p ReadUserData and @p WriteUserData

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

        * capability is also needed.

        *

        * @param aDatabaseInfo Information about the landmark database to

        *   create. The information object will be updated with

        *   media type and drive information.

        *

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

        *   supported.

        * @leave KErrArgument The URI is incorrect.

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

        */

        virtual void CreateDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0;

        /**

        * Deletes a landmark database.

        *

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

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

        * @ref CPosLmDatabaseManager.

        *

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

        *

        * This function requires @p ReadUserData and @p WriteUserData

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

        * capability is also needed.

        *

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

        *

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

        *   supported.

        * @leave KErrArgument The URI is incorrect.

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

        * @leave KErrAccessDenied The database is read-only.

        */

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

        /**

        * Copies a landmark database to a new location.

        *

        * Database locations are specified as URIs. URI construction is

        * described in the class description for @ref CPosLmDatabaseManager.

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

        *

        * This function requires @p ReadUserData and @p WriteUserData

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

        * capability is also needed.

        *

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

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

        *

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

        *   supported.

        * @leave KErrArgument A URI is incorrect.

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

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

        *   is currently modifying the database.

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

        */

        virtual void CopyDatabaseL(

            const TDesC& aSourceUri,

            const TDesC& aTargetUri

        ) = 0;

    protected:

        // C++ constructor.

        IMPORT_C CPosLmDatabaseManager();

    private:

        // Prohibit copy constructor

        CPosLmDatabaseManager( const CPosLmDatabaseManager& );

        // Prohibit assigment operator

        CPosLmDatabaseManager& operator= ( const CPosLmDatabaseManager& );

    private:

        // Implementation Uid

        TUid iDtorIdKey;

    };

#endif      // CPOSLMDATABASEMANAGER_H