KDBusService

Search for usage in LXR

#include <KDBusService>

Inheritance diagram for KDBusService:

Public Types

enum  StartupOption { Unique = 1 , Multiple = 2 , NoExitOnFailure = 4 , Replace = 8 }
 
typedef QFlags< StartupOptionStartupOptions
 
- Public Types inherited from QObject
typedef  QObjectList
 

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 () override
 
QString errorMessage () const
 
bool isRegistered () const
 
QString serviceName () const
 
void setExitValue (int value)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
QBindable< QStringbindableObjectName ()
 
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 () const const
 
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 QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isQuickItemType () const const
 
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_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_GADGET_EXPORT (EXPORT_MACRO)
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_MOC_INCLUDE Q_MOC_INCLUDE
 
 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
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setObjectName (QAnyStringView name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool setProperty (const char *name, QVariant &&value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds interval, 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 *context, Functor functor, 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)
 
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, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
- 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 entry (DBusActivatable=true) in their desktop files will 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();
KDBusService takes care of registering the current process with D-Bus.
@ Unique
Indicates that only one instance of this application should ever exist.
Since
5.0

Definition at line 80 of file kdbusservice.h.

Member Typedef Documentation

◆ StartupOptions

Stores a combination of StartupOption values.

Definition at line 128 of file kdbusservice.h.

Member Enumeration Documentation

◆ StartupOption

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 89 of file kdbusservice.h.

Constructor & Destructor Documentation

◆ KDBusService()

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 269 of file kdbusservice.cpp.

◆ ~KDBusService()

KDBusService::~KDBusService ( )
overridedefault

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.

Member Function Documentation

◆ activateActionRequested

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

Signals that an application action should be triggered.

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.

◆ activateRequested

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 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());
static Q_INVOKABLE void activateWindow(QWindow *window, long time=0)
static void updateStartupId(QWindow *window)

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()

◆ errorMessage()

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 287 of file kdbusservice.cpp.

◆ isRegistered()

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 282 of file kdbusservice.cpp.

◆ openRequested

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

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.

Parameters
urisThe URLs of the files to open.

◆ serviceName()

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 297 of file kdbusservice.cpp.

◆ setExitValue()

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 292 of file kdbusservice.cpp.

◆ unregister

void KDBusService::unregister ( )
slot

Manually unregister the given serviceName from D-Bus.

Definition at line 302 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-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:14:09 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.