diff options
| -rw-r--r-- | ChangeLog | 9 | ||||
| -rw-r--r-- | dbus/dbus-bus.c | 34 | ||||
| -rw-r--r-- | doc/dbus-specification.xml | 149 |
3 files changed, 191 insertions, 1 deletions
@@ -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> |