From 0ca865284b28ff15d251a6c7a76fa11da548ba55 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Thu, 21 Jul 2011 16:17:35 +0100
Subject: [PATCH 2/5] spec: define unicast messages and broadcast signals, and
 explicitly allow unicast signals

I believe that the wording of the spec has always allowed unicast signals,
but most bindings assume that signals are broadcasts, so it seems worth
saying specifically that this feature exists and can be useful.
---
 doc/dbus-specification.xml |   24 +++++++++++++++++++++---
 1 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 459f46a..2abe799 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3375,7 +3375,8 @@
 
       <para>
         Messages may have a <literal>DESTINATION</literal> field (see <xref
-        linkend="message-protocol-header-fields"/>).  If the
+          linkend="message-protocol-header-fields"/>), resulting in a
+        <firstterm>unicast message</firstterm>.  If the
         <literal>DESTINATION</literal> 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
@@ -3385,9 +3386,26 @@
       </para>
 
       <para>
-        Signals normally do not specify a destination; they are sent to all
+        When the message bus receives a signal, if the
+        <literal>DESTINATION</literal> field is absent, it is considered to
+        be a <firstterm>broadcast signal</firstterm>, and is sent to all
         applications with <firstterm>message matching rules</firstterm> that
-        match the message.
+        match the message. Most signal messages are broadcasts.
+      </para>
+
+      <para>
+        Unicast signal messages (those with a <literal>DESTINATION</literal>
+        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 <xref linkend="bus-messages-add-match"/> 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.
       </para>
 
       <para>
-- 
1.7.5.4