Room: split subject stuff out into separate interface

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

5 files changed, 168 insertions, 131 deletions

diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml
index e09ed9f5..28491f43 100644
--- a/spec/Channel_Interface_Room.xml
+++ b/spec/Channel_Interface_Room.xml
@@ -294,26 +294,6 @@
 
     </tp:docstring>
 
-    <method name="SetSubject" tp:name-for-bindings="Set_Subject">
-      <arg direction="in" type="s" name="Subject">
-        <tp:docstring>The new subject.</tp:docstring>
-      </arg>
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Set the room's subject. Clients SHOULD look at the subject
-          flags before calling this method as the user might not have
-          permission to set the subject.</p>
-
-        <p>Clients SHOULD NOT assume success if no errors are raised
-          by calling this method, but instead should listen to the
-          <tp:member-ref>SubjectChanged</tp:member-ref> signal for
-          change notification.</p>
-      </tp:docstring>
-      <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
-      </tp:possible-errors>
-    </method>
-
     <property name="RoomName" tp:name-for-bindings="Room_Name" type="s"
               access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -349,113 +329,6 @@
       </tp:docstring>
     </property>
 
-    <tp:struct name="Room_Subject">
-      <tp:docstring>
-        A struct representing the subject of a room channel.
-      </tp:docstring>
-      <tp:member type="s" name="Subject">
-        <tp:docstring>
-           A human-readable description of the current subject of
-           conversation in the channel, similar to /topic in IRC.
-        </tp:docstring>
-      </tp:member>
-      <tp:member type="s" name="Actor">
-        <tp:docstring>
-           A normalized contact ID representing who last modified the
-           subject, or the empty string if it is not known.
-        </tp:docstring>
-      </tp:member>
-      <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp">
-        <tp:docstring>
-           A unix timestamp indicating when the subject was last modified.
-        </tp:docstring>
-      </tp:member>
-      <tp:member type="u" tp:type="Room_Subject_Flags" name="Flags">
-        <tp:docstring>
-           A bitwise OR of the flags applicable to this channel's
-           subject.
-        </tp:docstring>
-      </tp:member>
-    </tp:struct>
-
-    <property name="Subject" tp:name-for-bindings="Subject"
-              type="(ssxu)" tp:type="Room_Subject" access="read">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The subject on the room such as the topic in an IRC channel,
-          or the room name in XMPP MUCs. In protocols which do not support
-          subjects (like MSN), this property should be ("", "", 0, 0).</p>
-
-        <tp:rationale>This property replaces the subject, subject-contact, and
-          subject-timestamp Telepathy properties of Text channels, as Telepathy
-          properties are soon to be deprecated completely.</tp:rationale>
-
-        <p>Change notification for this property is provided by the
-          <tp:member-ref>SubjectChanged</tp:member-ref> signal.</p>
-
-        <p>This property may change during the lifetime of the channel and
-          MUST not be included in a channel request.</p>
-      </tp:docstring>
-    </property>
-
-    <signal name="SubjectChanged" tp:name-for-bindings="Subject_Changed">
-      <arg name="Subject" type="s">
-        <tp:docstring>
-          The new subject string.
-        </tp:docstring>
-      </arg>
-      <arg name="Actor" type="s">
-        <tp:docstring>
-          A normalized contact ID representing who last modified the
-          subject, or the empty string if it is not known.
-        </tp:docstring>
-      </arg>
-      <arg name="Timestamp" type="x" tp:type="Unix_Timestamp64">
-        <tp:docstring>
-          A unix timestamp indicating when the subject was last
-          modified.
-        </tp:docstring>
-      </arg>
-      <arg name="Flags" type="u" tp:type="Room_Subject_Flags">
-        <tp:docstring>
-          A bitwise OR of the flags applicable to this channel's
-          subject.
-        </tp:docstring>
-      </arg>
-      <tp:docstring>
-        Emitted when the <tp:member-ref>Subject</tp:member-ref>
-        property is changed.
-      </tp:docstring>
-    </signal>
-
-    <tp:flags name="Room_Subject_Flags"
-      value-prefix="Room_Subject_Flag" type="u">
-      <tp:docstring>
-        Flags indicating capabilities regarding the room subject.
-      </tp:docstring>
-
-      <tp:flag suffix="Present" value="1">
-        <tp:docstring>
-          A subject exists on this channel. Protocols which do not
-          have the concept of room subjects MUST NOT have this flag
-          set as an indication to clients that no notice should be
-          taken of the <tp:member-ref>Subject</tp:member-ref>
-          property. Note that this flag only allows clients to
-          distinguish between protocols which support room subjects
-          and protocols which do not. The presence of this flag
-          MUST NOT change.
-        </tp:docstring>
-      </tp:flag>
-
-      <tp:flag suffix="Can_Set" value="2">
-        <tp:docstring>
-          The <tp:member-ref>Subject</tp:member-ref> property can be
-          set by the user by calling
-          <tp:member-ref>SetSubject</tp:member-ref>. If this flag is
-          set, then Present MUST also be set.
-        </tp:docstring>
-      </tp:flag>
-    </tp:flags>
-
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Subject.xml b/spec/Channel_Interface_Subject.xml
new file mode 100644
index 00000000..60d37a31
--- /dev/null
+++ b/spec/Channel_Interface_Subject.xml
@@ -0,0 +1,163 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Subject"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>This library is free software; you can redistribute it and/or
+      modify it under the terms of the GNU Lesser General Public
+      License as published by the Free Software Foundation; either
+      version 2.1 of the License, or (at your option) any later version.</p>
+
+    <p>This library is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+      Lesser General Public License for more details.</p>
+
+    <p>You should have received a copy of the GNU Lesser General Public
+      License along with this library; if not, write to the Free Software
+      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+      02110-1301, USA.</p>
+  </tp:license>
+
+  <interface name="org.freedesktop.Telepathy.Channel.Interface.Subject.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:added version="0.21.UNRELEASED">(draft 1)</tp:added>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface channels can implement to support subjects. Most
+        of the time this will be implemented by Room channels, but some
+        protocols support subjects in 1-to-1 chats (such as Skype).</p>
+    </tp:docstring>
+
+    <method name="SetSubject" tp:name-for-bindings="Set_Subject">
+      <arg direction="in" type="s" name="Subject">
+        <tp:docstring>The new subject.</tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Set the room's subject. Clients SHOULD look at the subject
+          flags before calling this method as the user might not have
+          permission to set the subject.</p>
+
+        <p>Clients SHOULD NOT assume success if no errors are raised
+          by calling this method, but instead should listen to the
+          <tp:member-ref>SubjectChanged</tp:member-ref> signal for
+          change notification.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+      </tp:possible-errors>
+    </method>
+
+    <tp:struct name="Room_Subject">
+      <tp:docstring>
+        A struct representing the subject of a room channel.
+      </tp:docstring>
+      <tp:member type="s" name="Subject">
+        <tp:docstring>
+           A human-readable description of the current subject of
+           conversation in the channel, similar to /topic in IRC.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Actor">
+        <tp:docstring>
+           A normalized contact ID representing who last modified the
+           subject, or the empty string if it is not known.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp">
+        <tp:docstring>
+           A unix timestamp indicating when the subject was last modified.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="u" tp:type="Room_Subject_Flags" name="Flags">
+        <tp:docstring>
+           A bitwise OR of the flags applicable to this channel's
+           subject.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <property name="Subject" tp:name-for-bindings="Subject"
+              type="(ssxu)" tp:type="Room_Subject" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The subject on the room such as the topic in an IRC channel,
+          or the room name in XMPP MUCs. In protocols which do not support
+          subjects (like MSN), this property should be ("", "", 0, 0).</p>
+
+        <tp:rationale>This property replaces the subject, subject-contact, and
+          subject-timestamp Telepathy properties of Text channels, as Telepathy
+          properties are soon to be deprecated completely.</tp:rationale>
+
+        <p>Change notification for this property is provided by the
+          <tp:member-ref>SubjectChanged</tp:member-ref> signal.</p>
+
+        <p>This property may change during the lifetime of the channel and
+          MUST not be included in a channel request.</p>
+      </tp:docstring>
+    </property>
+
+    <signal name="SubjectChanged" tp:name-for-bindings="Subject_Changed">
+      <arg name="Subject" type="s">
+        <tp:docstring>
+          The new subject string.
+        </tp:docstring>
+      </arg>
+      <arg name="Actor" type="s">
+        <tp:docstring>
+          A normalized contact ID representing who last modified the
+          subject, or the empty string if it is not known.
+        </tp:docstring>
+      </arg>
+      <arg name="Timestamp" type="x" tp:type="Unix_Timestamp64">
+        <tp:docstring>
+          A unix timestamp indicating when the subject was last
+          modified.
+        </tp:docstring>
+      </arg>
+      <arg name="Flags" type="u" tp:type="Room_Subject_Flags">
+        <tp:docstring>
+          A bitwise OR of the flags applicable to this channel's
+          subject.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Emitted when the <tp:member-ref>Subject</tp:member-ref>
+        property is changed.
+      </tp:docstring>
+    </signal>
+
+    <tp:flags name="Room_Subject_Flags"
+      value-prefix="Room_Subject_Flag" type="u">
+      <tp:docstring>
+        Flags indicating capabilities regarding the room subject.
+      </tp:docstring>
+
+      <tp:flag suffix="Present" value="1">
+        <tp:docstring>
+          A subject exists on this channel. Protocols which do not
+          have the concept of room subjects MUST NOT have this flag
+          set as an indication to clients that no notice should be
+          taken of the <tp:member-ref>Subject</tp:member-ref>
+          property. Note that this flag only allows clients to
+          distinguish between protocols which support room subjects
+          and protocols which do not. The presence of this flag
+          MUST NOT change.
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:flag suffix="Can_Set" value="2">
+        <tp:docstring>
+          The <tp:member-ref>Subject</tp:member-ref> property can be
+          set by the user by calling
+          <tp:member-ref>SetSubject</tp:member-ref>. If this flag is
+          set, then Present MUST also be set.
+        </tp:docstring>
+      </tp:flag>
+    </tp:flags>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 63833e78..45f18433 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -86,7 +86,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <dt>subject (s)</dt>
           <dd>The current subject of conversation in the room (as would
             be returned by getting the string part of the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+            namespace="org.freedesktop.Telepathy.Channel.Interface.Subject.DRAFT"
             >Subject</tp:dbus-ref> property)</dd>
 
           <dt>members (u)</dt>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index e851b26b..7989344d 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -496,7 +496,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
       A human-readable description of the current subject of conversation in
       the channel, similar to /topic in IRC. This is equivalent to the
-      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Subject.DRAFT"
       >Subject</tp:dbus-ref> property in the Room interface which will replace
       this Telepathy property.
       </tp:docstring>
@@ -505,7 +505,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
       A contact handle representing who last modified the subject, or 0
       if it isn't known. This is equivalent to the
-      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Subject.DRAFT"
       >Subject</tp:dbus-ref> property in the Room interface which will replace
       this Telepathy property.
       </tp:docstring>
@@ -514,7 +514,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
       A unix timestamp indicating when the subject was last modified.
       This is equivalent to the
-      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Subject.DRAFT"
       >Subject</tp:dbus-ref> property in the Room interface which will replace
       this Telepathy property.
       </tp:docstring>
diff --git a/spec/all.xml b/spec/all.xml
index 9ef6136f..14487f6e 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -165,6 +165,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Channel_Interface_SASL_Authentication.xml"/>
    <xi:include href="Channel_Interface_Securable.xml"/>
    <xi:include href="Channel_Interface_Service_Point.xml"/>
+   <xi:include href="Channel_Interface_Subject.xml"/>
    <xi:include href="Channel_Interface_Tube.xml"/>
 
    <tp:section name="Text-specific interfaces">