From 50266d4190c2a9e9f8a58ff2a117103e6183726b Mon Sep 17 00:00:00 2001 From: "John (J5) Palmieri" Date: Wed, 3 May 2006 22:56:35 +0000 Subject: * 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 --- dbus/dbus-bus.c | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) (limited to 'dbus') 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 -- cgit