KDBusService Class

QApplication app(argc, argv);
app.setApplicationName("kuiserver");
app.setOrganizationDomain("kde.org");
// Create your D-Bus objects here
// ...
KDBusService service(KDBusService::Unique);
// If this point is reached, this is the only running instance
// i.e. org.kde.kuiserver has been registered
return app.exec();

Member Function Documentation

[explicit] KDBusService::KDBusService(KDBusService::StartupOptions options = Multiple, QObject *parent = nullptr)

Tries to register the current process to D-Bus at an address based on the application name and organization domain under the given parent.

The D-Bus service name is the reversed organization domain, followed by the application name. If options includes the Multiple flag, the application PID will be appended. For example:

app.setApplicationName("kuiserver");
app.setOrganizationDomain("kde.org");

The above will make KDBusService register as org.kde.kuiserver in Unique mode, and org.kde.kuiserver-1234 (if the process has PID 1234) in Multiple mode.

[override virtual noexcept] KDBusService::~KDBusService()

Destroys this object (but does not unregister the application).

Deleting this object before unregister() could confuse clients, who will see the service on the bus but will be unable to use the activation methods.

[signal] void KDBusService::activateActionRequested(const QString &actionName, const QVariant &parameter)

Signals that an application action actionName should be triggered with the given parameter.

This signal is emitted to request handling of the respective method of the D-Bus activation. For GUI applications, the signal handler also needs to deal with any platform-specific startup ids and make sure the mainwindow is shown as well as request its activation from the window manager. See documentation of activateRequested(const QStringList &arguments, const QString &) for details.

See the desktop entry specification for more information about action activation.

[signal] void KDBusService::activateRequested(const QStringList &arguments, const QString &workingDirectory)

Signals that the application is to be activated.

If this is a Unique application, when KDBusService is constructed in subsequent instances of the application (ie: when the executable is run when an instance is already running), it will cause this signal to be emitted in the already-running instance (with the arguments passed to the duplicate instance), and the duplicate instance will then exit.

If this application's desktop file indicates that it supports D-Bus activation (DBusActivatable=true), a command launcher may also call the Activate() D-Bus method to trigger this signal. In this case, arguments will be empty.

In single-window applications, the connected signal should typically raise the window.

arguments The arguments the executable was called with, starting with the executable file name. See QCoreApplication::arguments(). This can be empty.

workingDirectory The directory from which the executable is called. This can be empty.

A typical implementation of the signal handler would be:

if (!arguments.isEmpty()) {
    commandLineParser->parse(arguments); // same QCommandLineParser instance as the one used in main()
    handleCmdLine(workingDirectory); // shared method with main(), which uses commandLineParser to handle options and positional arguments
}

For GUI applications, the handler also needs to deal with any platform-specific startup ids and make sure the mainwindow is shown as well as request its activation from the window manager. For X11, KDBusService makes the id for the Startup Notification protocol available from QX11Info::nextStartupId(), if there is one. For Wayland, KDBusService provides the token for the XDG Activation protocol in the "XDG_ACTIVATION_TOKEN" environment variable and unsets it again after the signal, if there is one. The util method KWindowSystem::updateStartupId(QWindow *window) (since KF 5.91) takes care of that. A typical implementation in the signal handler would be:

mainWindow->show();
KWindowSystem::updateStartupId(mainWindow->windowHandle());
mainWindow->raise();
KWindowSystem::activateWindow(mainWindow->windowHandle());

If you're using the builtin handling of --help and --version in QCommandLineParser, you should call parser.process(arguments) before creating the KDBusService instance, since parse() doesn't handle those (and exiting the already-running instance would be wrong anyway).

See also setExitValue().

QString KDBusService::errorMessage() const

Returns the error message from the D-Bus registration if it failed.

Note that this is only useful when specifying the option NoExitOnFailure. Otherwise the process has quit by the time you can get a chance to call this.

bool KDBusService::isRegistered() const

Returns true if the D-Bus registration succeeded.

Note that this is only useful when specifying the option NoExitOnFailure. Otherwise, the simple fact that this process is still running indicates that the registration succeeded.

[signal] void KDBusService::openRequested(const QList<QUrl> &uris)

Signals that one or more files should be opened in the application.

This signal is emitted to request handling of the respective method of the D-Bus activation. For GUI applications, the signal handler also needs to deal with any platform-specific startup ids and make sure the mainwindow is shown as well as request its activation from the window manager. See documentation of activateRequested(const QStringList &arguments, const QString &) for details.

uris The URLs of the files to open.

[since 5.33] QString KDBusService::serviceName() const

Returns the name of the D-Bus service registered by this class. Mostly useful when using the option Multiple.

This function was introduced in 5.33.

void KDBusService::setExitValue(int value)

Sets the exit value to be used for a duplicate instance.

If this is a Unique application, a slot connected to activateRequested() can use this to specify a non-zero exit value for the duplicate instance. This would typically be done if invalid command-line arguments are passed.

Note that this will only work if the signal-slot connection type is Qt::DirectConnection.

value The exit value for the duplicate instance.

[slot] void KDBusService::unregister()

Manually unregister the given serviceName from D-Bus.