From 1152fa55960984e12574e623403247c74de18754 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Mon, 15 Jan 2018 17:50:16 +0000
Subject: [PATCH 4/8] spec: Add a method call to request a new
 CONTAINER_INSTANCE header field

This follows the pattern established in fd.o#100317 by combining a
request "please give me more information", for efficiency (most
destinations not wanting the extra information will not receive it),
with a mechanism for "tell me whether I can trust this new header
field", for correctness/safety (a successful return indicates that
all future CONTAINER_INSTANCE header fields can be trusted).

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 doc/dbus-specification.xml | 58 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 6205d347..238e5d19 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1786,6 +1786,26 @@
                   This header field is controlled by the message sender.
                   </entry>
                 </row>
+                <row>
+                  <entry><literal>CONTAINER_INSTANCE</literal></entry>
+                  <entry>10</entry>
+                  <entry><literal>OBJECT_PATH</literal></entry>
+                  <entry>optional</entry>
+                  <entry>
+                    The object path representing the container instance
+                    (see <xref linkend="bus-messages-containers1-add-server"/>)
+                    that sent this message, or the root object path
+                    <literal>/</literal> if the message did not come from a
+                    connection to a container instance.
+                    In message bus implementations that implement the
+                    <literal>Containers1.RequestHeader method</literal>, this
+                    header field is controlled by the message bus: see the
+                    <link linkend="bus-messages-containers1-request-header"
+                      >Containers1.RequestHeader method</link> for details.
+                    Senders must not attempt to include this header field
+                    in messages.
+                  </entry>
+                </row>
               </tbody>
             </tgroup>
           </informaltable>
@@ -7443,6 +7463,44 @@
         </para>
       </sect3>
 
+      <sect3 id="bus-messages-containers1-request-header">
+        <title><literal>org.freedesktop.DBus.Containers1.RequestHeader</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            RequestHeader ()
+          </programlisting>
+        </para>
+
+        <para>
+          Request that the message bus adds the
+          <literal>CONTAINER_INSTANCE</literal> header field to each
+          message that will be received by the connection that called
+          this method. If the message bus sends a successful reply,
+          the caller may assume that it will receive the
+          <literal>CONTAINER_INSTANCE</literal> header field in every
+          message, and that the value of that header field is authentic.
+          If the message bus sends an unsuccessful reply, the caller
+          must not make any assumptions about that header field.
+        </para>
+        <para>
+          If a sender mistakenly or maliciously includes this header field
+          in any message, then all message bus implementations that
+          implement this method call must remove the header field before
+          relaying the message.
+        </para>
+        <para>
+          If a destination to which a message will be delivered has
+          successfully called this method, then the message bus must add
+          this header field to the copy of the message that will be
+          delivered to that destination. For messages that are delivered
+          to more than one destination, if another destination did not
+          request this header field, it is unspecified whether the
+          other destination will receive it anyway: D-Bus clients must
+          not rely on one behaviour or the other.
+        </para>
+      </sect3>
+
       <sect3 id="bus-messages-containers1-instance-removed">
         <title><literal>org.freedesktop.DBus.Containers1.InstanceRemoved</literal></title>
         <para>
-- 
2.15.1