Landmarks Database Management API Specification

1 Overview

The Landmarks Database Management API allows clients to manage landmark databases, for example creating new databases or deleting existing databases. The API is used mainly by end-user applications.

API category	public
API type	c++
API libraries	eposlmdbmanlib.lib
Location	`/sf/mw/locationsrv/locsrv_pub/landmarks_database_management_api`
Buildfiles	`/sf/mw/locationsrv/locsrv_pub/landmarks_database_management_api/group/bld.inf`

1.1 Description

The Landmarks Database Management API is a Library API and is provides with the client-server interface (The implementation encapsulates a server session).

1.2 Changes

The Landmarks Database Management API is introduced in Symbian OS, S60 3.0.

1.3 Use Cases

Getting information about available databases
Modifying database settings
Managing landmark databases
Listening to database-related events

1.4 Class Structure

Summary of API classes and header files
Classes	Files

CPosLmDatabaseManager /epoc32/include/mw/EPos_CPosLmDatabaseManager.h CPosLmDatabaseManagerPluginBase /epoc32/include/mw/EPos_CPosLmDatabaseManagerPluginBase.h HPosLmDatabaseInfo /epoc32/include/mw/EPos_HPosLmDatabaseInfo.h TPosLmDatabaseSettings /epoc32/include/mw/EPos_TPosLmDatabaseSettings.h No classes/epoc32/include/mw/EPos_TPosLmDatabaseEvent.h

The main interface to the API is the CPosLmDatabaseManager class.
The class HPosLmDatabaseInfo holds information about a database.
TPosLmDatabaseSettings is used to read or change the settings for a database.
The TPosLmDatabaseEvent class is used when notifications about changes are requested.
This API also contains the CPosLmDatabaseManagerPluginBase class, but it is reserved for future extensions and must not be used by clients.

Landmarks Database Management API class structure

2 Using The API

2.1 Listing landmark databases

A client can request list of all available landmark databases by using the CPosLmDatabaseManager::ListDatabasesLC() method. It is also possible to specify that only databases of some protocol are listed. For example, to get a list of only local native databases, use the "file" protocol as an input parameter, as shown in the first example below.

A client can get more information about a database than only the database URI. The client can use CPosLmDatabaseManager::ListDatabasesL() or CPosLmDatabaseManager::GetDatabaseInfoL() methods to receive an instance of the HPosLmDatabaseInfo class, which contains properties such as media where database is located, drive for local database and whether this database is the default.

The first example uses less memory at the cost of performance. It first gets URIs of databases and then retrieving database info for every particular database.

CPosLmDatabaseManager* dbManager = CPosLmDatabaseManager::NewL();
CleanupStack::PushL( dbManager );

// Get a list of databases
_LIT( KFileProtocol, "file" );
CDesCArray* dbList = dbManager->ListDatabasesLC( KFileProtocol );

for ( TInt i = 0; i < dbList->Count(); ++i )
    {
    TPtrC dbUri = ( *dbList )(i);
    HPosLmDatabaseInfo* dbInfo = HPosLmDatabaseInfo::NewLC( dbUri );
    dbManager->GetDatabaseInfoL( *dbInfo ); // this is client-server call

    // Get information about the database
    TPtrC uri = dbInfo->DatabaseUri();
    TPtrC protocol = dbInfo->Protocol();
    TBool defaultDb = dbInfo->IsDefault();
    TChar drive = dbInfo->DatabaseDrive();
    TInt size = dbInfo->Size();

    CleanupStack::PopAndDestroy( dbInfo );
    }

// Destroy the list
CleanupStack::PopAndDestroy( dbList );
CleanupStack::PopAndDestroy( dbManager );

The example below allocates memory for holding information about all the databases at once.

CPosLmDatabaseManager* dbManager = CPosLmDatabaseManager::NewL();
CleanupStack::PushL(dbManager);

// Get a list of database information
RPointerArray<HPosLmDatabaseInfo> dbInfoList;
dbManager->ListDatabasesL( dbInfoList );

for ( TInt i = 0; i < dbInfoList.Count(); ++i )
    {
    HPosLmDatabaseInfo* dbInfo = dbInfoList(i);

    // Get settings
    const TPosLmDatabaseSettings& settings = dbInfo->Settings();
    // Check if a display name is set
    if ( settings.IsAttributeSet( TPosLmDatabaseSettings::EName ) )
        {
        TPtrC displayName = settings.DatabaseName();
        }
    }

// Destroy the list
dbInfoList.ResetAndDestroy();

CleanupStack::PopAndDestroy( dbManager );

2.2 Modifying database settings

A client applications can customize some settings of landmark databases through the CPosLmDatabaseManager::ModifyDatabaseSettingsL method. TPosLmDatabaseSettings encapsulates the attributes that can be set for a landmark database. Currently only database name attribute is supported. The example below shows how to set a friendly name for a database. Typically, applications display this name instead of the URI.

The following diagram and example show how the client can change the display name of a database.

Modifying database name sequence diagram

_LIT( KDatabaseUri, "file://c:myLandmarks.ldb" );
_LIT( KDisplayname, "My landmarks" );

CPosLmDatabaseManager* dbManager = CPosLmDatabaseManager::NewL();
CleanupStack::PushL( dbManager );
HPosLmDatabaseInfo* dbInfo = HPosLmDatabaseInfo::NewLC( KDatabaseUri );

TPosLmDatabaseSettings& settings = dbInfo->Settings();
settings.SetDisplayName( KDisplayName );
dbManager->ModifyDatabaseSettingsL( KDatabaseUri, settings );

CleanupStack::PopAndDestroy( dbInfo );
CleanupStack::PopAndDestroy( dbManager );

2.3 Managing landmark databases

To start managing landmark databases, clients need to create an instance of the CPosLmDatabaseManager class. Database URIs are used to refer to landmarks databases.

Clients can create, copy, move and delete landmark databases. For example, to create a new landmark database use the following code:

_LIT(KDatabaseUri, "file://c:myLandmarks.ldb");

CPosLmDatabaseManager* dbManager = CPosLmDatabaseManager::NewL();
CleanupStack::PushL( dbManager );

HPosLmDatabaseInfo* dbInfo = HPosLmDatabaseInfo::NewLC( KDatabaseUri );
dbManager->CreateDatabaseL( *dbInfo );

CleanupStack::PopAndDestroy( dbInfo );
CleanupStack::PopAndDestroy( dbManager );

The actual implementation used to create the database depends on the type of the URI. Method calls that have a URI parameter are blocking and can take a long time to complete. This must be considered if the used protocol is slow to perform the task. For local file access, this is fast.

The example below shows how to move a database between two drives on terminal:

_LIT( KSourceUri, "file://c:myLandmarks.ldb" );
_LIT( KDestUri, "file://e:myLandmarks.ldb" );

CPosLmDatabaseManager* dbManager = CPosLmDatabaseManager::NewL();
CleanupStack::PushL( dbManager );

dbManager->CopyDatabaseL( KSourceUri, KDestUri );
dbManager->DeleteDatabaseL( KSourceUri );

CleanupStack::PopAndDestroy( dbManager );

2.3.1 Registering landmark databases

Some protocols may not support creating and deleting databases. In that case, clients should use CPosLmDatabaseManager::RegisterDatabaseL() and CPosLmDatabaseManager::UnregisterDatabaseL() respectively instead. By registering a database, a link is created so that it is listed when a list of all landmarks databases is requested. Registering is only performed for remote databases. It is not supported for local files (those of "file" protocol).

2.4 Listening to events

Clients listen to database events such as creation of a new database or changing default database location. Event notification is implemented through asynchronous requests. TPosLmDatabaseEvent holds information about the occurred event. Some events are associated with the URI of an affected database, which can be retrieved by CPosLmDatabaseManager::DatabaseUriFromLastEventLC() . Note: This should be performed before a new request for notification is made.

The following diagram shows basic steps that clients perform to get informed about and to analyze database-related events.

Listening to database events

2.5 Error handling

The Landmarks Database Management API uses the standard Symbian error reporting mechanism. In case of a serious error, panics are used, otherwise, errors are reported through return codes or leaves.

The Landmarks Database Management API uses the same panic code category as Landmarks API. The panic codes are documented in Landmarks API specification.

2.6 Memory and Performance Considerations

Depending on the type of the URI, an ECom plug-in is loaded for the used protocol. Memory usage depends on the protocol. For local file access, the memory usage is low.

2.7 Extensions to the API

This version of the API does not allow extensions.

2.8 Security issues

Landmarks are considered as important user data and this applies some access limitations to client applications. For example, in order to be able to create or remove landmark databases, clients must have the WriteUserData capability. Whenever special capabilities are needed, they are listed in appropriate class and method descriptions.

3 Glossary

3.1 Definitions

**Definitions**
Landmark	A landmark is a named object that contains a location. The location can be defined by various attributes, such as WGS 84 coordinates or a textual address.
Landmark database	Persistent storage of a collection of landmarks and landmark categories.