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:

Create a service +object for the API using device.getServiceObject().
+
Define the +tasks you want to perform and choose the correct methods for them.
+
Optionally, +define how you want the results filtered.
Define methods +to process the results.
Retrieve the +results using the methods from step 2. Use asynchronous methods together with callback().
+
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.