Purpose

PSY Configuration UI Plug-in API is meant for PSY module developers who intend to provide a configuration UI application for their PSY. See reference document [ 1] for information of developing a PSY module. PSY Configuration UI Plug-in API in conjunction with Positioning Plug-in API (see reference document [1]) provides the PSY module developer with the complete information on developing a PSY module with a configuration UI. The Positioning Settings (part of the General Settings application) can launch a specific PSY’s configuration UI application within its context. This API provides the developer an interface to plug the PSY configuration UI application into the Positioning Settings.

PSY Configuration UI Plug-in API is classified as a Domain API.

Constraints

PSY Configuration UI Plug-in API is available from S60 release 3.0 onwards.

API description

PSY Configuration UI Plug-in API is based on a service discovery mechanism. This API defines a Service UID which client implementation should use in its resource file in order to inform the system that it implements this PSY configuration UI service. Further, the client implementation should also specify the UID of the PSY for which it is providing the configuration UI.

Positioning Settings uses the service discovery mechanism to find all PSY Configuration UI applications and associates them to their respective PSY modules. It can then launch the PSY specific configuration UI application as an embedded application. There is no further communication between the launched configuration UI application and Positioning Settings. Once the configuration UI application is closed the UI control returns back to the previous settings view.

Since the discovery and launching is done through the framework provided, there is no need to implement any interface. Hence, there are no interfaces to be inherited or implemented for the configuration UI application to use this API.

Use cases

PSY Configuration UI Plug-in API can be used to:

  • Provide a Configuration UI application for a PSY module.

API class structure

PSY Configuration UI Plug-in API is based on the service discovery mechanism. The API defines a Service UID that must be used by the client applications in their resource files. Hence, there is no class structure defined for this API.

Using PSY Configuration UI Plug-in API

PSY Configuration UI Plug-in API can be used by a PSY module developer who intends to provide a Configuration UI for the PSY module.

Provide a Configuration UI application for a PSY module

In order to implement this plug-in, the PSY Configuration UI application needs to perform two steps:

1. Specify the service UID that is exported by PSY Configuration UI Plug-in API in the application registration file.

2. Specify the ECOM implementation UID of the PSY for which this application is a configuration UI application in the ECOM registration file.

Specifying service UID

The application registration information for a UI application is specified in the application's registration resource file usually named as <appname>_reg.rss. This resource file consists of an APP_REGISTRATION_INFO structure that contains the application’s name, main resource file path and its capabilities.

The structure also specifies a service_list parameter that consists of a list of SERVICE_INFO structures. The SERVICE_INFO structure consists of two fields, namely uid and opaque_data. The uid field should contain the UID definition for the service, i.e. KLocPsyConfigServiceUid implying that this application implements the PSY Configuration UI service. KLocPsyConfigServiceUid is defined in the header file LocPsyConfigUiUID.hrh that is exported by PSY Configuration UI Plug-in API as a Domain API.

Related APIs
  • KLocPsyConfigServiceUid

Specifying PSY UID

The SERVICE_INFO also contains an opaque_data field that contains the UID of the PSY for which the concerned application is a configuration UI application.

The opaque_data field points to a resource in the main resource file which is a definition of the structure PSYCONFIG_REGISTRATION. This structure is defined in the header file LocPsyConfigUi.rh that is exported by PSY Configuration UI Plug-in API.

The PSYCONFIG_REGISTRATION structure is defined in the application’s main resource file usually named <appname>_reg.rss. The structure contains a single field, psy_uid. The psy_uid field value should contain the ECOM Implementation UID of the PSY for which the configuration UI application is being designed. See reference document [2] for further information about the ECOM Implementation UID for a PSY.

The resource name used for the PSYCONFIG_REGISTRATION resource structure definition should be used in the opaque_data field in the SERVICE_INFO structure.

Positioning Settings uses the service discovery mechanism to find the applications that implement the published service UID, i.e. KLocPsyConfigServiceUid. The application information obtained from the discovery is used to launch the PSY configuration UI application as an embedded application. Once the PSY configuration UI application is closed the UI control returns back to the previous settings view.

Related APIs
  • KLocPsyConfigServiceUid

Code example

The following example depicts the usage of PSY Configuration UI Plug-in API.

In the application registration resource file the APP_REGISTRATION_INFO should be defined as shown below.

#include <LocPsyConfigUiUID.hrh>

RESOURCE APP_REGISTRATION_INFO
    {
    …
    service_list = 
        {
            SERVICE_INFO 
            {
                uid = KLocPsyConfigServiceUid;
                opaque_data = R_SIMPSYUI_REG_INFO;
            }
        };
    }

The application resource file should contain the definition for R_SIMPSYUI_REG_INFO resource as shown below.

#include <LocPsyConfigUi.rh>

RESOURCE PSYCONFIG_REGISTRATION r_simpsyui_reg_info
    {
    psy_uid=0x101F7A81; // Simulation PSY module ECOM Implementation UID
    }

The example code shown above shows the values for Simulation PSY Configurator application which is a reference implementation for this API. The psy_uid field contains the UID value for Simulation PSY. This value should be replaced with the ECOM Implementation UID for the PSY for which the configuration UI application is being developed. The name of the PSYCONFIG_REGISTRATION resource structure should be specified in the opaque_data field in the SERVICE_INFO structure.

Error handling

The API defines a Service UID that must be used by the client applications in their resource files. Hence, there is no specific run time error handling required in the usage of this API.

Memory overhead

The API defines a Service UID that must be used by the client applications in their resource files. Hence, there is no additional run time memory overhead in the usage of this API.

Extensions to the API

There are no extensions defined to the PSY Configuration UI Plug-in API.

Glossary

Abbreviations

PSY

Positioning System.

Definitions

ECOM

EPOC Component Object Model. A mechanism for loading plug-in DLLs.

UID

Unique ID allocated for specific purposes.

References

[1] Positioning Plug-in API Specification Document

[2] Positioning Plug-in Information API Specification Document