Home · All 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 QCop.

Pre-defined Services

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

Requesting Services

To request a service, the calling application executes:

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

For example:

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

QCopServiceRequest::send() returns a boolean value indicating whether the service is available.

Responding to Service Requests

To respond to a service request, an application should use the QCopObjectService 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 QCopObjectService
    {
        Q_OBJECT
    public:
        WebAccessService( QObject *parent )
            : QCopObjectService( "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 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. 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 Serviceas settings. If the service can be provided by multiple applications, the service file will contain:

    Multiple = 1

in the [Service] section.

Advanced Service Functionality

The servicename of a service may contain '/', indicating that the service is actually an hierarchy of services. For example, the SetValue/v-card service is used to set v-card values, but the service is structured such that other SetValue services follow the same general protocol.