Doc: add documentation for QDBusServiceWatcher class.

1 files changed, 163 insertions, 0 deletions

diff --git a/src/dbus/qdbusservicewatcher.cpp b/src/dbus/qdbusservicewatcher.cpp
index d8a33c33bf..4872732406 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);