diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/EPos_CPosLmDatabaseManagerPluginBase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/EPos_CPosLmDatabaseManagerPluginBase.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,364 @@ +/* +* 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 +#include +#include +#include +#include + +class CPosLmDbManPluginBaseExtension; +class RPosLandmarkServer; + +/** +* @internal +* +* This class is not used by client applications. +* It is reserved for future extensions. +*/ +/* +* 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& 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 + +