Update spec to 0.17.14

1 files changed, 77 insertions, 8 deletions

diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 205dbc0bc..8340305ff 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -168,11 +168,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           The message to send
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Request that a message be sent on this channel. When the message has
-        been submitted for delivery, this method will return and the Sent
-        signal will be emitted. If the message cannot be submitted for
-        delivery, the method returns an error and no signal is emitted.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that a message be sent on this channel. When the message has
+          been submitted for delivery, this method will return and the Sent
+          signal will be emitted. If the message cannot be submitted for
+          delivery, the method returns an error and no signal is emitted.</p>
+
+        <p>This method SHOULD return before the Sent signal is
+          emitted.</p>
+
+        <tp:rationale>
+          <p>When a Text channel implements the Messages interface, that
+            "SHOULD" becomes a "MUST".</p>
+        </tp:rationale>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -265,11 +273,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <arg name="Text" type="s">
         <tp:docstring>
-          The text of the message
+          The text of the message. If the message was, or will be, altered
+          during transmission, this argument SHOULD reflect what other
+          contacts will receive rather than being a copy of the argument
+          to Send.
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Signals that a message has been submitted for sending.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Signals that a message has been submitted for sending.</p>
       </tp:docstring>
     </signal>
 
@@ -335,6 +346,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             the user that part of the message was not understood.</p>
         </tp:docstring>
       </tp:flag>
+
+      <tp:flag suffix="Scrollback" value="4">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The incoming message was part of a replay of message history.</p>
+
+          <tp:rationale>
+            <p>In XMPP multi-user chat, a few past messages are replayed
+              when you join a chatroom. A sufficiently capable IRC connection
+              manager could also set this flag on historical messages when
+              connected to a proxy like bip or irssi-proxy. The existence
+              of this flag allows loggers and UIs to use better heuristics
+              when eliminating duplicates (a simple implementation made
+              possible by this flag would be to avoid logging scrollback
+              at all).</p>
+          </tp:rationale>
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:flag suffix="Rescued" value="8">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The incoming message has been seen in a previous channel during
+            the lifetime of the Connection, but had not been acknowledged
+            when that channel closed, causing an identical channel (the
+            channel in which the message now appears) to open.</p>
+
+          <tp:rationale>
+            <p>This means that a logger (which should already have seen the
+              message in the previous channel) is able to recognise and ignore
+              these replayed messages.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </tp:flag>
     </tp:flags>
 
     <tp:property name="anonymous" type="b">
@@ -473,6 +516,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref>
         signal (with the suppress_handler parameter set to FALSE).</p>
 
+      <p>If messages were sent on the old channel but the
+        <tp:member-ref>Sent</tp:member-ref>signal has not yet been emitted
+        for those messages, the new channel SHOULD emit Sent for those
+        messages when appropriate - it behaves like a continuation of the
+        old channel.</p>
+
       <tp:rationale>
         <p>In effect, this turns this situation, in which a client
           is likely to lose messages:</p>
@@ -501,6 +550,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>suppress_handler must be set to FALSE so the replacement channel
           will be handled by something.</p>
       </tp:rationale>
+
+      <p>As a result, Text channels SHOULD implement <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable</tp:dbus-ref>.</p>
+
+      <tp:rationale>
+        <p>This "respawning" behaviour becomes problematic if there is no
+          suitable handler for Text channels, or if a particular message
+          repeatedly crashes the Text channel handler; a channel dispatcher
+          can't just Close() the channel in these situations, because
+          it will come back.</p>
+
+        <p>In these situations, the channel dispatcher needs a last-resort
+          way to destroy the channel and stop it respawning. It could either
+          acknowledge the messages itself, or use the Destroyable interface;
+          the Destroyable interface has the advantage that it's not
+          channel-type-dependent, so the channel dispatcher only has to
+          understand one extra interface, however many channel types
+          eventually need a distinction between Close and Destroy.</p>
+      </tp:rationale>
+
     </tp:docstring>
   </interface>
 </node>