diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/epos_cposlmdatabasemanager.h --- 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 +#include +#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& 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 + +