Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia Application Services

- Introduction
- Requesting Services
- Responding to Service Requests
- Adding a New Service
- Pre-Defined Services
  - Document Oriented services
  - EMail services
  - WebAccess services
  - PlayMedia services
  - Contacts services
  - Calendar services
  - Tasks services
  - TimeMonitor services
  - CleanupWizard services

## Introduction

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.

## 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.

## 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`

## 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:

    [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 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.

## Pre-Defined Services

The services below are defined by Trolltech as basic services that may be available on a Qtopia device, and the messages which such services handle.

All services respond to the following messages:

- raise() Bring a user interface for the service to the top of the window stack.
- quit() Remove any user interface for the service. Note that sending this message when the service is not started will start the service (and immediately terminate it).

### Document Oriented services

The following actions are defined for document oriented services:

- Open/mimetype
  - setDocument(QString document)
  - openFile(QString filepath) Version 1.01 only
- View/mimetype
  - setDocument(QString document)
  - viewFile(QString filepath) Version 1.01 only
- Receive/mimetype
  - receiveData(QString filename, QString type)
    - filename = name of file containing data
    - type = MIME type of the data

    The service should delete the file after reading it.

### EMail services

- writeMail() In response to this message, the Email service interacts with the user to complete the email message, and then, if confirmed by the user, send the email message.
- writeMail(QMap(QString,QString) values)
  - values = set of header names -> value mappings (eg. names are "To", "Subject"), plus optionally a "BODY" -> value mapping giving the body content, plus optionally a "ATTACHMENT<n>" -> value mapping. The attachments value is ...
  In response to this message, the Email service interacts with the user to complete the email message, and then, if confirmed by the user, send the email message.
- writeMail(QString name,QString email)
  - name = the name of the recipient, or the empty string.
  - email = the email address of the recipient.
  In response to this message, the Email service interacts with the user to complete the email message, and then, if confirmed by the user, send the email message.
- cleanupMessages(QDate date, int size)
  - date = only include messages that are older than date
  - size = the minimal mail size
  In response to this message, the Email service will purge all messages which are older than the given date and exceed the minimal mail size.

### WebAccess services

- openURL(QString url)
  - url = a fully-specified URL
  In response to this message, the WebAccess service retrieves the resource specified by the URL and either displays it to the user, invokes further services to display the resource, or notifies the user that no facility exists for displaying the resource. If the resource cannot be retrieved, the WebAccess notifies the user.
- retrieveURL(QString url)
  - url = a fully-specified URL
  In response to this message, the WebAccess service retrieves the resource specified by the URL, creates a document containing the resource. Then, if services exist to display the document, the WebAccess service gives the user the option to display the document. If the resource cannot be retrieved, the WebAccess notifies the user.
- getURL(QString url, QString doclnk)
  - url = a fully-specified URL
  - doclnk = the filename of a .desktop file
  In response to this message, the WebAccess service retrieves the resource specified by the URL, creates a document containing the resource using the given doclnk as the document link file. The document is created even if the resource could not be retrieved. As a result of creating the document, Qtopia will send the QPE/System linkChanged(QString) message, with the doclnk as the argument.

### PlayMedia services

- openURL(QString url, QString mimetype)
  - url = a fully-specified URL
  - mimetype = the mimetype of the media file.

### Contacts services

- addContact(PimContact)
- addAndEditContact(PimContact)
- removeContact(PimContact)
- updateContact(PimContact)
- showContact(PimContact)
- beamBusinessCard()

### Calendar services

- raiseToday()
- newEvent()
- newEvent(QDataTime,QDataTime,QString,QString)
- showEvent(QUuid)
- showEvent(QUuid,QDate)
- newEvent(QDateTime start, QDateTime end, QString description, QString notes)
  - start = start time for the event (invalid = use default)
  - end = start time for the event (invalid = use default)
  - description = one-line description of the event
  - notes = detailed notes for the event

### Tasks services

- newTask()
- addTask(PimTask)
- removeTask(PimTask)
- updateTask(PimTask)
- showTask(QUuid)

### TimeMonitor services

- timeChange(QString timezone_id)
  - timezone_id = the new TimeZone id.

### CleanupWizard services

- showCleanupWizard()