* Adding old doc patch that never got applied

* dbus/bus.c (dbus_bus_add_match): Add documentation

* doc/dbus-specification.xml: Add documentation for the match rules
  and the AddMatch and RemoveMatch methods

3 files changed, 191 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 88b4bb29..aef67f45 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2006-05-03  John (J5) Palmieri  <johnp@redhat.com>
+
+	* Adding old doc patch that never got applied
+	
+	* dbus/bus.c (dbus_bus_add_match): Add documentation
+
+	* doc/dbus-specification.xml: Add documentation for the match rules
+	  and the AddMatch and RemoveMatch methods
+
 2006-05-02  Thiago Macieira  <thiago.macieira@trolltech.com>
 
 	* qt/dbusidl2cpp.cpp: There's no callAsync. Use the correct
diff --git a/dbus/dbus-bus.c b/dbus/dbus-bus.c
index 060b0ba9..0b8c9c4f 100644
--- a/dbus/dbus-bus.c
+++ b/dbus/dbus-bus.c
@@ -1031,7 +1031,39 @@ send_no_return_values (DBusConnection *connection,
  * a boolean value indicating whether the error was set,
  * but that would require blocking always to determine
  * the return value.
- * 
+ *
+ * The AddMatch method is fully documented in the D-BUS 
+ * specification. For quick reference, the format of the 
+ * match rules is discussed here, but the specification 
+ * is the canonical version of this information.
+ *
+ * Rules are specified as a string of comma separated 
+ * key/value pairs. An example is 
+ * "type='signal',sender='org.freedesktop.DBus',
+ * interface='org.freedesktop.DBus',member='Foo',
+ * path='/bar/foo',destination=':452345.34'"
+ *
+ * Possible keys you can match on are type, sender, 
+ * interface, member, path, destination and the special
+ * arg keys.  Excluding a key from the rule indicates 
+ * a wildcard match.  For instance excluding the
+ * the member from a match rule but adding a sender would
+ * let all messages from that sender through.  
+ *
+ * Matches are inclusive not exclusive so as long as one 
+ * rule matches the message will get through.  It is important
+ * to note this because every time a message is received the 
+ * application will be paged into memory to process it.  This
+ * can cause performance problems such as draining batteries
+ * on embedded platforms.
+ *
+ * The special arg keys are used for further restricting the 
+ * match based on the parameters sent by the signal or method.
+ * For instance arg1='foo' will check the first argument, 
+ * arg2='bar' the second and so on.  For performance reasons
+ * there is a set limit on the highest number parameter that
+ * can be checked which is set in dbus-protocol.h
+ *
  * @param connection connection to the message bus
  * @param rule textual form of match rule
  * @param error location to store any errors
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index da9a813f..52422277 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2936,6 +2936,92 @@
       <para>
         FIXME 
       </para>
+      <sect3 id="message-bus-routing-match-rules">
+        <title>Match Rules</title>
+        <para>
+	  An important part of the message bus routing protocol is match  
+	  rules. Match rules describe what messages can be sent to a client
+          based on the contents of the message.  When a message is routed
+          through the bus it is compared to clients' match rules.  If any
+          of the rules match, the message is dispatched to the client.
+          If none of the rules match the message never leaves the bus.  This
+          is an effective way to control traffic over the bus and to make sure
+          only relevant message need to be processed by the client.
+        </para>
+        <para>
+          Match rules are added using the AddMatch bus method 
+          (see xref linkend="bus-messages-add-match"/>).  Rules are 
+          specified as a string of comma separated key/value pairs. 
+          Excluding a key from the rule indicates a wildcard match.  
+          For instance excluding the the member from a match rule but 
+          adding a sender would let all messages from that sender through.
+          An example of a complete rule would be 
+          "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
+        </para>
+        <para>
+          The following table describes the keys that can be used to create 
+          a match rule:
+          The following table summarizes the D-BUS types.
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Key</entry>
+                  <entry>Possible Values</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry><literal>type</literal></entry>
+                  <entry>'signal', 'method_call', 'method_return', 'error'</entry>
+                  <entry>Match on the message type.  An example of a type match is type='signal'</entry>
+                </row>
+                <row>
+                  <entry><literal>sender</literal></entry>
+                  <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
+                  and <xref linkend="term-unique-name"/> respectively)
+                  </entry>
+                  <entry>Match messages sent by a particular sender.  An example of a sender match
+                  is sender='org.freedesktop.Hal'</entry>
+                </row>
+                <row>
+                  <entry><literal>interface</literal></entry>
+                  <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
+                  <entry>Match messages sent over or to a particular interface.  An example of an
+                  interface match is interface='org.freedesktop.Hal.Manager'</entry>
+                </row>
+                <row>
+                  <entry><literal>member</literal></entry>
+                  <entry>Any valid method or signal name</entry>
+                  <entry>Matches messages which have the give method or signal name. An example of
+                  a member match is member='NameOwnerChanged'</entry>
+                </row>
+                <row>
+                  <entry><literal>path</literal></entry>
+                  <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
+                  <entry>Matches messages which are sent from or to the given object. An example of a
+                  path match is path='/org/freedesktop/Hal/Manager'</entry>
+                </row>
+                <row>
+                  <entry><literal>destination</literal></entry>
+                  <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
+                  <entry>Matches messages which are being sent to the given unique name. An
+                  example of a destination match is destination=':1.0'</entry>
+                </row>
+                <row>
+                  <entry><literal>arg[1, 2, 3, ...]</literal></entry>
+                  <entry>Any string</entry>
+                  <entry>Arg matches are special and are used for further restricting the 
+                  match based on the arguments in the body of a message.  As of this time
+                  only string arguments can be matched.  An example of an argument match 
+                  would be arg3='Foo'.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+      </sect3>
     </sect2>
     <sect2 id="message-bus-starting-services">
       <title>Message Bus Starting Services</title>
@@ -3525,6 +3611,69 @@
        </para>
       </sect3>
 
+      <sect3 id="bus-messages-add-match">
+        <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            AddMatch (in STRING rule)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Match rule to add to the connection</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>). 
+	If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
+	error is returned.
+       </para>
+      </sect3>
+      <sect3 id="bus-messages-remove-match">
+        <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            RemoveMatch (in STRING rule)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Match rule to remove from the connection</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>). 
+	If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
+	error is returned.
+       </para>
+      </sect3>
+
     </sect2>
 
   </sect1>