Qt API | Qtopia API | Qtopia Documentation |

## Qtopia - Application Services

Application Services are standardized APIs to functionality supplied by applications. The purpose is to allow applications to invoke the services of other applications, yet allow the end-user to decide which application provides each service.

Trolltech defines the following services.

### Qtopia - Requesting Services

To request a service, the calling application executes:

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

For example:

        ServiceRequest srv("Email", "writeMail(QString,QString)");
        srv << QString("Johan R. User") << QString("random@trolltech.com");
        srv.send();

ServiceRequest::send() returns a bool value indicating whether the service is available.

### Qtopia - Responding to Service Requests

To respond to a service request, an application should connect to the QPEApplication::appMessage() signal.

Applications register as providing a service by supplying a $QPEDIR/services/servicename/appname file, where servicename is both the directory name and the name of the service and appname is the application's executable filename. This file is a standard Qtopia Config file. The keys in this file are:

- `[Standard]`
  - `Version`

    An integer. "100" should be interpretted as Version 1.00. Later versions of a service may support additional actions.

- `[Extensions]`
  - `Actions`

    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`

### Qtopia - Adding a New Service

Each service must be very carefully specified since 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 $QPEDIR/services/servicename.service file, which is a standard Qtopia Config file. 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 parantheses, 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 will not be shown to the user, i.e. has parameters.

  - `Name`
  - `Icon`

Example:

    [Service]
    Icon = DateBook
    Name = Calendar
    Name[de] = Termin kalender
    Name[hu] = Naptár
    Name[no] = Avtalebok
    Actions=raiseToday()
    [raiseToday()]
    Name=Show today's events
    Icon=today

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

    Multiple = 1

in the `[Service]` section.