Update to spec 0.21.5

- adjust Call example: InitialTransport is now a uint32
- add Confused, ServiceConfused errors
- add codegen for Hints and related things

1 files changed, 116 insertions, 54 deletions

diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 0eeee39e2..d773411eb 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -104,6 +104,8 @@ USA.</p>
           This list MUST NOT be empty, since all Messages implementations
           MUST accept messages containing a single "text/plain" part.</p>
 
+        <p>Items in this list MUST be normalized to lower-case.</p>
+
         <p>Some examples of how this property interacts with the
           <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p>
 
@@ -142,6 +144,20 @@ USA.</p>
       </tp:docstring>
     </property>
 
+    <property name="MessageTypes" type="au"
+      tp:type="Channel_Text_Message_Type[]" access="read"
+      tp:name-for-bindings="Message_Types"
+      tp:immutable="yes">
+      <tp:added version="0.21.5">
+        This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text"
+          >GetMessageTypes</tp:dbus-ref>; fall back to that method for
+        compatibility with older connection managers.
+      </tp:added>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A list of message types which may be sent on this channel.</p>
+      </tp:docstring>
+    </property>
+
     <property name="MessagePartSupportFlags" type="u"
       tp:type="Message_Part_Support_Flags" access="read"
       tp:name-for-bindings="Message_Part_Support_Flags"
@@ -289,6 +305,17 @@ USA.</p>
             image.</p>
         </tp:rationale>
 
+        <p>Connection managers, clients and extensions to this specification
+          SHOULD NOT include <tp:type>Handle</tp:type>s as values in a
+          Message_Part, except for <code>message-sender</code> in the
+          header.</p>
+
+        <tp:rationale>
+          <p>Reference-counting handles in clients becomes problematic if
+            the channel proxy cannot know whether particular map values
+            are handles or not.</p>
+        </tp:rationale>
+
         <h4>Example messages</h4>
 
         <p>A rich-text message, with an embedded image, might be represented
@@ -491,6 +518,12 @@ USA.</p>
 
     <tp:simple-type type="s" name="Message_Header_Key">
       <tp:added version="0.19.8"/>
+      <tp:changed version="0.21.5">
+        Removed <tt>protocol-token</tt>—which had never been implemented—and
+        respecified <tt>message-token</tt> not to have unimplementable
+        uniqueness guarantees.
+      </tp:changed>
+
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a
           message, which contains metadata about the message as a whole, along
@@ -499,39 +532,37 @@ USA.</p>
           one or the other.</p>
 
           <dl>
-            <dt>message-token (s)</dt>
-            <dd>
-              <p>An opaque, globally-unique identifier for the entire message.
-                This MAY be treated as if it were a MIME Message-ID, e.g. for
-                the mid: and cid: URI schemes. If omitted, there is no suitable
-                token; the protocol-token key SHOULD be provided if the protocol
-                identifies messages in some less unique way.</p>
-            </dd>
-
-            <dt>protocol-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>
+            <dt>message-token (s -
+              <tp:type>Protocol_Message_Token</tp:type>)
+            </dt>
             <dd>
-              <p>An opaque token for the entire message, with whatever uniqueness
-                guarantee is provided by the underlying protocol. As described
-                for the Protocol_Message_Token type, this token is <em>not</em>
-                guaranteed to be unique between contacts, or even within the
-                scope of a Channel.</p>
-
-              <tp:rationale>
-                <p>In practice, in most protocols there is no token with the
-                  uniqueness guarantees demanded for message-token; the
-                  definition of message-token was inappropriate, but must now
-                  be preserved for the benefit of clients that rely on it, at
-                  least until Telepathy breaks backwards compatibility.</p>
-              </tp:rationale>
-
-              <p>The message-token and protocol-token SHOULD NOT both be present;
-                clients requiring an identifier with the semantics of the
-                protocol-token SHOULD look for the message-token first, falling
-                back to the protocol-token.</p>
+              <p>An opaque identifier for the message, as used by the
+                underlying protocol. For outgoing messages, this SHOULD be
+                globally unique; for incoming messages, this is <em>not</em>
+                guaranteed to uniquely identify a message, <em>even within the
+                scope of a single channel or contact</em>; the only guarantee
+                made is that two messages with different <tt>message-token</tt>
+                headers are different messages.</p>
+
+              <p>Clients wishing to determine whether a new message with the
+                <tt>scrollback</tt> header matches a previously-logged message
+                with the same <tt>message-token</tt> SHOULD compare the
+                message's sender, contents, <tt>message-sent</tt> or
+                <tt>message-received</tt> timestamp, etc. Note that, in XMPP,
+                the server only supplies a timestamp for scrollback messages,
+                not for messages received while you are in a room; thus,
+                non-scrollback messages will lack a <tt>message-sent</tt>
+                timestamp.</p>
 
               <tp:rationale>
-                <p>This is for compatibility with CMs older than the
-                  protocol-token key.</p>
+                <p>In practice, most protocols do not provide globally-unique
+                  identifiers for messages. Connection managers, being
+                  stateless, do not have the necessary information — namely, IM
+                  logs — to generate reliable unique tokens for messages.</p>
+
+                <p>For instance, some XMPP clients (including Gabble) stamp
+                  messages they send with unique identifiers, but others number
+                  outgoing messages in a conversation from 1 upwards.</p>
               </tp:rationale>
             </dd>
 
@@ -549,6 +580,13 @@ USA.</p>
             <dd>The contact who sent the message. If 0 or omitted, the contact
               who sent the message could not be determined.</dd>
 
+            <dt>message-sender-id (s)</dt>
+            <dd>The identifier of the contact who sent the message,
+              i.e. the result of calling <tp:dbus-ref
+                namespace="ofdT.Connection">InspectHandles</tp:dbus-ref>
+              on <code>message-sender</code>. If omitted, clients MUST
+              fall back to looking at <code>message-sender</code>.</dd>
+
             <dt>sender-nickname (s)</dt>
             <dd>The nickname chosen by the sender of the message, which can be
               different for each message in a conversation.</dd>
@@ -601,7 +639,8 @@ USA.</p>
               does not make sense on outgoing messages, and SHOULD NOT
               appear there.</dd>
           </dl>
-          </tp:docstring>
+
+      </tp:docstring>
     </tp:simple-type>
 
     <tp:simple-type type="s" name="Message_Body_Key">
@@ -652,6 +691,12 @@ USA.</p>
 
               <p>Clients MUST ignore parts without a 'content-type' key, which
                 are reserved for future expansion.</p>
+
+              <p>When sending messages, clients SHOULD normalize the
+                content-type to lower case, but connection managers SHOULD NOT
+                rely on this. When signalling sent or received messages,
+                connection managers MUST normalize the content-type to lower
+                case.</p>
             </dd>
 
             <dt>lang (s)</dt>
@@ -703,16 +748,19 @@ USA.</p>
             <dt>needs-retrieval (b)</dt>
             <dd>If false or omitted, the connection
               manager already holds this part in memory. If present and true,
-              this part will be retrieved on demand (like MIME's
-              message/external-body), so clients should expect retrieval to
-              take time; if this specification is later extended to provide a
-              streaming version of GetPendingMessageContent, clients should
-              use it for parts with this flag.</dd>
+              this part must be retrieved on demand (like MIME's
+              <tt>message/external-body</tt>) by a mechanism to be defined later.
+
+              <tp:rationale>The mechanism was meant to be
+                <tp:member-ref>GetPendingMessageContent</tp:member-ref>, but
+                that didn't work out. It's worth leaving the header in in
+                preparation for a future mechanism.
+              </tp:rationale>
+            </dd>
 
             <dt>truncated (b)</dt>
-            <dd>The content available via the 'content' key or
-              GetPendingMessageContent has been truncated by the server
-              or connection manager (equivalent to
+            <dd>The content available via the 'content' key has been truncated
+              by the server or connection manager (equivalent to
               Channel_Text_Message_Flag_Truncated in the Text interface).
             </dd>
 
@@ -826,20 +874,6 @@ USA.</p>
                 the sender. This is sometimes the only way to match it
                 against the sent message, so we include it here.
               </tp:rationale>
-
-              <p>Unlike in the Messages interface, content not visible
-                in the value for this key cannot be retrieved by another
-                means, so the connection manager SHOULD be more
-                aggressive about including (possibly truncated) message
-                content in the 'content' key.</p>
-
-              <tp:rationale>
-                The Messages interface needs to allow all content to be
-                retrieved, but in this interface, the content we provide is
-                merely a hint; so some is better than none, and it doesn't
-                seem worth providing an API as complex as Messages'
-                GetPendingMessageContent for the echoed message.
-              </tp:rationale>
             </dd>
 
           </dl>
@@ -848,6 +882,11 @@ USA.</p>
 
     <tp:simple-type type="u" name="Message_Part_Index"
       array-name="Message_Part_Index_List">
+      <tp:deprecated version="0.21.5">
+        This type is only used by
+        <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is
+        unimplemented and deprecated.
+      </tp:deprecated>
       <tp:added version="0.17.17"/>
       <tp:docstring>
         The index of a message part within a message.
@@ -856,6 +895,11 @@ USA.</p>
 
     <tp:mapping name="Message_Part_Content_Map">
       <tp:added version="0.17.17"/>
+      <tp:deprecated version="0.21.5">
+        This structure is only used by
+        <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is
+        unimplemented and deprecated.
+      </tp:deprecated>
       <tp:docstring>
         A mapping from message part indexes to their content, as returned by
         <tp:member-ref>GetPendingMessageContent</tp:member-ref>.
@@ -888,7 +932,7 @@ USA.</p>
           is no particular identification for a message.</p>
 
         <p>CM implementations SHOULD use an identifier expected to be unique,
-          such as a UUID, if possible.</p>
+          such as a UUID, for outgoing messages (if possible).</p>
 
         <p>Some protocols can only track a limited number of messages
           in a small message-ID space (SMS messages are identified by a single
@@ -946,6 +990,16 @@ USA.</p>
         <p>If this method fails, message submission to the server has failed
           and no signal on this interface (or the Text interface) is
           emitted.</p>
+
+        <p>If this method succeeds, message submission to the server has
+          succeeded, but the message has not necessarily reached its intended
+          recipient. If a delivery failure is detected later, this is
+          signalled by receiving a message whose <code>message-type</code>
+          header maps to
+          <tp:type>Channel_Text_Message_Type</tp:type>_Delivery_Report.
+          Similarly, if delivery is detected to have been successful
+          (which is not possible in all protocols), a successful delivery
+          report will be signalled.</p>
       </tp:docstring>
 
       <arg direction="in" type="aa{sv}" tp:type="Message_Part[]"
@@ -1128,6 +1182,14 @@ USA.</p>
 
     <method name="GetPendingMessageContent"
       tp:name-for-bindings="Get_Pending_Message_Content">
+      <tp:deprecated version='0.21.5'
+                     xmlns="http://www.w3.org/1999/xhtml">
+        This method has never been implemented, and in any case would have been
+        impossible to use correctly when multiple clients (such as a logger and
+        the handler) are interested in a text channel. See <a
+          href='https://bugs.freedesktop.org/show_bug.cgi?id=26417'>freedesktop.org
+        bug #26417</a> for more details.
+      </tp:deprecated>
       <tp:docstring>
         Retrieve the content of one or more parts of a pending message.
         Note that this function may take a considerable amount of time