Figure 1: Landmark database access classes
Landmarks API is mainly targeted for end-user applications. It lets clients access landmark databases and read/edit their content.
This API uses position classes and generic position field IDs from Location Acquisition API to define the location of a landmark.
Landmarks API enables defining landmark categories. Landmark categories are labels, which can be assigned to a landmark to define the type of the landmark. For instance, a landmark of some restaurant could be a assigned with category “Restaurants”.
Landmarks API provides an interface for listening to database events. Clients can be notified when a landmark database is edited.
Landmarks API also offers methods for exporting landmark data to and importing from exchange format, which enables exchanging landmarks between terminals.
Note: Landmarks API does not provide search functionality. Search is provided by Landmarks Search API.
The logical type of the API is Library API. Technically it is method-call interface. Landmarks API loads the implementation at run time but the implementation consists only of local objects.
Landmark is a location with a name and it may also contain other data, such as description, icon, address details etc. Landmarks are organized in landmark databases, which reside on terminal or may be remote. Client can read landmarks from a database, add new, modify and remove existing landmarks.
A landmark can contain the following attributes:
| Landmark attribute | Description |
| Item ID | This ID is a reference to the landmark in a landmark database. It is locally unique within one database. |
| Landmark name | The name of the landmark can contain a maximum of 255 characters. The landmark name does not have to be unique in a database. |
| Position | The WGS84 coordinate for the landmark. |
| Coverage radius | Coverage radius is set if the landmark is big, for example, a city. It defines the size of the area, which the landmark represents. The coverage area is specified in meters. |
| Category info | The categories related to the landmark, e.g. restaurant, gas station, grocery store, etc. For more information about categories, see section Landmark categories. |
| Icon | A reference to an icon in an icon file which can be used to symbolize the landmark in a UI. An icon mask can also be specified from the same icon file. |
| Description | A textual description of the landmark, for example, “Chinese restaurant. Nice atmosphere and the service is superb”. The description has a maximum length of 4095 characters. |
| Position fields | Generic position fields as defined by Location Acquisition API. A position field can, for instance, be the street address of the landmark or the name of the city where the landmark is found. Landmarks API only supports text position fields. If the client wants to store a non-text field, the value must first be converted to a textual representation. A landmark can contain any number of position fields. |
A landmark may be assigned to one or many categories (or none at all). Categories help to classify landmarks, group them, enable finer search criteria etc. Landmark categories are also stored in landmark databases.
Landmark categories may be local or global. Local categories are defined by the user. They are stored in a database and cannot be reused by multiple databases unless the user creates the same category in several databases.
Global categories are predefined in the terminal and may be reused in multiple databases and multiple phones and on different platforms. The Global Category ID uniquely specifies a global category, which makes global categories localizable. The names and icons of global categories are predefined in a resource file and the category name is automatically changed in the database when it is open if the terminal language changes since the last usage of the database. Note: The global category name will not be changed to the newly selected language if the user has previously renamed this category.
The predefined global landmark categories are listed in the following table:
| ID | Name | Purpose (examples of landmarks) |
| 3000 | Accommodation | Hotel, Camping site |
| 6000 | Business | Bank, Factory, Office |
| 9000 | Communication | Internet Access Point, Public Telephone, Wireless LAN Hot Spot |
| 12000 | Educational institute | School, College |
| 15000 | Entertainment | Amusement park, Cinema, Concert hall, Night club |
| 18000 | Food & Beverage | Fast food, Restaurant, Café, Bar |
| 21000 | Geographical area | City, City center, Town |
| 24000 | Outdoor activities | Camping site, Fishing place, Hunting, National park, Playground |
| 27000 | People | My home, My friend’s home, Father’s summer cottage, Child’s school |
| 30000 | Public service | Tourist information office, Government office, Library, Post office, Hospital, Police |
| 33000 | Religious places | Church, Mosque |
| 36000 | Shopping | Market Place, Pharmacy, Shop, Shopping Center |
| 39000 | Sightseeing | Monument, Mountain top, Museum |
| 42000 | Sports | Bowling, Golf course, Ice hockey hall, Stadium |
| 45000 | Transport | Airport, Bus stop, Harbour, Railway Station, Rest area |
Other IDs are reserved for future use. Names are given only for reference purposes, localized names are defined for all languages supported by the platform.
A landmark category contains the following attributes:
| Category attribute | Description |
| Item ID | This ID is a reference to the category in a landmark database. It is locally unique within one database. |
| Category name | The name of the category can contain a maximum of 124 characters. The category name must be unique in a database. If the client tries to change the name of a category and that name is already occupied by another category, the update fails. |
| Global category ID | This ID refers to a category in a globally defined category set. |
| Icon | A reference to an icon in an icon file, which can be used to symbolize the category in a UI. An icon mask can also be specified from the same icon file. |
These a main use cases for Landmarks API:
The following subchapters describe the Landmarks API class structure. UML diagrams are used to present the classes and their dependencies. Note: The UML diagrams do not show all the available methods, and some of or all of the method parameters may be left out.
Landmarks are stored in databases. A client accesses landmark databases
through the CPosLandmarkDatabase class. Each instance of
CPosLandmarkDatabase is a handle to exactly one landmark database. All operations
upon a landmark database are performed through instances of CPosLandmarkDatabase.
CPosLandmark represents the content of a landmark, for
example the landmark name and landmark position. This class is used in CPosLandmarkDatabase methods
to let the client read or edit a landmark in the database.
A landmark stored in a database is referenced by an ID (TPosLmItemId),
which is unique within the database. To access a landmark through CPosLandmarkDatabase,
the client must specify the ID of the landmark.
It is common that a client needs to retrieve a set of landmarks, for instance
when listing the content of a landmark database. In Landmarks API, a landmark
set is accessed by using an iterator object. CPosLmItemIterator lets
the client retrieve the IDs of the iterated landmarks. The client can iterate
all the landmarks in a database by retrieving a CPosLmItemIterator instance
from CPosLandmarkDatabase.
Clients may require retrieving landmarks in a certain sort order. In Landmarks
API, the client specifies sort preference by using a TPosLmSortPref object.
If a client is not interested in full landmark information, it can perform
a partial read. For instance, the client may only be interested in the name
of the landmark. By using a CPosLmPartialReadParameters object,
the client can specify which landmark information is of interest.
Figure 1: Landmark database access classes
A landmark database can contain landmark categories. To access categories
in the database, the client must create a CPosLmCategoryManager object
connected to the database. Through this object, the client can retrieve information
about the categories in the database or edit the category content.
CPosLandmarkCategory represents information about a
landmark category. It is used in the CPosLmCategoryManager interface
to pass category information from/to the client.
A landmark category stored in a database is referenced by an ID (TPosLmItemId),
which is unique within the database. To refer to a landmark category, the
client specifies the ID of the category. Note: The same type, TPosLmItemId,
is used to refer to landmarks and categories. It is possible that a landmark
and a category have the same ID.
Categories can be iterated, just like landmarks. CPosLmItemIterator is
used for iterating both landmark and category sets. Note: The iterator
is never used to iterate a mixed set of landmarks and categories.
Figure 2: Landmark category management classes
A client can listen to events from landmark databases. To listen to the
next event, the client calls CPosLandmarkDatabase.
The client passes a TRequestStatus, which will be completed
when an event is detected. When an event has been retrieved, the client must
renew the NotifyDatabaseEvent() request to listen to further
events.
Figure 3: Classes for listening to landmark database events
A client can exchange landmark data with another party by using the import
and export functionality. If a client has received a file or buffer containing
landmark data and the client is connected to a landmark database, the client
can use Landmarks API to import landmarks to the landmark database. To import
landmarks, the client has to create an instance of the CPosLandmarkParser class.
The client can also use Landmarks API to export landmarks from the landmark
database. This will result in a file or buffer containing the landmark data.
To export landmarks, the client has to create an instance of the CPosLandmarkEncoder class.
Figure 4: Classes for handling exchange of landmark content
Some operations in Landmarks API can potentially take a long time. These
operations can therefore be run incrementally. The client retrieves a CPosLmOperation object,
which can either be run incrementally or all at once.
If the operation is run incrementally, the client can read the operation progress between incremental steps.
Figure 5: Classes for handling incremental operations in Landmarks API
A client can pack a landmark or a landmark category object into a buffer
for further serialization. This can be used e.g. for sending data over process
boundaries. On the receiving side packed objects can be unpacked from buffer.
The PosLandmarkSerialization class contains static methods PackL() and UnpackL() for
packing and unpacking CPosLandmark instances. PosLmCategorySerialization class
contains appropriate methods for packing and unpacking CPosLandmarkCategory instances.
This feature is added in S60 3.1.
Figure 6: Classes for packing landmark and categories into buffer and unpacking back
