Contents

• Purpose
  • Constraints
• API Description
  • Use cases
  • API class structure
• Using the Landmarks Database Management API
  • Listing landmark databases
  • Modifying database settings
  • Managing landmark databases
    • Registering landmark databases
  • Listening to events
  • Error handling
  • Memory overhead
  • Extensions to the API
  • Security issues
• Glossary
  • Abbreviations
  • Definitions
• References

Constraints

Landmarks Database Management API is available from S60 3rd Edition onwards.

Use cases

• Getting information about available databases

• Modifying database settings

• Managing landmark databases

• Listening to database-related events

API class structure

The main interface to the API is the CPosLmDatabaseManager class. The class HPosLmDatabaseInfo holds information about a database and 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 not supposed to use by clients and reserved for future extensions.

• CPosLmDatabaseManager
• CPosLmDatabaseManagerPluginBase
• HPosLmDatabaseInfo
• TPosLmDatabaseEvent
• TPosLmDatabaseSettings

Listing landmark databases

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

• CPosLmDatabaseManager::GetDatabaseInfoL()
• CPosLmDatabaseManager::ListDatabasesL()
• CPosLmDatabaseManager::ListDatabasesLC()
• HPosLmDatabaseInfo

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

• CPosLmDatabaseManager::ModifyDatabaseSettingsL
• TPosLmDatabaseSettings

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.

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

• CPosLmDatabaseManager

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.

• CPosLmDatabaseManager::DatabaseUriFromLastEventLC()
• TPosLmDatabaseEvent

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

This version of the API does not allow extensions.

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.

• WriteUserData

Abbreviations

Abbreviations

None

Definitions

Definitions

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