Qtopia Application 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:
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]
- [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.
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
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()
- 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
Copyright © 2001-2005 Trolltech
| Trademarks
| Qtopia version 2.1.1
|