From add19565ef9d6b952b5ab9bff5aa6299096412c1 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Thu, 21 Jul 2011 16:24:01 +0100 Subject: [PATCH 4/5] Move the explanation of message routing to the Message Routing section, leaving behind a summary --- doc/dbus-specification.xml | 108 +++++++++++++++++++++++--------------------- 1 files changed, 56 insertions(+), 52 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index ef5fde5..dbd5d08 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -3374,57 +3374,10 @@ - Messages may have a DESTINATION field (see ), resulting in a - unicast message. If the - DESTINATION field is present, it specifies a message - recipient by name. Method calls and replies normally specify this field. - The message bus must send messages (of any type) with the - DESTINATION field set to the specified recipient, - regardless of whether the recipient has set up a match rule matching - the message. - - - - When the message bus receives a signal, if the - DESTINATION field is absent, it is considered to - be a broadcast signal, and is sent to all - applications with message matching rules that - match the message. Most signal messages are broadcasts. - - - - Unicast signal messages (those with a DESTINATION - field) are not commonly used, but they are treated like any unicast - message: they are delivered to the specified receipient, - regardless of its match rules. One use for unicast signals is to - avoid a race condition in which a signal is emitted before the intended - recipient can call to - receive that signal: if the signal is sent directly to that recipient - using a unicast message, it does not need to add a match rule at all, - and there is no race condition. Another use for unicast signals, - on message buses whose security policy prevents eavesdropping, is to - send sensitive information which should only be visible to one - recipient. - - - - When the message bus receives a method call, if the - DESTINATION field is absent, the call is taken to be - a standard one-to-one message and interpreted by the message bus - itself. For example, sending an - org.freedesktop.DBus.Peer.Ping message with no - DESTINATION will cause the message bus itself to - reply to the ping immediately; the message bus will not make this - message visible to other applications. - - - - Continuing the org.freedesktop.DBus.Peer.Ping example, if - the ping message were sent with a DESTINATION name of - com.yoyodyne.Screensaver, then the ping would be - forwarded, and the Yoyodyne Corporation screensaver application would be - expected to reply to the ping. + Applications may send unicast messages to + a specific recipient or to the message bus itself, or + broadcast messages to all interested recipients. + See for details. @@ -3858,8 +3811,59 @@ Message Bus Message Routing + - FIXME + Messages may have a DESTINATION field (see ), resulting in a + unicast message. If the + DESTINATION field is present, it specifies a message + recipient by name. Method calls and replies normally specify this field. + The message bus must send messages (of any type) with the + DESTINATION field set to the specified recipient, + regardless of whether the recipient has set up a match rule matching + the message. + + + + When the message bus receives a signal, if the + DESTINATION field is absent, it is considered to + be a broadcast signal, and is sent to all + applications with message matching rules that + match the message. Most signal messages are broadcasts. + + + + Unicast signal messages (those with a DESTINATION + field) are not commonly used, but they are treated like any unicast + message: they are delivered to the specified receipient, + regardless of its match rules. One use for unicast signals is to + avoid a race condition in which a signal is emitted before the intended + recipient can call to + receive that signal: if the signal is sent directly to that recipient + using a unicast message, it does not need to add a match rule at all, + and there is no race condition. Another use for unicast signals, + on message buses whose security policy prevents eavesdropping, is to + send sensitive information which should only be visible to one + recipient. + + + + When the message bus receives a method call, if the + DESTINATION field is absent, the call is taken to be + a standard one-to-one message and interpreted by the message bus + itself. For example, sending an + org.freedesktop.DBus.Peer.Ping message with no + DESTINATION will cause the message bus itself to + reply to the ping immediately; the message bus will not make this + message visible to other applications. + + + + Continuing the org.freedesktop.DBus.Peer.Ping example, if + the ping message were sent with a DESTINATION name of + com.yoyodyne.Screensaver, then the ping would be + forwarded, and the Yoyodyne Corporation screensaver application would be + expected to reply to the ping. -- 1.7.5.4