/*
* 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:   CPosLmDatabaseManagerPluginBase class
*
*/



#ifndef CPOSLMDATABASEMANAGERPLUGINBASE_H
#define CPOSLMDATABASEMANAGERPLUGINBASE_H

#include <e32base.h>
#include <badesca.h>
#include <EPos_TPosLmDatabaseEvent.h>
#include <EPos_TPosLmDatabaseSettings.h>
#include <EPos_HPosLmDatabaseInfo.h>

class CPosLmDbManPluginBaseExtension;
class RPosLandmarkServer;

/**
*  @internal
*
*  <b>This class is not used by client applications. 
*  It is reserved for future extensions.</b>
*/
/*
*  This class is the base class which has to be subclassed in order to write a
*  plug-in for database management for a specific protocol. It is reserved for
*  for future extensions.
*
*  @p CPosLmDatabaseManagerPluginBase contains functions for listing,
*  registering, unregistering, creating, deleting, copying landmark databases,
*  etc.
*
*  @lib eposlmdbmanlib.lib
*  @since S60 3.0
*/
class CPosLmDatabaseManagerPluginBase : public CBase
    {
    public:

        /*
        * Destructor.
        */
        IMPORT_C virtual ~CPosLmDatabaseManagerPluginBase();

    public:

        /*
        * Retrieves the type of media where a landmark database resides.
        *
        * This function does not validate the URI. If the URI is invalid, this
        * function will just return @p EMediaUnknown.
        *
        * @param[in] aDatabaseUri The URI of the database to check media for.
        * @return Type of storage media.
        */
        virtual TMediaType DatabaseMedia( const TDesC& aDatabaseUri ) = 0;

        /*
        * Retrieves the drive letter for the drive where a landmark database
        * resides.
        *
        * If the landmark database is remote or otherwise the drive letter is
        * not applicable, 0 is returned.
        *
        * This function does not validate the URI. If the URI is invalid, this
        * function will just return 0.
        *
        * @param[in] aDatabaseUri The URI of the database to check drive letter
        *   for.
        * @return The drive letter, or 0 if drive letter is not applicable.
        */
        virtual TChar DatabaseDrive( const TDesC& aDatabaseUri ) = 0;

        /*
        * Returns the protocol which the plug-in handles.
        *
        * The returned descriptor pointer is valid until the plug-in is
        * unloaded.
        *
        * @return Pointer to the protocol descriptor, e.g. "file"
        */
        virtual TPtrC Protocol() = 0;

        /*
        * Lists the URIs to all landmark databases handled by this
        * plug-in.
        *
        * The client takes ownership of the returned array.
        *
        * If no databases are found, an empty array is returned.
        *
        * This function requires @p ReadUserData capability.
        *
        * @return The list of database URIs.
        */
        virtual CDesCArray* ListDatabasesLC() = 0;

        /*
        * Lists information about each landmark database handled by this
        * plug-in.
        *
        * 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, the input array is not modified.
        *
        * This function requires @p ReadUserData capability.
        *
        * @param[out] aDatabaseInfoArray On return, contains information about
        *   the landmark databases.
        */
        virtual void ListDatabasesL(
            RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray
        ) = 0;

        /*
        * Registers a landmark database.
        *
        * The landmark database is then returned when listing landmark
        * databases.
        *
        * Some protocols like "file" does not allow registering of databases
        * and will leave with error code @p KErrNotSupported. To add a
        * database of such protocol, 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.
        *
        * @leave KErrNotSupported The protocol specified in the URI is not
        *   supported by this plug-in 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 will not be returned when listing
        * landmark databases.
        *
        * Some protocols like "file" does not allow unregistering of databases
        * and will leave with error code @p KErrNotSupported. To remove a
        * database of such protocol, 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 by this plug-in 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 this
        * plug-in.
        *
        * After this, the landmark databases will not be returned when listing
        * landmark databases.
        *
        * Some protocols like "file" does not allow unregistering of databases
        * and will leave with error code @p KErrNotSupported. To remove a
        * "file"-protocol database, the client must call @ref DeleteDatabaseL.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @leave KErrNotSupported This plug-in does not allow unregistering
        *   landmark databases.
        */
        virtual void UnregisterAllDatabasesL() = 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 by this plug-in.
        * @leave KErrNotFound The specified database is not found.
        */
        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 by this plug-in.
        * @leave KErrNotFound The specified database is not found.
        */
        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.
        *
        * 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 KErrArgument The URI is incorrect or the protocol specified in the
        *   URI is not supported by this plug-in.
        */
        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[in,out] aDatabaseInfo Information about the landmark database to
        *   create.
        *
        * @leave KErrNotSupported The protocol is not supported or the create
        *   operation is not supported by the protocol plug-in.
        * @leave KErrArgument The URI is incorrect or the protocol specified in the
        *   URI is not supported by this plug-in.
        * @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. The URI must specify the protocol which
        * is handled by this database manager plug-in.
        *
        * 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[in] aDatabaseUri The URI of the database to delete.
        *
        * @leave KErrNotSupported The protocol is not supported or the delete
        *   operation is not supported by the plug-in.
        * @leave KErrArgument The URI is incorrect or the protocol specified in the
        *   URI is not supported by this plug-in.
        * @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.
        * The target and source URIs must specify the protocol which is handled
        * by this database manager plug-in.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities. If the database is 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 operation is not supported by the plug-in.
        * @leave KErrArgument A URI is incorrect or the protocol specified in a
        *   URI is not supported by this plug-in.
        * @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 CPosLmDatabaseManagerPluginBase();

        /*
        * Creates the internals of the manager.
        *
        * This function must be called first in the manager's @b ConstructL()
        * method.
        *
        * @param[in] aConstructionParameters The construction parameters supplied
        *   in the factory call.
        */
        IMPORT_C void BaseConstructL( TAny* aConstructionParameters );

    protected:

        /*
        * Returns a reference to an open landmark server session.
        *
        * @return The server session.
        */
        IMPORT_C RPosLandmarkServer& Session() const;

    private:

        // Prohibit copy constructor
        CPosLmDatabaseManagerPluginBase(
            const CPosLmDatabaseManagerPluginBase& );
        // Prohibit assigment operator
        CPosLmDatabaseManagerPluginBase& operator=(
            const CPosLmDatabaseManagerPluginBase& );

    private:

        CPosLmDbManPluginBaseExtension* iExtension;
    };

#endif      // CPOSLMDATABASEMANAGERPLUGINBASE_H