Figure 2: Root element diagram
On a high level, using this API consists of two tasks:
They are discussed in detail in the next chapters.
The Location Centre Registration file is an XML file, which must comply with the XML format defined by this API. This format declares what kind of services can be registered in Location Centre, what information must be given about them and what kind of rules must be followed. The formal specification is provided by the appropriate XML Schema, available from here.
The root element of the Location Centre Registration file format is location_centre_registration,
see the diagram below.
Figure 2: Root element diagram
This element must contain only one element, service, which
represents a single Location Centre service.
Location Centre services are described by the service element.
In XML Schema it is defined as the complex type serviceType,
as shown below.
Figure 3: Service element diagram
The service element's attributes are defined in the following
table.
| Attribute | Usage | Value type | Description |
uuid | Mandatory, Single | xs:anyURI | Universally Unique ID of the service. Not empty and of maximum 1024 symbols. |
The service element's contents are defined in the following
table.
| Element | Usage | Value type | Description |
name | Optional, Unlimited | xs:normalizedString | Localized name of the service for a particular language. This text must not contain tabs, line feeds or carriage returns (as defined by its type). |
icon | Optional, Single | No value allowed | The icon of the service. It is shown in the UI together with the service's name. |
feature | Optional, Unlimited | xs:token | A property which describes the service's features. Possible values are listed below. |
runmode | Mandatory, Single | No value allowed | Defines default execution mode for the service |
Only one of application, webService or document | Mandatory, Single | Contains a definition of the actual service (described in detail in Chapters Registering application, Registering web service and Registering document-based service respectively). Note that only one of these three is allowed and exactly one of them is required. |
Universally Unique ID
Every service must have a UUID (Universally Unique ID) assigned to it.
Location Centre ignores registrations, which use a UUID duplicate to an already
registered one. Thus the service element must have the attribute uuid defined.
The recommended value of the attribute is a string of the UUID value. See Wikipedia for information about UUIDs and how to generate them. Note however, that it is not required to use UUID values: Location Centre uses this value only for service identifying purposes. Therefore any string that can be considered unique in the context of Location Centre is acceptable. See special notes about UUIDs for different types of Location Centre services below.
An example of using the UUID tag is given below:
... <service uuid="09AE0C5C-C8B7-11DB-BD2F-38BD55D89593"> ... </service> ...
Name
| Attribute | Usage | Type | Description |
lang | Mandatory | xs:language | The language identifiers, which can be used with this attribute, are defined in RFC 3066, as mentioned in the XML Schema specification. |
Every service has a name. This is a localizable string, which is shown
for the user in UI. Localization is achieved by providing as many instances
of this element as there are translations for this string defined. The actual
language of the text is specified in the lang attribute attached
to the appropriate name tag. Location Centre uses only the
first 50 characters of this text.
One instance of the name per available translation should be given. If no given translation matches the currently selected language in the terminal, Location Centre tries to use other languages based on the Symbian OS language downgrade paths. Therefore it is recommended to always provide at least an English name with the language tag "en".
The name can be omitted for the application type of services
(see Chapter Registering application).
If so, Location Centre tries to find a localizable name by using normal application
registration information in the system. For all other types of services, the
name is required.
There is an example of using this tag below to provide several translations for a service's name:
... <name lang="en">Maps</name> <name lang="fi">Kartat</name> ...
Icon
Along with a name, a service may have an icon, which is also shown on the UI.
| Attribute | Usage | Type | Description |
file | Mandatory | xs:string | The path and name of the icon file. |
frame | Optional | xs:unsignedInt | An index of the icon frame in the multi-frame file. |
The icon can be either an SVG file (.svg) or a Symbian OS MIF file (.mif,
a collection of scalable icons). If it is the latter, then additionally the
index of the icon within the MIF file can be specified by using the attribute frame.
By default, the first frame is used for multi-frame files.
The icon file path should not contain a drive name and the icon should be located on the same drive as this registration file. The icon file should be accessible for reading by any client.
Only one icon can be specified. If it is not specified at all, then Location Centre uses the default icon and therefore it is recommended to supply a custom icon for non-application-based services. For application-based services (see Chapter Registering application) Location Centre uses the application's icon by default.
The following example shows how to use this element with MIF files.
<icon file="\resource\mapsicons.mif" frame="10">
The following example shows how to use this element with SVG files.
<icon file="\resource\mapservice.svg">
Features
In order to give clients of the Location Centre API an ability to customize a list of Location Centre Services based on their needs, a registrant can specify more accurately what kind of features describe that service. Those features are related to functionality and data usage of the service. The following features are defined:
| Feature | Description |
| "Settings" | A service which is used to configure the user’s terminal or the remote server for location related functionality. |
| "PersonalData" | A service which enables the user to manage his personal information either on the terminal or on a remote server. |
| "Navigation" | A service which helps the terminal user to navigate from one location to another. |
| "Maps" | A service which provides map content, local or remote. |
| "LocationEvents" | A service which triggers or handles events based on the terminal’s current location. |
| "RemotePositioning" | A service involved in determining the current location of other terminals or objects. |
| "NetworkService" | A service running on a network. |
| "LocationMessaging" | A service which is used to send location-enhanced messages. |
| "LocalContent" | A service which uses content stored on a terminal. |
| "RemoteContent" | A service which uses remote content (would need network connection to access the content). |
The feature element is used for that purpose. No attributes
are defined for this element. If a service is associated with several features,
the registration file should contain several instances of the feature tag.
It is recommended to specify at least one feature, because if the client requests for a customized list of services, based on feature filtering (see Location Centre API for details), the Location Centre lists only those services, which have specified features and skips others. It is also recommended to use data-related features "LocalContent" and "RemoteContent" in combination with others.
The following example shows how a Map application with local map content could use this tag to describe its capabilities.
... <service> ... <feature>Maps</feature> <feature>LocalContent</feature> ... </service> ...
Run mode
A service can be executed in different modes in relation to the client
application of Location Centre API: standalone or chained. This API allows
registrants to specify which mode should be used by default. The element runmode serves
this purpose. It contains no value by itself but has the attribute default which
defines the default execution mode of the service, see table below.
| Attribute | Usage | Type | Description |
default | Mandatory | xs:token | Possible values are: "standalone", "child". |
The next example shows how to use this element to describe that a service recommends the Standalone mode to be run in.
<runmode default="standalone">
Service implementation
The actual type of service implementation is defined by selecting one of
the application, webService or document tags,
which are described in detail below.
Applications are registered by using the application tag,
defined below.
Figure 4: Element 'application'
The application element's contents are defined in the
following table. No attributes are defined for this element.
| Element | Usage | Value type | Description |
native | Single | No value allowed | Describes the native Symbian OS application. |
java | Single | No value allowed | Describes the Java application. |
params | Optional, Single | xs:string | Command line parameters that should be passed to the executable when it is started. |
Only one of the elements native and java can
be used at a time.
Native Symbian OS applications
Native Symbian OS executable can be identified by a SID (Security ID, usually
same as UID3, see Symbian OS documentation for Platform Security) value and
described by using the child tag native. This tag has no
subelements and contains information in its attributes, which are described
in the following table.
| Attribute | Usage | Value type | Description |
sid | Mandatory | xs:string | SID of the executable, which implements the service. The SID should be written as a hexadecimal value in the following format: "[1234ABCD]". (Note capitals.) |
The recommended value of the Universally Unique ID of application services is UUID (as for any other services), but also SID of the executable can be used, or an ID based on the SID.
Below is a full example of registering the Maps application, which implements both map views and navigation facilities and utilizes local and remote content. The Maps application defines three translations for its name, for English, Finnish and Russian. Its default run mode is stand-alone and the SID of the executable is 20001F63. No parameters used.
<?xml encoding="UTF-8" version="1.0" standalone="yes"?>
<location_centre_registration>
<service uuid="SID20001F63_A">
<name lang="en">Maps</name>
<name lang="fi">Kartat</name>
<name lang="ru">Карты</name>
<icon file="\resource\mapsicons.mif" frame="10">
<feature>Maps</feature>
<feature>Navigation</feature>
<feature>LocalContent</feature>
<feature>RemoteContent</feature>
<runmode default="standalone"/>
<application>
<native sid="[20001F63]">
</application>
</service>
</location_centre_registration>Java applications
Java applications are identified by name, specified in the midlet attribute
of the element java. This is because they are assigned with
a UID only at the installation phase and therefore the UID is unknown when
the registration file is compiled.
| Attribute | Usage | Value type | Description |
midlet | Mandatory | xs:string | Name of the Java application |
The recommended value of Universally Unique ID of the Java application services is UUID.
Below is a simple example of registering a location based service implemented in the Java application.
<?xml encoding="UTF-8" version="1.0" standalone="yes"?>
<location_centre_registration>
<service uuid="09AE0C5C-C8B7-11DB-BD2F-38BD55D89593">
<name lang="en">Address search</name>
<runmode default="standalone"/>
<application>
<java midlet="MyJavaAddressSearch">
</application>
</service>
</location_centre_registration>Another type of Location Centre service is a web service, defined as service's
child element webService. In fact it is any service, which
is accessed by the user as a web page. Therefore such services are defined
by the only property - URL.
Figure 5: Element 'webService'
The webService element's contents are defined in the following
table. No attributes are defined for this element.
| Element | Usage | Value type | Description |
url | Mandatory, Single | xs:anyURI | The URL specified in this field should be an absolute URL, otherwise it is not useful for the client applications and the user of Location Centre. |
The recommended value of the Universally Unique ID of the web services is UUID (as for any other services), but also the URL of the service can be used, or an ID based on, e.g., the domain name. By nature, Web-based services are network-located services and therefore they are recommended to declare the "NetworkService" feature.
Web services are accessed using the Browser application and therefore the runmode property
of such services defines the execution mode of the Browser application in
relation to calling a client.
Below is a full example of registering a pizza delivery web service, which is based on the current location of the terminal. It defines only one translation for its name, for English. Its default run mode is stand-alone and the web address is "http://www.anywherepizza.com/request".
<?xml encoding="UTF-8" version="1.0" standalone="yes"?>
<location_centre_registration>
<service uuid="www.anywherepizza.com-2007">
<name lang="en">AnywherePizza</name>
<feature>NetworkService</feature>
<runmode default="standalone"/>
<webService url="http://www.anywherepizza.com/request"/>
</service>
</location_centre_registration>For the purposes of services based on a content, the Location Centre Registration API defines the document-based type of service. Its functionality is based on the default document handler, defined on a particular terminal for the given MIME type. Instead of running any application or opening a web page, Location Centre attempts to open the given document, which causes this document to be opened by the registered content handler for this document. This approach can be used for services based on Flash, for example.
A document-based service is declared in the registration file by the service's
child element document. It has the only attribute, file,
which identifies the document to be open.
Figure 6: Element 'document'
The document element's contents are defined in the following
table. No attributes are defined for this element.
| Attribute | Usage | Value type | Description |
file | Mandatory, Single | xs:string | Path and name of the document. |
The file attribute should contain a path to the file in
question in the terminal's file system. The drive name should be omitted and
the file should be located on the same drive where registration file is found.
The file shall be located in a folder accessible for its associated document
handler.
As the file name cannot be used to build a universally unique ID, the only valid value of the Universally Unique ID of document-based services is UUID.
The Run mode of such services defines the Execution mode of the handler application in relation to calling a client.
Below is a full example of registering the Map application based on Flash. The drive is not specified and is assumed as the same drive which contains this registration file.
<?xml encoding="UTF-8" version="1.0" standalone="yes"?>
<location_centre_registration>
<service uuid="09AE0C5C-C8B7-11DB-BD2F-38BD55D89593">
<name lang="en">FlashMap</name>
<runmode default="child"/>
<feature>Maps</feature>
<feature>RemoteContent</feature>
<document file="\data\others\mapflash"/>
</service>
</location_centre_registration>In order for a service to be registered in Location Centre, the registration
file has to be put to the Location Centre Server's private import folder,
i.e., to the folder \private\10283138\import. Registrants
must make sure that the files in that folder have a unique name, therefore
the file should have a name of the UUID used in the service's registration
file and the extension xml.
Built-in applications use the Location Centre's private folder in ROM. Post-installed registrants use system drives or memory cards. They can have their registration file put to this folder by creating an installation package and specifying an appropriate target folder for the registration file.
Generally, it is recommended that the installation file does not specify the name of the target drive, because the drive names, as well as the number of available drives, may differ from terminal to terminal and it is better to let the user decide where to install. Using the exclamation mark in place of the drive name instructs the software installer to ask the user to select the target drive. All such files from the package are installed to the same drive in that case. That way it is easy to make sure that the Location Centre registration file, and the files it refers to, are located on the same drive (which is required for icon and document files).
If a registration file does not comply with the specified XML format depicted in this document, it is silently rejected by Location Centre. Use XML validation tools to verify that a registration file is correct.
Not applicable.
This API enables no extensions.
