dbus/dbus dbus-bus.c,1.49,1.50

[John Palmieri]

Update of /cvs/dbus/dbus/dbus
In directory kemper:/tmp/cvs-serv26724/dbus

Modified Files:
	dbus-bus.c 
Log Message:
* 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



Index: dbus-bus.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-bus.c,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -d -r1.49 -r1.50
--- dbus-bus.c	26 Feb 2006 08:11:03 -0000	1.49
+++ dbus-bus.c	3 May 2006 22:56:35 -0000	1.50
@@ -1031,7 +1031,39 @@
  * 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