Symbian^3 Application 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

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]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.