Accessing and managing information about landmarks

The Landmarks Service API allows widgets 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 widgets 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

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 so = device.getServiceObject("Service.Landmarks", "IDataSource");

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.

Using the service in a widget

To access and manage landmark information using the Landmarks Service API:

  1. Create a service object for the API using device.getServiceObject().

  2. Define the tasks you want to perform and choose the correct methods for them.

  3. Optionally, define how you want the results filtered.

  4. Define methods to process the results.

  5. Retrieve the results using the methods from step 2. Use asynchronous methods together with callback().

  6. Process the results using the methods defined in step 4.

For the complete source of a sample widget that demonstrates how to use this service, see the full example.

© Nokia 2008.