From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 23 Sep 2014 16:43:30 +0000 (+0100)
Subject: Expand documentation of NO_REPLY_EXPECTED
X-Git-Tag: dbus-1.10.6~383
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5392058c25d425934ee13570d40d04acab5df832;p=platform%2Fupstream%2Fdbus.git

Expand documentation of NO_REPLY_EXPECTED

The message type is more important than whether NO_REPLY_EXPECTED is
set, when deciding whether a reply is expected. This documents
existing practice in at least libdbus, GDBus and dbus-daemon.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=75749
Reviewed-by: Thiago Macieira
---

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 3276f2b..a110a08 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1300,7 +1300,8 @@
               <row>
                 <entry><literal>METHOD_CALL</literal></entry>
                 <entry>1</entry>
-                <entry>Method call.</entry>
+                <entry>Method call. This message type may prompt a
+                  reply.</entry>
               </row>
               <row>
                 <entry><literal>METHOD_RETURN</literal></entry>
@@ -1337,11 +1338,26 @@
               <row>
                 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
                 <entry>0x1</entry>
-                <entry>This message does not expect method return replies or
-                error replies; the reply can be omitted as an
-                optimization. However, it is compliant with this specification
-                to return the reply despite this flag and the only harm 
-                  from doing so is extra network traffic.
+                <entry>
+                  <para>
+                    This message does not expect method return replies or
+                    error replies, even if it is of a type that can
+                    have a reply; the reply can be omitted as an
+                    optimization. It is compliant with this specification
+                    to return the reply despite this flag, although doing
+                    so on a bus with a non-trivial security policy
+                    (such as the well-known system bus) may result in
+                    access denial messages being logged for the reply.
+                  </para>
+                  <para>
+                    Note that METHOD_CALL is the only message type currently
+                    defined in this specification that can expect a reply,
+                    so the presence or absence of this flag in the other
+                    three message types that are currently
+                    documented is meaningless: replies to those message
+                    types should not be sent, whether this flag is present
+                    or not.
+                  </para>
                 </entry>
               </row>
               <row>
@@ -4431,7 +4447,9 @@
         <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. Most signal messages are broadcasts.
+        match the message. Most signal messages are broadcasts, and
+        no other message types currently defined in this specification
+        may be broadcast.
       </para>
 
       <para>
@@ -4471,7 +4489,7 @@
       <para>
         Message bus implementations may impose a security policy which
         prevents certain messages from being sent or received.
-        When a message cannot be sent or received due to a security
+        When a method call message cannot be sent or received due to a security
         policy, the message bus should send an error reply, unless the
         original message had the <literal>NO_REPLY</literal> flag.
       </para>