Example of updating event feed with a D-Bus call

The most common scenarios for event feed updates are when user interactions trigger the update or when a scheduled update from the Synchronization Framework plugin occurs. However, the request to refresh feed content can also originate from the Events View, for example, when the device user taps the refresh button.

When the refresh requests come from the Events View, the Events View and the application that generates the feed communicate over D-Bus. To facilitate this, the application needs to do the following:

• implement and register a D-Bus service
• register its D-Bus method as refreshAction for the Events View with a D-Bus call
• (optional) Set the application to launch when a refresh request is received

These steps are described below.

Implementing the D-Bus service

To implement the D-Bus service, follow these steps:

1. Create an XML file that contains a refresh method for a desired interface. This example creates a file called example.xml with the following content:

<!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.mycompany.example">
    <method name="refresh" />
 </interface>
</node>

2. Use the qdbusxml2cpp auto-converter included with the Qt SDK to generate a C++ wrapper class based on that with the following command:

qdbusxml2cpp example.xml -a exampleadaptor -c ExampleAdaptor -l Example -i example.h

With the above line, qdbusxml2cpp generates an ExampleAdaptor class that uses Example as its parent class and creates an #include line for example.h header file. The Example class and the example.h header file are created later.

The generated file looks like this:

class ExampleAdaptor: public QDBusAbstractAdaptor
{
public:
    ExampleAdaptor(Example *parent);
    virtual ~ExampleAdaptor();

    inline Example *parent() const
    {
       return static_cast<Example *>(QObject::parent()); 
    }

public: // PROPERTIES
public Q_SLOTS: // METHODS
    void refresh();
Q_SIGNALS: // SIGNALS
};

Example is your own class that is defined in example.h. Example implements the refresh action (as defined in the XML file earlier) that is called when Events View requests a refresh.

3. Initialize the class with the following lines in the example.h header file:

class Example : public QObject
{
// ...
signals:
    void refresh();
// ...
}

4. Within the application that generates the event feed items, you must create an instance of the Example class and the corresponding generated D-Bus wrapper class (ExampleAdaptor in this case). To register your application in the session bus, use the following:

QDBusConnection bus = QDBusConnection::sessionBus();
example = new Example;
new ExampleAdaptor(example);
bus.registerService("com.mycompany.example");
bus.registerObject("/path", example);

Note that all names match with the ones in the XML file. After this step you have a D-Bus service running with the following parameters:

• service: com.mycompany.example
• path: /path
• interface: com.mycompany.example
• method: refresh()

You can build, deploy and test your new D-Bus service by calling it from the device Terminal application with the following command:

qdbus com.mycompany.example /path com.mycompany.example refresh

Registering the service to Events View refresh events

After you have a working D-Bus service, you must register its refresh action to the event feed in the Events View with the following steps:

1. Input your D-Bus service parameters into a MRemoteAction instance. For more information, see MRemoteAction in Platform API reference.

2. Create a QDBusInterface object that uses the MEventFeed interface to send event updates.

3. Make a D-Bus call to addRefreshAction method:

#include <MRemoteAction>

    MRemoteAction action("com.mycompany.example", "/path", "com.mycompany.example", "refresh");
    QDBusInterface interface("com.nokia.home.EventFeed", "/eventfeed", "com.nokia.home.EventFeed", QDBusConnection::sessionBus());
    interface.call(QDBus::NoBlock, "addRefreshAction", action.toString());

4. Since MRemoteAction is a MeeGo Touch class, add the following line into your project file:

CONFIG += meegotouch

Your new D-Bus service is now registered to receive refresh requests.

Starting your D-Bus service automatically

Normally, your application is not running all the time. If you want your application to start up automatically when an event feed refresh request occurs, you must define it in a D-Bus .service file. The .service file notifies the device system which executable must be run when the D-Bus call (for com.mycompany.example in this example) is received.

With the names and parameters used in this example, and an application installed in /opt/exampleapplication/bin/exampleapplication, the .service file looks like this:

com.mycompany.example.service:

[D-BUS Service]
Name=com.mycompany.example
Exec=/usr/bin/invoker --type=d /opt/exampleapplication/bin/exampleapplication

To install the .service file to the correct location, add the following lines into the project file:

dbusservice.path = /usr/share/dbus-1/services
dbusservice.files = <location of the .service file on your host workstation>

INSTALLS += dbusservice