--- a/epoc32/include/mw/epos_cposlmdatabasemanager.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/epos_cposlmdatabasemanager.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,447 @@
-epos_cposlmdatabasemanager.h
+/*
+* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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
+
+