fd.o #26838: define a really unique identifier for a channelconversation-token

2 files changed, 52 insertions, 5 deletions

diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml
index 5bbca17b..81ba1b5a 100644
--- a/spec/Channel_Future.xml
+++ b/spec/Channel_Future.xml
@@ -44,6 +44,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:rationale>
     </tp:docstring>
 
+    <property name="ConversationID" tp:name-for-bindings="Conversation_ID"
+      type="s" access="read">
+      <tp:added version="0.19.UNRELEASED">(in Channel.FUTURE
+        pseudo-interface)</tp:added>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A unique identifier for the conversation represented by this
+          channel, allocated by the connection manager. This property
+          is immutable.</p>
+
+        <p>If the value of this property is non-empty, it MUST be unique
+          to this channel, even over time (implementations MAY allocate and use
+          a UUID, for instance).</p>
+
+        <p>If this property is empty or missing, clients SHOULD treat the
+          channel as if it had a conversation ID distinct from any other
+          channel, for instance by generating a UUID locally and using
+          that as the conversation ID.</p>
+
+        <tp:rationale>
+          <p>Unlike the object path of the channel, this property is
+            guaranteed to remain unique over time.</p>
+
+          <p>Because this property persists with the channel, if a logger
+            crashes and is restarted, it can tell that a channel that still
+            exists is the same channel that it started to log before
+            crashing.</p>
+
+          <p>In particular, clients can safely assume that each pair
+            (ConversationID, <tp:type>Message_ID</tp:type>) uniquely
+            identifies at most one message.</p>
+
+          <p>This property is also useful to identify an anonymous conference
+            channel (as used in MSN connection managers), which has no other
+            means of identification.</p>
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
     <property name="Bundle" tp:name-for-bindings="Bundle"
       type="o" access="read">
       <tp:added version="0.17.9">(in Channel.FUTURE
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5315a550..9f5dc30e 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -22,11 +22,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
     <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List">
-      <tp:docstring>
-        A unique-per-channel identifier for an incoming message. These
-        SHOULD be allocated in a way that minimizes collisions (in particular,
-        message IDs SHOULD NOT be re-used until all of the 32-bit integer
-        space has already been used).
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A unique-per-channel identifier for an incoming message. These
+          MUST be allocated in a way that avoids collisions within a Channel
+          instance (typically, IDs are simply allocated sequentially).</p>
+
+        <p>Clients MAY assume that each pair (<tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.FUTURE"
+            >ConversationID</tp:dbus-ref>, Message_ID) uniquely identifies
+          at most one message, if the ConversationID is non-empty.</p>
+
+        <tp:rationale>
+          <p>For example, it is safe to use a string obtained by combining
+            these as a key in a database of messages.</p>
+        </tp:rationale>
       </tp:docstring>
     </tp:simple-type>