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