diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/dbus-specification.xml | 149 |
1 files changed, 149 insertions, 0 deletions
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> |