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 --- doc/dbus-specification.xml | 149 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) (limited to 'doc') 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 @@ 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. + + + -- cgit