CopperSpice DBUS  1.7.4
DBus Adaptor Example

BROOM - compile before release

The following example shows how a D-Bus interface can be implemented using an adaptor.

class MainApplicationAdaptor : public QDBusAbstractAdaptor
{
CS_OBJECT(MainApplicationAdaptor)
CS_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
CS_PROPERTY_READ(caption, caption)
CS_PROPERTY_WRITE(caption, setCaption)
CS_PROPERTY_READ(organizationName, organizationName)
CS_PROPERTY_READ(organizationDomain, organizationDomain)
public:
MainApplicationAdaptor(QApplication *application)
: QDBusAbstractAdaptor(application), m_app(application)
{
connect(m_app, &QApplication::aboutToQuit,
this, &MainApplicationAdaptor::aboutToQuit);
connect(m_app, &QApplication::focusChanged,
this, &MainApplicationAdaptor::focusChangedSlot);
}
QString caption()
{
if (m_app->hasMainWindow()) {
return m_app->mainWindow()->caption();
}
return QString();
}
void setCaption(const QString &newCaption)
{
if (m_app->hasMainWindow()) {
m_app->mainWindow()->setCaption(newCaption);
}
}
QString organizationName()
{
return m_app->organizationName();
}
QString organizationDomain()
{
return m_app->organizationDomain();
}
CS_SIGNAL_1(Public, void aboutToQuit())
CS_SIGNAL_2(aboutToQuit)
CS_SIGNAL_1(Public, void mainWindowHasFocus())
CS_SIGNAL_2(mainWindowHasFocus)
// four public slots
void quit()
{
m_app->quit();
}
void reparseConfiguration()
{
m_app->reparseConfiguration();
}
QString mainWindowObject()
{
if (m_app->hasMainWindow()) {
return QString("/%1/mainwindow").formatArg(m_app->applicationName());
}
return QString();
}
void setSessionManagement(bool enable)
{
if (enable) {
m_app->enableSessionManagement();
} else {
m_app->disableSessionManagement();
}
}
private:
QApplication *m_app;
// private slot
void focusChangedSlot(QWidget *, QWidget *now)
{
if (now == m_app->mainWindow()) {
emit mainWindowHasFocus();
}
}
};

The code above would create an interface that could be represented more or less in the following canonical representation:

interface org.kde.DBus.MainApplication
{
property readwrite STRING caption
property read STRING organizationName
property read STRING organizationDomain
method quit() annotation("org.freedesktop.DBus.Method.NoReply", "true")
method reparseConfiguration()
method mainWindowObject(out STRING)
method disableSessionManagement(in BOOLEAN enable)
signal aboutToQuit()
signal mainWindowHasFocus()
}

This adaptor could be used in the application's main function as follows

int main(int argc, char **argv)
{
// create the QApplication object
QApplication app(argc, argv);
// create the MainApplication adaptor:
new MainApplicationAdaptor(app);
// connect to D-Bus and register as an object:
QDBusConnection::sessionBus().registerObject("/MainApplication", app);
// add main window, etc.
[...]
app.exec();
}

Header File

The header of the example is:

class MainApplicationAdaptor: public QDBusAbstractAdaptor
{
CS_OBJECT(MainApplicationAdaptor)
CS_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")

The code does the following:

  • Declares the adaptor MainApplicationAdaptor, which descends from QDBusAbstractAdaptor
  • Declares the CopperSpice meta object data using the CS_OBJECT macro
  • Declares the name of the D-Bus interface it implements.

The properties

The properties are declared as follows:

CS_PROPERTY_READ(caption, caption)
CS_PROPERTY_WRITE(caption, setCaption)
CS_PROPERTY_READ(organizationName, organizationName)
CS_PROPERTY_READ(organizationDomain, organizationDomain)

And are implemented as follows:

QString caption()
{
if (app->hasMainWindow()) {
return app->mainWindow()->caption();
}
return QString();
}
void setCaption(const QString &newCaption)
{
if (app->hasMainWindow()) {
app->mainWindow()->setCaption(newCaption);
}
}
QString organizationName()
{
return app->organizationName();
}
QString organizationDomain()
{
return app->organizationDomain();
}

The code declares three properties: one of them is a read-write property called "caption" of string type. The other two are read-only, also of the string type.

The properties organizationName and organizationDomain are simple relays of the app object's organizationName and organizationDomain properties. However, the caption property requires verifying if the application has a main window associated with it: if there is not any, the caption property is empty. Note how it is possible to access data defined in other objects through the getter/setter functions.

The constructor

The constructor:

MyInterfaceAdaptor(QApplication *application) : QDBusAbstractAdaptor(application), app(application)
{
connect(application, SIGNAL(aboutToQuit()),
this, SLOT(aboutToQuit());
connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
this, SLOT(focusChangedSlot(QWidget*, QWidget*)));
}

The constructor does the following:

  • Initializes the base class (QDBusAbstractAdaptor) with the parent object it is related to.
  • Stores the app pointer in a member variable. Note that it would be possible to access the same object using the QDBusAbstractAdaptor::object() function, but it would be necessary to use static_cast to properly access the methods in QApplication that are not part of QObject.
  • Connects the application's signal "aboutToQuit" to its own signal "aboutToQuit".
  • Connects the application's signal "focusChanged" to a private slot for additional processing before emitting a D-Bus signal.

There is no destructor in the example. An eventual destructor could be used to emit one last signal before the object is destroyed, for instance.

Slots

The public slots in the example (which will be exported as D-Bus methods) are defined as follows:

  1. quit  This method takes no parameters and is defined to be asynchronous. That is, callers are expected to use "fire-and-forget" mechanism when calling this method, since it provides no useful reply. This is represented in D-Bus by the use of the org.freedesktop.DBus.Method.NoReply annotation.
  2. reparseConfiguration  This method, with no input or output arguments simply relays the call to the application's reparseConfiguration member function.
  3. mainWindowObject  This method takes no input parameter, but returns one string output argument, containing the path to the main window object (if the application has a main window), or an empty string if it has no main window. Note that this method could have also been written: void mainWindowObject(QString &path).
  4. setSessionManagement  This method takes one input argument (a boolean) and, depending on its value, it calls one function or another in the application.
See also
Q_NOREPLY

Signals

The signal definitions are not enough, signals have to be emitted. One way of emitting signals is to connect another signal to them so the CopperSpice signal handling system chains them automatically. This is what is done for the "aboutToQuit" signal.

When this is the case, one can use the QDBusAbstractAdaptor::setAutoRelaySignals to automatically connect every signal from the real object to the adaptor.

When simple signal-to-signal connection is not enough, you can use a private slot to do some of the work. This is what was done for the mainWindowHasFocus signal.

This private slot (which will not be exported as a method via D-Bus) was connected to the focusChanged signal in the adaptor's constructor. It is therefore able to shape the application's signal into what the interface expects it to be.