Update spec to 0.19.2

1 files changed, 105 insertions, 25 deletions

diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index c668067d7..566e1166d 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -185,7 +185,7 @@ USA.</p>
           appears in isolation - messages are represented by a list of
           <tp:type>Message_Part</tp:type> mappings.</p>
 
-        <p>An example of how a message might
+        <p>An example of how a rich-text message, with an embedded image, might
           look, in a Python-like syntax:</p>
 
           <pre>
@@ -213,8 +213,26 @@ USA.</p>
     'size': 101000,
     'needs-retrieval': True,
   },
-]
-          </pre>
+]</pre>
+
+        <p>An example of how a non-text message — in particular, a vCard sent
+          via SMS as implemented by telepathy-ring on Nokia's Maemo 5 —
+          looks:</p>
+
+        <pre>
+[
+  {
+    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+    'message-sender': 42,
+    'message-sent': 1210067943,
+    'message-received': 1210067947,
+    'message-type': 0,              # = Channel_Text_Message_Type_Normal
+    'pending-message-id': 437,
+  },
+  { 'content-type': 'text/x-vcard',
+    'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
+  },
+]</pre>
 
         <div>
           <p>The first part of the message contains "headers" which refer
@@ -247,10 +265,40 @@ USA.</p>
 
           <dl>
             <dt>message-token (s)</dt>
-            <dd>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.</dd>
+            <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>
+            <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>
+
+              <tp:rationale>
+                <p>This is for compatibility with CMs older than the
+                  protocol-token key.</p>
+              </tp:rationale>
+            </dd>
 
             <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt>
             <dd>The time the message was sent (if unavailable, the time
@@ -426,7 +474,33 @@ USA.</p>
                 There's no point in providing the size if you're already
                 providing all the content.
               </tp:rationale>
-              </dd>
+            </dd>
+
+            <dt>thumbnail (b)</dt>
+            <dd>
+              <p>This part is a thumbnail. To represent an image together with
+                its thumbnail in a single message, there should be one part for
+                the full image followed by a part for the thumbnail (following
+                the “more complete versions first” requirement), with the same
+                'alternative' value. For example:</p>
+
+              <pre>
+[ ... ,
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg',
+    'size': 150000,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg'
+    'size': 1024,
+    'thumbnail': True,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  ...
+]
+              </pre>
+            </dd>
 
             <dt>needs-retrieval (b)</dt>
             <dd>If false or omitted, the connection
@@ -504,7 +578,7 @@ USA.</p>
             <dd>The status of the message. All delivery reports MUST contain
               this key in the first Message_Part.</dd>
 
-            <dt>delivery-token (s - Sent_Message_Token)</dt>
+            <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>
 
             <dd>
               <p>An identifier for the message to which this delivery report
@@ -740,22 +814,27 @@ USA.</p>
       </tp:member>
     </tp:mapping>
 
-    <tp:simple-type type="s" name="Sent_Message_Token">
+    <tp:simple-type type="s" name="Protocol_Message_Token">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>An opaque token used to identify sent messages. As a special case,
-          the empty string indicates that there is no particular
-          identification for a message.</p>
+        <p>An opaque token used to identify messages in the underlying.
+          protocol. As a special case, the empty string indicates that there
+          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>
 
-        <p>Some protocols can only track a limited number of sent messages
-          in a small message-ID space. As a result, clients MUST NOT assume
-          that message tokens will not be re-used, and SHOULD use some
-          reasonable heuristic to assign delivery reports to messages, such
-          as matching on message content or timestamp (if available), or
-          assuming that the delivery report refers to the most recent message
-          with that ID.</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
+          byte), and some implementations send non-unique identifiers (some
+          XMPP clients use very simple message IDs, such as an incrementing
+          integer that resets to 1 at the beginning of each connection). As a
+          result, clients MUST NOT assume that protocol tokens will not be
+          re-used.</p>
+
+        <p>In particular, clients SHOULD use a heuristic to assign delivery
+          reports to messages, such as matching on message content or
+          timestamp (if available), or assuming that the delivery report
+          refers to the most recent message with that ID.</p>
       </tp:docstring>
     </tp:simple-type>
 
@@ -774,7 +853,7 @@ USA.</p>
 
         <tp:rationale>
           <p>This means that the process sending the message is the first
-            to see the <tp:type>Sent_Message_Token</tp:type>, and can
+            to see the <tp:type>Protocol_Message_Token</tp:type>, and can
             relate the message to the corresponding
             <tp:member-ref>MessageSent</tp:member-ref> signal by comparing
             message tokens (if supported by the protocol).</p>
@@ -798,7 +877,7 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <arg direction="out" type="s" tp:type="Sent_Message_Token"
+      <arg direction="out" type="s" tp:type="Protocol_Message_Token"
         name="Token">
         <tp:docstring>
           An opaque token used to match any incoming delivery or failure
@@ -850,8 +929,9 @@ USA.</p>
         <p>Signals that a message has been submitted for sending. This
           MUST be emitted exactly once per emission of the <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
-          signal on the
-          Text interface.</p>
+          signal on the Text interface. This SHOULD be emitted as soon as
+          the CM determines it's theoretically possible to send the message
+          (e.g. the parameters are supported and correct).</p>
 
         <tp:rationale>
           <p>This signal allows a process that is not the caller of
@@ -889,7 +969,7 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <arg name="Message_Token" type="s" tp:type="Sent_Message_Token">
+      <arg name="Message_Token" type="s" tp:type="Protocol_Message_Token">
         <tp:docstring>
           An opaque token used to match any incoming delivery or failure
           reports against this message, or an empty string if the message