CopperSpice DBUS  1.7.4
QDBusServiceWatcher Class Reference

The QDBusServiceWatcher class allows the user to watch for a bus service change. More...

Inherits QObject.

Public Typedefs

using WatchMode = QFlags< WatchModeFlag >
 

Public Types

enum  WatchModeFlag
 

Public Signals

void serviceOwnerChanged (const QString &serviceName, const QString &oldOwner, const QString &newOwner)
 
void serviceRegistered (const QString &serviceName)
 
void serviceUnregistered (const QString &serviceName)
 

Public Methods

 QDBusServiceWatcher (const QString &serviceName, const QDBusConnection &connection, WatchMode watchMode=WatchForOwnerChange, QObject *parent=nullptr)
 
 QDBusServiceWatcher (QObject *parent=nullptr)
 
 ~QDBusServiceWatcher ()
 
void addWatchedService (const QString &newService)
 
QDBusConnection connection () const
 
bool removeWatchedService (const QString &serviceName)
 
void setConnection (const QDBusConnection &connection)
 
void setWatchedServices (const QStringList &services)
 
void setWatchMode (WatchMode mode)
 
QStringList watchedServices () const
 
WatchMode watchMode () const
 

Properties

 watchMode
 

Detailed Description

The QDBusServiceWatcher class allows the user to watch for a bus service change. A QDBusServiceWatcher object can be used to notify the application about an ownership change of a service name on the bus. It has three watch modes:

  • Watching for service registration only.
  • Watching for service unregistration only.
  • Watching for any kind of service ownership change (the default mode).

Besides being created or deleted, services may change owners without a unregister/register operation happening. So the serviceRegistered() and serviceUnregistered() signals may not be emitted if that happens.

This class is more efficient than using the QDBusConnectionInterface::serviceOwnerChanged() signal because it allows one to receive only the signals for which the class is interested in.

See also
QDBusConnection

Member Typedef Documentation

Typedef for QFlags<WatchModeFlag>. Refer to QDBusServiceWatcher::WatchModeFlag for documentation.

Member Enumeration Documentation

ConstantValueDescription
DBusServiceWatcher::WatchForRegistration 0x01 Watch for service registration only, ignoring any signals related to other service ownership change.
QDBusServiceWatcher::WatchForUnregistration 0x02 Watch for service unregistration only, ignoring any signals related to other service ownership change.
QDBusServiceWatcher::WatchForOwnerChange 0x03 Watch for any kind of service ownership change.

Constructor & Destructor Documentation

QDBusServiceWatcher::QDBusServiceWatcher ( QObject *  parent = nullptr)
explicit

Creates a QDBusServiceWatcher object. Until you set a connection by calling setConnection(), this object will not emit any signals. The parent parameter is passed to QObject to set the parent of this object.

QDBusServiceWatcher::QDBusServiceWatcher ( const QString &  serviceName,
const QDBusConnection connection,
WatchMode  watchMode = WatchForOwnerChange,
QObject *  parent = nullptr 
)

BROOM - where tis serviceName?

Creates a QDBusServiceWatcher object and attaches it to the connection. This method immediately starts watching for watchMode changes to service. The parent parameter is passed to QObject to set the parent of this object.

QDBusServiceWatcher::~QDBusServiceWatcher ( )

Destroys the QDBusServiceWatcher object and releases any resources associated with it.

Method Documentation

void QDBusServiceWatcher::addWatchedService ( const QString &  newService)

Adds newService to the list of services to be watched by this object. This function is more efficient than setWatchedServices() and should be used whenever possible to add services.

QDBusConnection QDBusServiceWatcher::connection ( ) const

Returns the QDBusConnection that this object is attached to.

See also
setConnection()
bool QDBusServiceWatcher::removeWatchedService ( const QString &  serviceName)

Removes the serviceName from the list of services being watched by this object. Note that D-Bus notifications are asynchronous, so there may still be signals pending delivery about service. Those signals will still be emitted whenever the D-Bus messages are processed.

Returns true if any services were removed.

void QDBusServiceWatcher::serviceOwnerChanged ( const QString &  serviceName,
const QString &  oldOwner,
const QString &  newOwner 
)
signal

This signal is emitted whenever this object detects that there was a service ownership change relating to the serviceName service. The oldOwner parameter contains the old owner name and newOwner is the new owner. Both oldOwner and newOwner are unique connection names.

This signal is also emitted whenever the serviceName service was registered or unregistered. If it was registered, oldOwner will contain an empty string, whereas if it was unregistered, newOwner will contain an empty string.

If you need only to find out if the service is registered or unregistered only, without being notified that the ownership changed, consider using the specific modes for those operations. This class is more efficient if you use the more specific modes.

See also
serviceRegistered(), serviceUnregistered()
void QDBusServiceWatcher::serviceRegistered ( const QString &  serviceName)
signal

This signal is emitted whenever this object detects the service matching the given serviceName becames available on the bus.

See also
serviceUnregistered(), serviceOwnerChanged()
void QDBusServiceWatcher::serviceUnregistered ( const QString &  serviceName)
signal

This signal is emitted whenever this object detects that the service serviceName was unregistered from the bus and is no longer available.

See also
serviceRegistered(), serviceOwnerChanged()
void QDBusServiceWatcher::setConnection ( const QDBusConnection connection)

Sets the D-Bus connection that this object is attached to be connection. All services watched will be transferred to this connection.

Note that QDBusConnection objects are reference counted: QDBusServiceWatcher will keep a reference for this connection while it exists. The connection is not closed until the reference count drops to zero, so this will ensure that any notifications are received while this QDBusServiceWatcher object exists.

See also
connection()
void QDBusServiceWatcher::setWatchedServices ( const QStringList &  services)

Sets the list of D-Bus services being watched to be services.

Setting the entire list means removing all previous rules for watching services and adding new ones. This is an expensive operation and should be avoided, if possible. Instead, use addWatchedService() and removeWatchedService() if you can to manipulate entries in the list.

See also
watchedServices()
void QDBusServiceWatcher::setWatchMode ( WatchMode  mode)

Sets the value of the property to mode.

QStringList QDBusServiceWatcher::watchedServices ( ) const

Returns the list of D-Bus services that are being watched.

See also
setWatchedServices()
WatchMode QDBusServiceWatcher::watchMode ( ) const

Returns the value of the property.

Property Documentation

QDBusServiceWatcher::watchMode

This property holds the current watch mode for this QDBusServiceWatcher object. The default value for this property is QDBusServiceWatcher::WatchForOwnershipChange.

PropertiesClass Methods
read watchMode
write setWatchMode