Collapse all Symbian^3 Product Developer Library

CPosLmDatabaseManager Class Reference

class CPosLmDatabaseManager : public CBase

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.

eposlmdbmanlib.lib

Since: S60 3.0

Inherits from

CPosLmDatabaseManager
- CBase

Public Member Functions
	~CPosLmDatabaseManager()
TInt	CancelNotifyDatabaseEvent()
void	CopyDatabaseL(const TDesC &, const TDesC &)
void	CreateDatabaseL(HPosLmDatabaseInfo &)
TBool	DatabaseExistsL(const TDesC &)
HBufC *	DatabaseUriFromLastEventLC()
HBufC *	DefaultDatabaseUriLC()
void	DeleteDatabaseL(const TDesC &)
void	GetDatabaseInfoL(HPosLmDatabaseInfo &)
void	ListDatabasesL(RPointerArray< HPosLmDatabaseInfo > &, const TDesC &)
CDesCArray *	ListDatabasesLC(const TDesC &)
void	ModifyDatabaseSettingsL(const TDesC &, const TPosLmDatabaseSettings &)
IMPORT_C CPosLmDatabaseManager *	NewL()
void	NotifyDatabaseEvent(TPosLmDatabaseEvent &, TRequestStatus &)
void	RegisterDatabaseL(HPosLmDatabaseInfo &)
void	SetDefaultDatabaseUriL(const TDesC &)
void	UnregisterAllDatabasesL(const TDesC &)
void	UnregisterDatabaseL(const TDesC &)

Protected Member Functions
	CPosLmDatabaseManager()

Private Member Functions
	CPosLmDatabaseManager(const CPosLmDatabaseManager &)
CPosLmDatabaseManager &	operator=(const CPosLmDatabaseManager &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
TUid	iDtorIdKey

Constructor & Destructor Documentation

CPosLmDatabaseManager()

IMPORT_C

CPosLmDatabaseManager

(

)

[protected]

CPosLmDatabaseManager(const CPosLmDatabaseManager &)

CPosLmDatabaseManager

(

const CPosLmDatabaseManager &

)

[private]

Parameters

const CPosLmDatabaseManager &

~CPosLmDatabaseManager()

IMPORT_C

~CPosLmDatabaseManager

(

)

[virtual]

Destructor.

Member Functions Documentation

CancelNotifyDatabaseEvent()

TInt

CancelNotifyDatabaseEvent

(

)

[pure virtual]

Cancels a call to NotifyDatabaseEvent .

CopyDatabaseL(const TDesC &, const TDesC &)

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

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.

Parameters

const TDesC & aSourceUri	The URI of the database to copy.
const TDesC & aTargetUri	The URI of the new database location.

CreateDatabaseL(HPosLmDatabaseInfo &)

void

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.

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.

Parameters

HPosLmDatabaseInfo & aDatabaseInfo

Information about the landmark database to create. The information object will be updated with media type and drive information.

DatabaseExistsL(const TDesC &)

TBool

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.

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

leave: KErrArgument The URI is incorrect.

Parameters

const TDesC & aDatabaseUri

The URI of the database which should be checked for existence.

DatabaseUriFromLastEventLC()

HBufC *

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.

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.

DefaultDatabaseUriLC()

HBufC *

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.

DeleteDatabaseL(const TDesC &)

void

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.

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.

Parameters

const TDesC & aDatabaseUri

The URI of the database to delete.

GetDatabaseInfoL(HPosLmDatabaseInfo &)

void

GetDatabaseInfoL

(

HPosLmDatabaseInfo &

aDatabaseInfo

)

[pure virtual]

Retrieve information about a landmark database.

This function requires ReadUserData capability.

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.

Parameters

HPosLmDatabaseInfo & 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.

ListDatabasesL(RPointerArray< HPosLmDatabaseInfo > &, const TDesC &)

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

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

Parameters

RPointerArray< HPosLmDatabaseInfo > & 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.
const TDesC & aProtocol = KNullDesC	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.

ListDatabasesLC(const TDesC &)

CDesCArray *

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.

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

Parameters

const TDesC & aProtocol = KNullDesC

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.

ModifyDatabaseSettingsL(const TDesC &, const TPosLmDatabaseSettings &)

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

Modifies the settings for a landmark database.

This function requires ReadUserData and WriteUserData capabilities.

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.

Parameters

const TDesC & aDatabaseUri	The URI of the database to modify settings for.
const TPosLmDatabaseSettings & aDatabaseSettings	The new settings for the database.

NewL()

IMPORT_C CPosLmDatabaseManager *

NewL

(

)

[static]

Two-phased constructor.

This function requires ReadUserData capability.

NotifyDatabaseEvent(TPosLmDatabaseEvent &, TRequestStatus &)

void	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

TPosLmDatabaseEvent & aEvent	Contains the event information when an event occurs (request completes).
TRequestStatus & aStatus	Is completed with KErrNone if an event occurs or an error code if some error is encountered.

RegisterDatabaseL(HPosLmDatabaseInfo &)

void

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.

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.

Parameters

HPosLmDatabaseInfo & aDatabaseInfo

Information about the landmark database to register. The information object will be updated with media type and drive information.

SetDefaultDatabaseUriL(const TDesC &)

void

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.

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.

Parameters

const TDesC & aDatabaseUri

The URI of the database which should be set as default.

UnregisterAllDatabasesL(const TDesC &)

void

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.

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.

Parameters

const TDesC & aProtocol

The protocol to unregister all databases for.

UnregisterDatabaseL(const TDesC &)

void

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.

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.

Parameters

const TDesC & aDatabaseUri

The URI of the database to register.

operator=(const CPosLmDatabaseManager &)

CPosLmDatabaseManager &

operator=

(

const CPosLmDatabaseManager &

)

[private]

Parameters

const CPosLmDatabaseManager &

Member Data Documentation

TUid iDtorIdKey

TUid

iDtorIdKey

[private]