summaryrefslogtreecommitdiffstats
path: root/src/dbus
diff options
context:
space:
mode:
authorThiago Macieira <thiago.macieira@nokia.com>2009-10-26 14:16:47 (GMT)
committerThiago Macieira <thiago.macieira@nokia.com>2009-10-28 09:17:18 (GMT)
commitbd9a8091eb8c731569e4972a04f23c9a2f48391c (patch)
tree7b7232f7bdf4234466cddec86bfdb8cdf1b0ee05 /src/dbus
parentf9b55c5263ba25e707c8cc35988935a804af2f50 (diff)
downloadQt-bd9a8091eb8c731569e4972a04f23c9a2f48391c.zip
Qt-bd9a8091eb8c731569e4972a04f23c9a2f48391c.tar.gz
Qt-bd9a8091eb8c731569e4972a04f23c9a2f48391c.tar.bz2
Doc: add documentation for QDBusServiceWatcher class.
Diffstat (limited to 'src/dbus')
-rw-r--r--src/dbus/qdbusservicewatcher.cpp163
1 files changed, 163 insertions, 0 deletions
diff --git a/src/dbus/qdbusservicewatcher.cpp b/src/dbus/qdbusservicewatcher.cpp
index d8a33c3..4872732 100644
--- a/src/dbus/qdbusservicewatcher.cpp
+++ b/src/dbus/qdbusservicewatcher.cpp
@@ -138,26 +138,159 @@ void QDBusServiceWatcherPrivate::removeService(const QString &service)
SLOT(_q_serviceOwnerChanged(QString,QString,QString)));
}
+/*!
+ \class QDBusServiceWatcher
+ \since 4.6
+ \inmodule QtDBus
+
+ \brief 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:
+
+ \list
+ \o watching for service registration only
+ \o watching for service unregistration only
+ \o watching for any kind of service ownership change (the default mode)
+ \endlist
+
+ Besides being created or deleted, services may change owners without a
+ unregister/register operation happening. So the \ref serviceRegistered()
+ and \ref 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.
+
+ \sa QDBusConnection
+*/
+
+/*!
+ \enum QDBusServiceWatcher::WatchModeFlag
+
+ QDBusServiceWatcher supports three different watch modes, which are configured by this flag:
+
+ \value WatchForRegistration watch for service registration only, ignoring
+ any signals related to other service ownership change.
+
+ \value WatchForUnregistration watch for service unregistration only,
+ ignoring any signals related to other service ownership change.
+
+ \value WatchForOwnerChange watch for any kind of service ownership
+ change.
+*/
+
+/*!
+ \property QDBusServiceWatcher::watchMode
+
+ The \c watchMode property holds the current watch mode for this
+ QDBusServiceWatcher object. The default value for this property is
+ QDBusServiceWatcher::WatchForOwnershipChange.
+*/
+
+/*!
+ \property QDBusServiceWatcher::watchedServices
+
+ The \c servicesWatched property holds the list of services watched.
+
+ Note that modifying this list with setServicesWatched() is an expensive
+ operation. If you can, prefer to change it by way of addWatchedService()
+ and removeWatchedService().
+*/
+
+/*!
+ \fn void QDBusServiceWatcher::serviceRegistered(const QString &serviceName)
+
+ This signal is emitted whenever this object detects that the service \a
+ serviceName became available on the bus.
+
+ \sa serviceUnregistered(), serviceOwnerChanged()
+*/
+
+/*!
+ \fn void QDBusServiceWatcher::serviceUnregistered(const QString &serviceName)
+
+ This signal is emitted whenever this object detects that the service \a
+ serviceName was unregistered from the bus and is no longer available.
+
+ \sa serviceRegistered(), serviceOwnerChanged()
+*/
+
+/*!
+ \fn void QDBusServiceWatcher::serviceOwnerChanged(const QString &serviceName, const QString &oldOwner, const QString &newOwner)
+
+ This signal is emitted whenever this object detects that there was a
+ service ownership change relating to the \a serviceName service. The \a
+ oldOwner parameter contains the old owner name and \a newOwner is the new
+ owner. Both \a oldOwner and \a newOwner are unique connection names.
+
+ Note that this signal is also emitted whenever the \a serviceName service
+ was registered or unregistered. If it was registered, \a oldOwner will
+ contain an empty string, whereas if it was unregistered, \a 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.
+
+ \sa serviceRegistered(), serviceUnregistered()
+*/
+
+/*!
+ Creates a QDBusServiceWatcher object. Note that until you set a
+ connection with setConnection(), this object will not emit any signals.
+
+ The \a parent parameter is passed to QObject to set the parent of this
+ object.
+*/
QDBusServiceWatcher::QDBusServiceWatcher(QObject *parent)
: QObject(*new QDBusServiceWatcherPrivate(QDBusConnection(QString()), WatchForOwnerChange), parent)
{
}
+/*!
+ Creates a QDBusServiceWatcher object and attaches it to the \a connection
+ connection. Also, this function immediately starts watching for \a
+ watchMode changes to service \a service.
+
+ The \a parent parameter is passed to QObject to set the parent of this
+ object.
+*/
QDBusServiceWatcher::QDBusServiceWatcher(const QString &service, const QDBusConnection &connection, WatchMode watchMode, QObject *parent)
: QObject(*new QDBusServiceWatcherPrivate(connection, watchMode), parent)
{
d_func()->setConnection(QStringList() << service, connection, watchMode);
}
+/*!
+ Destroys the QDBusServiceWatcher object and releases any resources
+ associated with it.
+*/
QDBusServiceWatcher::~QDBusServiceWatcher()
{
}
+/*!
+ Returns the list of D-Bus services that are being watched.
+
+ \sa setWatchedServices()
+*/
QStringList QDBusServiceWatcher::watchedServices() const
{
return d_func()->servicesWatched;
}
+/*!
+ Sets the list of D-Bus services being watched to be \a services.
+
+ Note that 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.
+*/
void QDBusServiceWatcher::setWatchedServices(const QStringList &services)
{
Q_D(QDBusServiceWatcher);
@@ -166,6 +299,11 @@ void QDBusServiceWatcher::setWatchedServices(const QStringList &services)
d->setConnection(services, d->connection, d->watchMode);
}
+/*!
+ Adds \a 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.
+*/
void QDBusServiceWatcher::addWatchedService(const QString &newService)
{
Q_D(QDBusServiceWatcher);
@@ -175,6 +313,14 @@ void QDBusServiceWatcher::addWatchedService(const QString &newService)
d->servicesWatched << newService;
}
+/*!
+ Removes the \a service 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 \a service. Those signals will
+ still be emitted whenever the D-Bus messages are processed.
+
+ This function returns true if any services were removed.
+*/
bool QDBusServiceWatcher::removeWatchedService(const QString &service)
{
Q_D(QDBusServiceWatcher);
@@ -195,11 +341,28 @@ void QDBusServiceWatcher::setWatchMode(WatchMode mode)
d->setConnection(d->servicesWatched, d->connection, mode);
}
+/*!
+ Returns the QDBusConnection that this object is attached to.
+
+ \sa setConnection()
+*/
QDBusConnection QDBusServiceWatcher::connection() const
{
return d_func()->connection;
}
+/*!
+ Sets the D-Bus connection that this object is attached to be \a
+ 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.
+
+ \sa connection()
+*/
void QDBusServiceWatcher::setConnection(const QDBusConnection &connection)
{
Q_D(QDBusServiceWatcher);