Accessing and managing information about landmarks

The Landmarks Service API allows Flash Lite applications to access and manage information about landmarks and landmark categories. This information is stored in one or more landmark databases on a device. You can use the Landmarks Service to create Flash Lite applications that:

  • Retrieve information about landmarks, landmark categories, and landmark databases

  • Create, edit, and delete landmarks and landmark categories

  • Import and export landmarks

  • Organize landmarks into landmark categories

For example code snippets that focus on common Landmarks Service use cases, see section Flash Lite components and code snippets.

The Landmarks Service involves the following concepts:

  • Landmark is defined as a location with a name. The location of a landmark is expressed as a set of geographical coordinates accompanied by either coordinate measurement accuracy information or a textual description, such as an address. A landmark can be used as Point of Interest (POI). Each landmark has a unique ID that distinguishes it from other landmarks in the same database. The ID is assigned when the landmark is added to the database.

    For detailed information about landmark objects, see section Landmark.

  • Landmark category groups landmarks according to type and interest. For example, a category can denote geographical or architectural interest, or it can relate to a particular type of attraction or activity. Each category has a unique name and ID that distinguish it from other categories in the same database. The ID is assigned when the category is added to the database.

    Landmark categories are further classified as follows:

    • Local categories are created by the user for a specific database. A local category is only valid for landmarks in the same database for which the category was created.

    • Global categories exist across all databases and have unique global IDs associated with them. Global categories are valid for all landmarks in all databases. Accommodation, Businesses, and Education, for example, are global categories.

    For detailed information about landmark category objects, see section Landmark category.

  • Landmark database stores landmarks and landmark categories. Each database has a unique URI that identifies the database.

    Landmark databases are further classified as follows:

    • Local databases reside on the device or on some device mapped to the device's file system. The default database is file://c:eposlm.ldb. If the device does not contain the default database, it is created when it is called for the first time by a service request.

      The URI of a local landmark database consists of a protocol specifier and the database location: file://<location>. If no protocol is specified, file:// is used by default. The location consists of the drive and the database file name, for example c:landmarks.ldb. The path to the file cannot be specified. The extension of the database file name must be ldb.

    • Remote databases reside in third-party servers and are accessed using a specific protocol. Creating or deleting remote databases results in adding or removing a bookmark on the device, respectively.

      Note: Remote databases and associated operations are not currently supported.

    For detailed information about landmark database objects, see section Landmark database.

Accessing the API and supported methods

To create a service object for the Landmarks Service API, use Service.Landmarks to identify the service provider and IDataSource to identify the supported interface:

var landmark = new Service("Service.Landmarks", "IDataSource");

If you want to specify your own default landmark database for a service instance, specify the URI of the database when creating the service object:

var parameters = {DatabaseURI:"file://c:mylandmarks.ldb"};
var landmark = new Service("Service.Landmarks", "IDataSource", null, parameters);

For this service instance, the specified database (file://c:mylandmarks.ldb) is used as the default. However, if a method call tries to access this database, and it does not exist on the device, the call fails and returns an error. The custom default database is not created, if it does not exist.

The IDataSource interface provides the following methods:

  • New()

    Use the New() method to create an empty landmark or landmark category item. You can use this item as a template.

  • GetList()

    Use the GetList() method to retrieve information about landmarks, landmark categories, or landmark databases.

  • Add()

    Use the Add() method to add a new landmark or landmark category to a landmark database. You can also use this method to edit an existing landmark or landmark category.

  • Delete()

    Use the Delete() method to delete a landmark or landmark category from a landmark database.

    Note: You cannot delete landmark databases.

  • Import()

    Use the Import() method to import landmarks to a landmark database.

  • Export()

    Use the Export() method to export landmarks from a landmark database.

  • Organise()

    Use the Organise() method to add landmarks to a landmark category or to remove landmarks from a landmark category.

  • Cancel()

    Use the Cancel() method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Landmarks Service API.

© Nokia 2009.