Add new public API to QDBusConnection for connecting with string

matching.

The bus allows us to match string arguments when receiving messages.
This is very useful for the NameOwnerChanged signal, whose first
argument is usually what we're interested in.

By using these new functions, you can restrict receiving of signals to
those that you truly want, instead of receiving NameOwnerChanged for all
services registered/unregistered on the bus.

2 files changed, 78 insertions, 22 deletions

diff --git a/src/dbus/qdbusconnection.cpp b/src/dbus/qdbusconnection.cpp
index bead369..3aaba68 100644
--- a/src/dbus/qdbusconnection.cpp
+++ b/src/dbus/qdbusconnection.cpp
@@ -557,42 +557,61 @@ QDBusPendingCall QDBusConnection::asyncCall(const QDBusMessage &message, int tim
 bool QDBusConnection::connect(const QString &service, const QString &path, const QString& interface,
                               const QString &name, QObject *receiver, const char *slot)
 {
-    return connect(service, path, interface, name, QString(), receiver, slot);
+    return connect(service, path, interface, name, QStringList(), QString(), receiver, slot);
 }
 
 /*!
-    Disconnects the signal specified by the \a service, \a path, \a interface and \a name parameters from
-    the slot \a slot in object \a receiver. The arguments \a service and \a path can be empty,
-    denoting a disconnection from all signals of the (\a interface, \a name) pair, from all remote
-    applications.
+    \overload
 
-    Returns true if the disconnection was successful.
+    Connects the signal to the slot \a slot in object \a
+    receiver. Unlike the previous connect() overload, this function
+    allows one to specify the parameter signature to be connected
+    using the \a signature variable. The function will then verify
+    that this signature can be delivered to the slot specified by \a
+    slot and return false otherwise.
+
+    Returns true if the connection was successful.
+
+    \note This function verifies that the signal signature matches the
+          slot's parameters, but it does not verify that the actual
+          signal exists with the given signature in the remote
+          service.
 */
-bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface,
-                                 const QString &name, QObject *receiver, const char *slot)
+bool QDBusConnection::connect(const QString &service, const QString &path, const QString& interface,
+                              const QString &name, const QString &signature,
+                              QObject *receiver, const char *slot)
 {
-    return disconnect(service, path, interface, name, QString(), receiver, slot);
+    return connect(service, path, interface, name, QStringList(), signature, receiver, slot);
 }
 
 /*!
     \overload
+    \since 4.6
 
     Connects the signal to the slot \a slot in object \a
-    receiver. Unlike the other connect() overload, this function
+    receiver. Unlike the previous connect() overload, this function
     allows one to specify the parameter signature to be connected
     using the \a signature variable. The function will then verify
     that this signature can be delivered to the slot specified by \a
     slot and return false otherwise.
 
+    The \a argumentMatch parameter lists the string parameters to be matched,
+    in sequential order. Note that, to match an empty string, you need to
+    pass a QString that is empty but not null (i.e., QString("")). A null
+    QString skips matching at that position.
+
+    Returns true if the connection was successful.
+
     \note This function verifies that the signal signature matches the
           slot's parameters, but it does not verify that the actual
           signal exists with the given signature in the remote
           service.
 */
 bool QDBusConnection::connect(const QString &service, const QString &path, const QString& interface,
-                              const QString &name, const QString &signature,
+                              const QString &name, const QStringList &argumentMatch, const QString &signature,
                               QObject *receiver, const char *slot)
 {
+
     if (!receiver || !slot || !d || !d->connection)
         return false;
     if (!interface.isEmpty() && !QDBusUtil::isValidInterfaceName(interface))
@@ -609,7 +628,7 @@ bool QDBusConnection::connect(const QString &service, const QString &path, const
 
     QString owner = d->getNameOwner(service); // we don't care if the owner is empty
     hook.signature = signature;               // it might get started later
-    if (!d->prepareHook(hook, key, service, owner, path, interface, name, QStringList(), receiver, slot, 0, false))
+    if (!d->prepareHook(hook, key, service, owner, path, interface, name, argumentMatch, receiver, slot, 0, false))
         return false;           // don't connect
 
     // avoid duplicating:
@@ -634,19 +653,50 @@ bool QDBusConnection::connect(const QString &service, const QString &path, const
 }
 
 /*!
+    Disconnects the signal specified by the \a service, \a path, \a interface
+    and \a name parameters from the slot \a slot in object \a receiver. The
+    arguments must be the same as passed to the connect() function.
+
+    Returns true if the disconnection was successful.
+*/
+bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface,
+                                 const QString &name, QObject *receiver, const char *slot)
+{
+    return disconnect(service, path, interface, name, QStringList(), QString(), receiver, slot);
+}
+
+/*!
     \overload
 
-    Disconnects the signal from the slot \a slot in object \a
-    receiver. Unlike the other disconnect() overload, this function
-    allows one to specify the parameter signature to be disconnected
-    using the \a signature variable. The function will then verify
-    that this signature is connected to the slot specified by \a slot
-    and return false otherwise.
+    Disconnects the signal specified by the \a service, \a path, \a
+    interface, \a name, and \a signature parameters from the slot \a slot in
+    object \a receiver. The arguments must be the same as passed to the
+    connect() function.
+
+    Returns true if the disconnection was successful.
 */
 bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString& interface,
                                  const QString &name, const QString &signature,
                                  QObject *receiver, const char *slot)
 {
+    return disconnect(service, path, interface, name, QStringList(), signature, receiver, slot);
+}
+
+/*!
+    \overload
+    \since 4.6
+
+    Disconnects the signal specified by the \a service, \a path, \a
+    interface, \a name, \a argumentMatch, and \a signature parameters from
+    the slot \a slot in object \a receiver. The arguments must be the same as
+    passed to the connect() function.
+
+    Returns true if the disconnection was successful.
+*/
+bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString& interface,
+                                 const QString &name, const QStringList &argumentMatch, const QString &signature,
+                                 QObject *receiver, const char *slot)
+{
     if (!receiver || !slot || !d || !d->connection)
         return false;
     if (!interface.isEmpty() && !QDBusUtil::isValidInterfaceName(interface))
@@ -663,7 +713,7 @@ bool QDBusConnection::disconnect(const QString &service, const QString &path, co
 
     QString owner = d->getNameOwner(service); // we don't care of owner is empty
     hook.signature = signature;
-    if (!d->prepareHook(hook, key, service, owner, path, interface, name, QStringList(), receiver, slot, 0, false))
+    if (!d->prepareHook(hook, key, service, owner, path, interface, name, argumentMatch, receiver, slot, 0, false))
         return false;           // don't disconnect
 
     // avoid duplicating:
diff --git a/src/dbus/qdbusconnection.h b/src/dbus/qdbusconnection.h
index 85fc7c2..82ae726 100644
--- a/src/dbus/qdbusconnection.h
+++ b/src/dbus/qdbusconnection.h
@@ -132,15 +132,21 @@ public:
 
     bool connect(const QString &service, const QString &path, const QString &interface,
                  const QString &name, QObject *receiver, const char *slot);
-    bool disconnect(const QString &service, const QString &path, const QString &interface,
-                    const QString &name, QObject *receiver, const char *slot);
-
     bool connect(const QString &service, const QString &path, const QString &interface,
                  const QString &name, const QString& signature,
                  QObject *receiver, const char *slot);
+    bool connect(const QString &service, const QString &path, const QString &interface,
+                 const QString &name, const QStringList &argumentMatch, const QString& signature,
+                 QObject *receiver, const char *slot);
+
+    bool disconnect(const QString &service, const QString &path, const QString &interface,
+                    const QString &name, QObject *receiver, const char *slot);
     bool disconnect(const QString &service, const QString &path, const QString &interface,
                     const QString &name, const QString& signature,
                     QObject *receiver, const char *slot);
+    bool disconnect(const QString &service, const QString &path, const QString &interface,
+                    const QString &name, const QStringList &argumentMatch, const QString& signature,
+                    QObject *receiver, const char *slot);
 
     bool registerObject(const QString &path, QObject *object,
                         RegisterOptions options = ExportAdaptors);