Landmarks Database Management API: Using the Landmarks Database Management API

The 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 should be listed. For example, to get a list of only the local native databases, use "file" protocol as input parameter, as in the first of the following examples.

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

The first example uses less memory at the cost of performance, by first getting 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 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 list
dbInfoList.ResetAndDestroy();

CleanupStack::PopAndDestroy( dbManager );

Modifying database settings

The client applications can customize some settings of landmark databases via 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 will display this name instead of the URI.

The following diagram shows how the client can change the display name of a database.

The following code example shows how the client can change the display name of a database:

_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 );

Managing landmark databases

To start managing landmark databases, the client needs to create an instance of the CPosLmDatabaseManager class. Database URIs are used to refer to landmarks databases (see Landmarks API).

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 should be taken into consideration if the used protocol is slow to perform the task. For local file access, this is fast.

_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 );

Registering landmark databases

Some protocols may not support creating and deleting databases. In that case, the client 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 done for remote databases. It is not supported for local files (those of "file" protocol).

Listening to events

The client listens to database events such as creation of a new database or changing default database location. Event notification is implemented via 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 done before a new request for notification is made.

The following diagram shows basic steps that the client performs to get informed about, and to analyze database-related events.

Error handling

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.

Landmarks Database Management API uses the same panic code category as

Landmarks
            API

. The panic codes are documented in Landmarks API specification.

Memory overhead

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

Extensions to the API

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 client must have WriteUserData capability. Whenever special capabilities are needed, they are listed in appropriate class and method descriptions.