CPosLmDatabaseManager Class Reference

API published in: S60 3rd Ed

Link against: eposlmdbmanlib.lib

Capability Information

Required Capabilities

None

Exceptions

The capability ReadUserData is required in:

CPosLmDatabaseManager::NewL();

CPosLmDatabaseManager::DefaultDatabaseUriLC();

CPosLmDatabaseManager::NotifyDatabaseEvent( TPosLmDatabaseEvent & aEvent, TRequestStatus & aStatus );

CPosLmDatabaseManager::DatabaseUriFromLastEventLC();

CPosLmDatabaseManager::ListDatabasesLC( const TDesC & aProtocol = KNullDesC );

CPosLmDatabaseManager::ListDatabasesL( RPointerArray< HPosLmDatabaseInfo > & aDatabaseInfoArray, const TDesC & aProtocol = KNullDesC );

CPosLmDatabaseManager::RegisterDatabaseL( HPosLmDatabaseInfo & aDatabaseInfo );

CPosLmDatabaseManager::UnregisterDatabaseL( const TDesC & aDatabaseUri );

CPosLmDatabaseManager::UnregisterAllDatabasesL( const TDesC & aProtocol );

CPosLmDatabaseManager::ModifyDatabaseSettingsL( const TDesC & aDatabaseUri, const TPosLmDatabaseSettings & aDatabaseSettings );

CPosLmDatabaseManager::GetDatabaseInfoL( HPosLmDatabaseInfo & aDatabaseInfo );

CPosLmDatabaseManager::DatabaseExistsL( const TDesC & aDatabaseUri );

CPosLmDatabaseManager::CreateDatabaseL( HPosLmDatabaseInfo & aDatabaseInfo );

CPosLmDatabaseManager::DeleteDatabaseL( const TDesC & aDatabaseUri );

CPosLmDatabaseManager::CopyDatabaseL( const TDesC & aSourceUri, const TDesC & aTargetUri );

The capability WriteUserData is required in:

CPosLmDatabaseManager::RegisterDatabaseL( HPosLmDatabaseInfo & aDatabaseInfo );

CPosLmDatabaseManager::UnregisterDatabaseL( const TDesC & aDatabaseUri );

CPosLmDatabaseManager::UnregisterAllDatabasesL( const TDesC & aProtocol );

CPosLmDatabaseManager::ModifyDatabaseSettingsL( const TDesC & aDatabaseUri, const TPosLmDatabaseSettings & aDatabaseSettings );

CPosLmDatabaseManager::CreateDatabaseL( HPosLmDatabaseInfo & aDatabaseInfo );

CPosLmDatabaseManager::DeleteDatabaseL( const TDesC & aDatabaseUri );

CPosLmDatabaseManager::CopyDatabaseL( const TDesC & aSourceUri, const TDesC & aTargetUri );

The capability WriteDeviceData is required in:

CPosLmDatabaseManager::SetDefaultDatabaseUriL( const TDesC & aDatabaseUri );

The capability NetworkServices is required in:

CPosLmDatabaseManager::DatabaseExistsL( const TDesC & aDatabaseUri ); When database URI refers to remote database.

CPosLmDatabaseManager::CreateDatabaseL( HPosLmDatabaseInfo & aDatabaseInfo ); When database URI refers to remote database.

CPosLmDatabaseManager::DeleteDatabaseL( const TDesC & aDatabaseUri ); When database URI refers to remote database.

CPosLmDatabaseManager::CopyDatabaseL( const TDesC & aSourceUri, const TDesC & aTargetUri ); When any of database URIs refers to remote database.

Other Information

The capability NetworkServices is required to work with remote databases.

#include <epos_cposlmdatabasemanager.h>

Detailed Description

This class is used to manage landmark databases.

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 KErrArgument. For local landmark databases, the client receives the error code KErrBadName if the file name is invalid and 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 CreateDatabaseL. "Bookmarks" to remote databases are created by calling RegisterDatabaseL. After this they are listed by the database manager.

If CPosLmDatabaseManager is used, the client must call the global function ReleaseLandmarkResources before terminating, in order to release all used landmark resources, otherwise the client may receive an ALLOC panic.


Public Member Functions
virtual IMPORT_C	~CPosLmDatabaseManager ()
	Destructor.
virtual HBufC *	DefaultDatabaseUriLC ()=0
	Retrieves the URI of the default landmark database.
virtual void	SetDefaultDatabaseUriL (const TDesC &aDatabaseUri)=0
	Sets a landmark database as default.
virtual void	NotifyDatabaseEvent (TPosLmDatabaseEvent &aEvent, TRequestStatus &aStatus)=0
	Listens for database management events.
virtual TInt	CancelNotifyDatabaseEvent ()=0
	Cancels a call to NotifyDatabaseEvent.
virtual HBufC *	DatabaseUriFromLastEventLC ()=0
	Retrieves the database URI associated with the last event.
virtual CDesCArray *	ListDatabasesLC (const TDesC &aProtocol=KNullDesC)=0
	Lists the URIs to all landmark databases known by the Landmarks system.
virtual void	ListDatabasesL (RPointerArray< HPosLmDatabaseInfo > &aDatabaseInfoArray, const TDesC &aProtocol=KNullDesC)=0
	Lists information about each landmark database known by the Landmarks system.
virtual void	RegisterDatabaseL (HPosLmDatabaseInfo &aDatabaseInfo)=0
	Registers a landmark database.
virtual void	UnregisterDatabaseL (const TDesC &aDatabaseUri)=0
	Unregisters a landmark database.
virtual void	UnregisterAllDatabasesL (const TDesC &aProtocol)=0
	Unregisters all landmark database which are accessed through a certain protocol.
virtual void	ModifyDatabaseSettingsL (const TDesC &aDatabaseUri, const TPosLmDatabaseSettings &aDatabaseSettings)=0
	Modifies the settings for a landmark database.
virtual void	GetDatabaseInfoL (HPosLmDatabaseInfo &aDatabaseInfo)=0
	Retrieve information about a landmark database.
virtual TBool	DatabaseExistsL (const TDesC &aDatabaseUri)=0
	Checks if the specified landmark database exists.
virtual void	CreateDatabaseL (HPosLmDatabaseInfo &aDatabaseInfo)=0
	Creates a landmark database.
virtual void	DeleteDatabaseL (const TDesC &aDatabaseUri)=0
	Deletes a landmark database.
virtual void	CopyDatabaseL (const TDesC &aSourceUri, const TDesC &aTargetUri)=0
	Copies a landmark database to a new location.
Static Public Member Functions
static IMPORT_C CPosLmDatabaseManager *	NewL ()
	Two-phased constructor.
Protected Member Functions
IMPORT_C	CPosLmDatabaseManager ()

Constructor & Destructor Documentation

virtual IMPORT_C CPosLmDatabaseManager::~CPosLmDatabaseManager ( ) [virtual]

Destructor.

IMPORT_C CPosLmDatabaseManager::CPosLmDatabaseManager ( ) [protected]

Member Function Documentation

virtual TInt CPosLmDatabaseManager::CancelNotifyDatabaseEvent ( ) [pure virtual]

Cancels a call to NotifyDatabaseEvent.

Returns:: KErrNone if the request was successfully cancelled, otherwise a system wide error code.

virtual void CPosLmDatabaseManager::CopyDatabaseL	(	const TDesC &	aSourceUri,
		const TDesC &	aTargetUri
	)	`[pure virtual]`

Copies a landmark database to a new location.

Database locations are specified as URIs. URI construction is described in the class description for CPosLmDatabaseManager. Target URI protocol must be the same as source URI protocol.

This function requires ReadUserData and WriteUserData capabilities. If the databases are remote, NetworkServices capability is also needed.

Parameters:

`[in]`	aSourceUri	The URI of the database to copy.
`[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 CPosLmDatabaseManager::CreateDatabaseL ( HPosLmDatabaseInfo & aDatabaseInfo ) [pure virtual]

Creates a landmark database.

This function requires ReadUserData and WriteUserData capabilities. If the database is remote, NetworkServices capability is also needed.

Parameters:

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 TBool CPosLmDatabaseManager::DatabaseExistsL ( const TDesC & aDatabaseUri ) [pure virtual]

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 CPosLmDatabaseManager. The URI must point to a database which is handled by this database manager, i.e. not a remote location.

This function requires ReadUserData capability. If the database is remote, NetworkServices capability is also needed.

Parameters:

[in] aDatabaseUri The URI of the database which should be checked for existence.

Returns:: ETrue if the database exists, otherwise EFalse.

Leave:: KErrNotSupported The protocol specified in the URI is not supported.

Leave:: KErrArgument The URI is incorrect.

virtual HBufC* CPosLmDatabaseManager::DatabaseUriFromLastEventLC ( ) [pure virtual]

Retrieves the database URI associated with the last event.

Some events, e.g. EPosLmDbDatabaseRegistered and 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 NotifyDatabaseEvent is called again to listen for the next event.

This function requires ReadUserData capability.

Returns:: 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 NotifyDatabaseEvent again.

virtual HBufC* CPosLmDatabaseManager::DefaultDatabaseUriLC ( ) [pure virtual]

Retrieves the URI of the default landmark database.

The default landmark database is the one which is opened when calling CPosLandmarkDatabase::OpenL without any parameters.

Only "file"-protocol databases can be set as default.

This function requires ReadUserData capability.

Returns:: The URI of the default landmark database. The client takes ownership of the descriptor object.

virtual void CPosLmDatabaseManager::DeleteDatabaseL ( const TDesC & aDatabaseUri ) [pure virtual]

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 CPosLmDatabaseManager.

If the specified database does not exist, the call is ignored.

This function requires ReadUserData and WriteUserData capabilities. If the database is remote, NetworkServices capability is also needed.

Parameters:

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 CPosLmDatabaseManager::GetDatabaseInfoL ( HPosLmDatabaseInfo & aDatabaseInfo ) [pure virtual]

Retrieve information about a landmark database.

This function requires ReadUserData capability.

Parameters:

[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 CPosLmDatabaseManager::ListDatabasesL	(	RPointerArray< HPosLmDatabaseInfo > &	aDatabaseInfoArray,
		const TDesC &	aProtocol = `KNullDesC`
	)	`[pure virtual]`

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 ReadUserData capability.

Parameters:

`[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.
`[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 CDesCArray* CPosLmDatabaseManager::ListDatabasesLC ( const TDesC & aProtocol = KNullDesC ) [pure virtual]

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 ReadUserData capability.

Parameters:

[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.

Returns:: The list of database URIs.

Leave:: KErrNotSupported The protocol is not supported in the platform.

virtual void CPosLmDatabaseManager::ModifyDatabaseSettingsL	(	const TDesC &	aDatabaseUri,
		const TPosLmDatabaseSettings &	aDatabaseSettings
	)	`[pure virtual]`

Modifies the settings for a landmark database.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

`[in]`	aDatabaseUri	The URI of the database to modify settings for.
`[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.

static IMPORT_C CPosLmDatabaseManager* CPosLmDatabaseManager::NewL ( ) [static]

Two-phased constructor.

This function requires ReadUserData capability.

virtual void CPosLmDatabaseManager::NotifyDatabaseEvent	(	TPosLmDatabaseEvent &	aEvent,
		TRequestStatus &	aStatus
	)	`[pure virtual]`

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 CancelNotifyDatabaseEvent.

This function requires ReadUserData capability.

Parameters:

`[out]`	aEvent	Contains the event information when an event occurs (request completes).
`[out]`	aStatus	Is completed with `KErrNone` if an event occurs or an error code if some error is encountered.

virtual void CPosLmDatabaseManager::RegisterDatabaseL ( HPosLmDatabaseInfo & aDatabaseInfo ) [pure virtual]

Registers a landmark database.

The landmark database is then returned when listing landmark databases.

For local landmark databases, this function leaves with error code KErrNotSupported. To add a local database, the client must call 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 ReadUserData and WriteUserData capabilities.

Parameters:

[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 CPosLmDatabaseManager::SetDefaultDatabaseUriL ( const TDesC & aDatabaseUri ) [pure virtual]

Sets a landmark database as default.

This database is opened the next time CPosLandmarkDatabase::OpenL() called without parameters.

To move the current default database to another drive, first use CopyDatabaseL to copy the database to the new drive, then use SetDefaultDatabaseUriL to set the new database as default and finally, use DeleteDatabaseL if the old default database should be deleted.

Only "file"-protocol databases can be set as default.

This function requires WriteDeviceData capability.

Parameters:

[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 CPosLmDatabaseManager::UnregisterAllDatabasesL ( const TDesC & aProtocol ) [pure virtual]

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 KErrNotSupported. To remove a local database, the client must call DeleteDatabaseL.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

[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 CPosLmDatabaseManager::UnregisterDatabaseL ( const TDesC & aDatabaseUri ) [pure virtual]

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 KErrNotSupported. To remove a local database, the client must call DeleteDatabaseL.

This function requires ReadUserData and WriteUserData capabilities.

Parameters:

[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.

The documentation for this class was generated from the following file:

epos_cposlmdatabasemanager.h

CPosLmDatabaseManager Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation