KDBusService

#include <KDBusService>

Inheritance diagram for KDBusService:

Public Types

enum  StartupOption { Unique = 1, Multiple = 2, NoExitOnFailure = 4, Replace = 8 }
 
typedef QFlags< StartupOptionStartupOptions
 

Signals

void activateActionRequested (const QString &actionName, const QVariant &parameter)
 
void activateRequested (const QStringList &arguments, const QString &workingDirectory)
 
void openRequested (const QList< QUrl > &uris)
 

Public Slots

void unregister ()
 

Public Member Functions

 KDBusService (StartupOptions options=Multiple, QObject *parent=nullptr)
 
 ~KDBusService ()
 
QString errorMessage () const
 
bool isRegistered () const
 
QString serviceName () const
 
void setExitValue (int value)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

KDBusService takes care of registering the current process with D-Bus.

This registers the application at a predictable location on D-Bus, registers the QCoreApplication (or subclass) object at /MainApplication, and assists in implementing the application side of D-Bus activation from the Desktop Entry Specification.

An application can either work in Multiple mode or Unique mode.

In Multiple mode, the application can be launched many times. The service name in the D-Bus registration will contain the PID to distinguish the various instances; for example: org.kde.konqueror-12345.

In Unique mode, only one instance of this application can ever run. The first instance of the application registers with D-Bus without the PID, and any attempt to run the application again will cause the activateRequested() signal to be emitted in the already-running instance; the duplicate instance will then quit. The exit value can be set by the already running instance with setExitValue(), the default value is 0.

Unique-mode applications should usually delay parsing command-line arguments until after creating a KDBusService object; that way they know they are the original instance of the application.

Applications that set the D-Bus activation entries in their desktop files should use Unique mode and connect to the signals emitted by this class. Note that the D-Bus interface is exported for Multiple-mode applications as well, so it also makes sense for such applications to connect to the signals emitted by this class.

Note
In order to avoid a race, the application should export its objects to D-Bus before allowing the event loop to run (for example, by calling QCoreApplication::exec()). Otherwise, the application will appear on the bus before its objects are accessible via D-Bus, which could be a problem for other applications or scripts which start the application in order to talk D-Bus to it immediately.

Example usage:

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

Definition at line 78 of file kdbusservice.h.

Member Typedef Documentation

Stores a combination of StartupOption values.

Definition at line 126 of file kdbusservice.h.

Member Enumeration Documentation

Options to control the behaviour of KDBusService.

See also
StartupOptions
Enumerator
Unique 

Indicates that only one instance of this application should ever exist.

Cannot be combined with Multiple.

Multiple 

Indicates that multiple instances of the application may exist.

Cannot be combined with Unique. This is the default.

NoExitOnFailure 

Indicates that the application should not exit if it failed to register with D-Bus.

If not set, KDBusService will quit the application if it failed to register the service with D-Bus or a Unique instance can not be activated. A Multiple instance will exit with error code 1. The exit value of a Unique instance can be set from the running instance with setExitValue(), the default value is 0.

Replace 

Indicates that if there's already a unique service running, to be quit and replaced with our own.

If exported, it will try first quitting the service calling org.qtproject.Qt.QCoreApplication.quit, which is exported by KDBusService by default.

Since
5.65

Definition at line 87 of file kdbusservice.h.

Constructor & Destructor Documentation

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

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

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");

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.

Definition at line 248 of file kdbusservice.cpp.

KDBusService::~KDBusService ( )

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

Deleting this object before unregister() is called (either manually or because QCoreApplication::aboutToQuit() was emitted) could confuse clients, who will see the service on the bus but will be unable to use the activation methods.

Definition at line 258 of file kdbusservice.cpp.

Member Function Documentation

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

Signals that an application action should be triggered.

See the desktop entry specification for more information.

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

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, args will be empty.

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

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

A typical implementation of the slot 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
}
// and for GUI applications, also terminate startup notification and activate the mainwindow:
KWindowSystem::forceActiveWindow(mainWindow->winId());

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.

Definition at line 268 of file kdbusservice.cpp.

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.

Definition at line 263 of file kdbusservice.cpp.

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

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

Parameters
urisThe URLs of the files to open.
QString KDBusService::serviceName ( ) const

Returns the name of the D-Bus service registered by this class.

Mostly useful when using the option Multiple.

Since
5.33

Definition at line 278 of file kdbusservice.cpp.

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.

Parameters
valueThe exit value for the duplicate instance.

Definition at line 273 of file kdbusservice.cpp.

void KDBusService::unregister ( )
slot

Unregister from D-Bus.

This is called automatically when the application is about to quit, to make sure it doesn't keep receiving calls to its D-Bus interface while it is doing final cleanups.

Definition at line 283 of file kdbusservice.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Jun 5 2020 22:42:02 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.