MeeGo Touch: Service Framework

Introduction

The service framework is an IPC mechanism that allows applications to simply either use or serve an interface. For the purposes of this documentation, the interface user process is referred to as 'user' and the interface provider process is referred to as the 'provider'.

The objectives of the service framework are :

to provide an IPC mechanism that is simple to use,
to ensure there is no run time binary dependancy between the service user and provider,
to allow the user to just use an interface and not worry about the logic of choosing or connecting to an interface,
to allow the user to query a list of providers and choose one of them.

The basic service framework mechanism.

The above diagram shows what happens behind the scenes when a Service User (SU) uses an Interface (IF).

The service user instantiates an interface which causes the interface to ask the servicemapper (a dedicated dbus service) for the name of a service provider that implements that interface.
The service mapper has been maintaining a map of services<->interfaces (by watching the dbus services directory, typically /usr/share/dbus-1/services) and has rules to determine which one to pick. It picks a service and returns the name to the interface in SU.
The interface in SU then makes a regular dbus connection to the given service name and calls the appropriate method.

The service mapper will send signals to the corresponding SU interfaces to inform them when there is a new SP for the IF, or if there are no more SPs for the IF. The application should connect to the signals in the IF in order to tell when these events occur and to take appropriate action. For example, a gallery application may wish to allow a user to send a photo via email and it might listen to the 'no more SP for IF' signal in order to tell when to disable the option.

Typical usecases for the Service Framework

Launch/Display a certain view of an application from another application or applet in experience canvas
Get a list/thumbnails of available video content on the device
Launch a web-browser displaying a certain web-page
Choose/Display some image from available content
Show recent contacts
Show calendar appointments for 13. friday 2042

Service Framework should not be used for generic IPC communication purposes or, for example, communication between applets. This should be done using other means like using a data backend that provides notifications of changes to values like MValueSpace.

Usage

As a Service Provider (SP)

Two things are required of the developer of an SP :

Binary

This is the binary that will be launched (if it is not already running) when a Service User application tries to connect to the service.

Interface

This consists of the files needed by the developer of a Service User application. It consists of :

mservicefwbaseif.h/cpp files that are common to all interfaces.
The mservicefwbaseif.h file is part of the libmeegotouch-dev package and the mservicefwbaseif.cpp is compiled into libmeegotouch itself and so is part of the libmeegotouchcore0 package.
XML file, header files, a library and a .service file for the interface being supplied.
The interface specific header files should be made part of the maemo-interfaces-dev package along with the interface's XML file, and the corresponding cpp files compiled into interface specific libs that are made part of the maemo-interfaces package. The .service file should also be made part of the maemo-interfaces package.

Binary

Create an XML file that defines the interface.

If you wish a method to be chained to the current application, you can add a 'chainTask="true"' attribute to the method tag. If you wish a method to be asynchronous, you can add an 'asyncTask="true"' attribute to the method tag. Note that such methods must not have any 'out' parameters.

For example:

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
    <interface name="com.nokia.TextProcessorInterface">
        <method name="reverse" chainTask="true">
            <arg name="message" type="s" direction="in"/>
            <arg name="" type="s" direction="out"/>
        </method>
        <method name="blinkScreen" asyncTask="true">
            <arg name="message" type="s" direction="in"/>
        </method>
    </interface>
</node>

Run the m-servicefwgen tool to generate the adaptor h and cpp files, for example :
```
m-servicefwgen -a com.nokia.TextProcessorInterface
```

Change your code.

There are three steps that are illustrated in the following code snippet :

// 1. Make an instance of the class that has methods that implement the interface functionality
MyService myService;

// 2. Make an adaptor to link the dbus methods with the methods in myService
// According to QDBusAbstractAdaptor(), this must be on the heap,
// and memory is owned by QDBusAbstractAdaptor, so no need to keep pointer
new MyServiceIfAdaptor( &myService );

// 3. Connect to session bus and register this service
QDBusConnection connection = QDBusConnection::sessionBus();
bool ret = connection.registerService("com.nokia.TextProcessor");

// continue with rest of app
return app.exec();

Interface

There are three steps to defining an interface.

Create an XML file defining the interface - this is the same XML file as described above.
Run the m-servicefwgen tool to generate the proxy header and cpp files, and the wrapper header file. For example :
```
m-servicefwgen -p com.nokia.TextProcessorInterface
```
You need to generate the service libraries.

The above files should be made part of the maemo-interfaces package. The library should be in maemo-interfaces, and the header and xml files should be in maemo-interfaces-dev.

Documentation for an interface and its methods can be added between '<doc>' and '</doc>' tags, as follows :

    <interface name="com.nokia.someserviceinterface">
        <doc>
            <arg tag="brief">brief documentation for the interface</arg>
            <arg tag="details">detailed documentation for the interface</arg>
        </doc>
        <method name="showPage">
            <doc>
                <arg tag="brief">brief documentation for showPage() method</arg>
                <arg tag="details">detailed documentation for showPage() method</arg>
            </doc>
            <arg name="targetPage" type="s" direction="in" />
            <arg name="previousPage" type="s" direction="in" />
            <arg name="" type="b" direction="out"/>    
        </method>
        ....etc

As a Service User

Install the libmeegotouch-dev and libmeegotouch-bin debian packages. This gives you the service mapper dbus daemon, headers, and lib.
Install the maemo-meegotouch-interfaces-dev package (incudes the proxy header and lib, and the wrapper header file).
Add -lmeegotouch and -l<interfacename> to LIBS in your project file.
In your source, include the interface header file and create an instance of the interface and call method serviceName() to get the provider for the interface.
Check to see if the service was found OK using the 'isValid()' method.
Call the interface method(s) as desired/appropriate.
Implement and connect slots to handle the 'serviceAvailable()', 'serviceUnavailable()' and 'serviceChanged()' signals sent by the service mapper.

Demos and example code

In libmeegotouch/demos/servicefw/ there is example code showing three service providers and a service user. The com.nokia.textprocessor and org.maemo.textprocessor services both implement the same interface - com.nokia.TextProcessorInterface. There are two services so that we are able to remove services and see that the service user is switched from one service to another/etc. There is one script tools/m-servicefwgen, which is used to generate the source files that are used to define the interface to the service user. To run this demo :

cd libmeegotouch
qmake && make && make install (or at least do a make install in the mservicemapper directory)
cd demos/servicefw
pushd misc; sudo ./INSTALL; popd (this will install the relevant dbus service files into /usr/share/dbus-1/services)
LD_LIBRARY_PATH=lib bin/user
This will open a small window that will allow you to enter text which will be sent through the interface to a service which will return the reversed text.

In this demo, you can remove the various service files from /usr/share/dbus-1/services to simulate the service being removed (and added again) and see that the service user application 'does the right thing'.