From 50266d4190c2a9e9f8a58ff2a117103e6183726b Mon Sep 17 00:00:00 2001 From: "John (J5) Palmieri" Date: Wed, 3 May 2006 22:56:35 +0000 Subject: [PATCH] * 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 --- ChangeLog | 9 +++ dbus/dbus-bus.c | 34 ++++++++++- doc/dbus-specification.xml | 149 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index 88b4bb2..aef67f4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2006-05-03 John (J5) Palmieri + + * 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 * qt/dbusidl2cpp.cpp: There's no callAsync. Use the correct diff --git a/dbus/dbus-bus.c b/dbus/dbus-bus.c index 060b0ba..0b8c9c4 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 da9a813..5242227 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -2936,6 +2936,92 @@ FIXME + + Match Rules + + 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. + + + 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'" + + + The following table describes the keys that can be used to create + a match rule: + The following table summarizes the D-BUS types. + + + + + Key + Possible Values + Description + + + + + type + 'signal', 'method_call', 'method_return', 'error' + Match on the message type. An example of a type match is type='signal' + + + sender + A bus or unique name (see + and respectively) + + Match messages sent by a particular sender. An example of a sender match + is sender='org.freedesktop.Hal' + + + interface + An interface name (see ) + Match messages sent over or to a particular interface. An example of an + interface match is interface='org.freedesktop.Hal.Manager' + + + member + Any valid method or signal name + Matches messages which have the give method or signal name. An example of + a member match is member='NameOwnerChanged' + + + path + An object path (see ) + Matches messages which are sent from or to the given object. An example of a + path match is path='/org/freedesktop/Hal/Manager' + + + destination + A unique name (see ) + Matches messages which are being sent to the given unique name. An + example of a destination match is destination=':1.0' + + + arg[1, 2, 3, ...] + Any string + 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'. + + + + + + Message Bus Starting Services @@ -3525,6 +3611,69 @@ + + <literal>org.freedesktop.DBus.AddMatch</literal> + + As a method: + + AddMatch (in STRING rule) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Match rule to add to the connection + + + + + Adds a match rule to match messages going through the message bus (see ). + If the bus does not have enough resources the org.freedesktop.DBus.Error.OOM + error is returned. + + + + <literal>org.freedesktop.DBus.RemoveMatch</literal> + + As a method: + + RemoveMatch (in STRING rule) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Match rule to remove from the connection + + + + + Removes the first rule that matches (see ). + If the rule is not found the org.freedesktop.DBus.Error.MatchRuleNotFound + error is returned. + + + -- 2.7.4