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