Home · All Classes · Grouped Classes · Annotated · Functions

Services

Introduction

Application Services are standardized APIs to access functionality supplied by other applications. They allow applications to invoke the services of other applications, while allowing the specific application providing the service to be selected by the system integrator or end-user. Messages between applications are delivered via Qtopia IPC.

Pre-defined Services

The following provides a list of the pre-defined services:

Requesting Services

To request a service, the calling application executes:

    QtopiaServiceRequest srv(servicename, action);
    srv << parameters;
    srv.send();

For example:

    QtopiaServiceRequest srv("WebAccess", "openURL(QString)");
    srv << QString("www.trolltech.com");
    srv.send();

QtopiaServiceRequest::send() returns a boolean value indicating whether the service is available. The next image demonstrates the service interaction if it is assumed that the mail application where to request the WebAccess service:

Responding to Service Requests

To respond to a service request, an application should use the QtopiaAbstractService class. The following example responds to the openURL(QString) request on the WebAccess service. It would typically be implemented by a Web browser application:

    class WebAccessService : public QtopiaAbstractService
    {
        Q_OBJECT
    public:
        WebAccessService( QObject *parent )
            : QtopiaAbstractService( "WebAccess", parent )
            { publishAll(); }

    public slots:
        void openURL( const QString& url );
    };

When an openURL(QString) request arrives, it will be automatically delivered to the WebAccessService::openURL() slot in the application.

Applications register as providing a service by supplying a standard Qtopia configuration file, $QPEDIR/services/<servicename>/<appname> where:

• The servicename is the directory name and the name of the service.
• The appname is the application executable filename.

The file should be installed by the build sytem. See Register a service provider for more information.

The standard keys in this file are:

• [Standard]
  • Version

    An integer: For example, 100 is interpreted as Version 1.00. Later versions of a service may support additional actions.

• [Extensions] (optional section)
  • Actions <p> Additional actions to those defined by the basic (standard) service.
• [action]

  For each entry in the Actions list above, there is a group defining properties of the action.

  • Name
  • Icon

The file may contain any additional sections, keys and values as defined by the documentation of the service.

Adding a New Service

Each new service must be carefully specified as it provides a system- wide API that can be invoked by other applications and the user. A service should only be added if it:

• Provides new functionality not already provided by a pre-defined service.
• Is useful to other applications.
• Is well-defined within the scope of the application type, e.g. openURL(QString <url>) for a web browser.
• Avoids adding unnecessary functionality which could complicate the user interface.

To add a new service, provide a standard Qtopia configuration file, $QPEDIR/services/<servicename>.service. Again this file should be installed by the build sytem. +See Create a new service for more information. The keys in this file are:

• [Service]
  • Name
  • Icon
  • Actions

    This is a list of actions separated by semicolon (;). The actions include any formal parameters in parentheses, including the case of no parameters.

• [action]

  For each entry in the Actions list above, there is a group defining properties of the action.

  An action with no parameters will appear in the list of available actions in the button settings. There is no need to add this section if the action has parameters and will not be shown to the user.

  • Name
  • Icon

For example:

    [Translation]
    File=QtopiaServices
    Context=Calendar
    [Service]
    Actions = raiseToday();newEvent()
    Icon = datebook_icon
    Name[]=Calendar
    [newEvent()]
    Icon = datebook_icon
    Name[]=New event
    [raiseToday()]
    Icon=today
    Name[]=Today's calendar

Usually, only one application responds to a given service. The user selects the application to handle the service using the Application Services settings. If the service can be provided by multiple applications, the service file will contain:

    Multiple = 1

in the [Service] section.

Advanced Service Functionality

Some services may be parameterised on the type of data to be processed. Different applications may handle different data types. The Qtopia Data Sharing (QDS) system should be used for these types of services.