Merge branch 'room'

Conflicts:
	src/muc-channel.c
	tests/twisted/constants.py

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

3 files changed, 377 insertions, 2 deletions

diff --git a/extensions/Channel_Interface_Room.xml b/extensions/Channel_Interface_Room.xml
new file mode 100644
index 000000000..ffdf4a96d
--- /dev/null
+++ b/extensions/Channel_Interface_Room.xml
@@ -0,0 +1,373 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Room"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2010 Nokia Corporation</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.Room.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:added version="0.19.11">(draft 1)</tp:added>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>Different IM protocols use a variety of ways to name chat rooms. The
+        simplest example is perhaps IRC, where chat rooms have short,
+        persistent, human-readable string names, and are generally global
+        across the network. Skype chat rooms have persistent string names, so
+        you can leave and re-join a room, but these names are opaque unique
+        identifiers. MSN chat rooms are unnamed, and you can only join one by
+        being invited. And XMPP wins the coveted “most complicated chat rooms”
+        prize: chat rooms may be hosted by different servers with different DNS
+        names; normally they have human-readable names, except that all MUCs on
+        Google Talk's conference server have UUIDs as names, and <a
+          href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym
+          title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4
+        <q>Requesting a Unique Room Name</q></a> defines a protocol for
+        requesting a unique, opaque room name on the server.</p>
+
+      <p>This interface intends to support and differentiate these mechanisms
+        more clearly than the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+        and <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+        properties can alone. It initially contains a pair of properties used
+        to represent the human-readable parts of a
+        <tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples
+        for different protocols are represented as follows:</p>
+
+      <ul>
+        <li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a
+          channel with properties
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>Room</code>,
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+          = <code>"#telepathy"</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>,
+          <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+          that the room has a human-readable identifier, and is not confined to
+          a particular server on the network.
+
+          <tp:rationale>
+            Actually, IRC supports creating “local” channels specific to the
+            server they are created on. These channels have identifiers
+            starting with <tt>&amp;</tt> rather than <tt>#</tt>. These could be
+            represented by setting <tp:member-ref>Server</tp:member-ref>
+            appropriately.
+          </tp:rationale>
+        </li>
+
+        <li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>Room</code>,
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+          = <code>"0xdeadbeef"</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+          <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+          that the room has an identifier but no human-readable name.
+        </li>
+
+        <li>An MSN group chat has
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>None</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+          <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+          that the room has neither an identifier (so it cannot be re-joined
+          later) nor a human-readable name.
+        </li>
+
+        <li>A standard Jabber multi-user chat
+          <tt>jdev@conference.jabber.org</tt> has
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>Room</code>,
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+          = <code>"jdev@conference.jabber.org"</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>,
+          <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>.
+        </li>
+
+        <li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>Room</code>,
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+          = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+          <tp:member-ref>Server</tp:member-ref> =
+          <code>"groupchat.google.com"</code>, indicating that the room has a
+          persistent identifier, no human-readable name, and is hosted by a
+          particular server.
+        </li>
+
+        <li>Similarly, a XEP-0045 §10.1.4 uniquely-named room
+          <tt>lrcgsnthzvwm@conference.jabber.org</tt> has
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+          = <code>Room</code>,
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+          = <code>"lrcgsnthzvwm@conference.jabber.org"</code>,
+          <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+          <tp:member-ref>Server</tp:member-ref> =
+          <code>"conference.jabber.org"</code>, indicating that the room has a
+          persistent identifier, no human-readable name, and is hosted by a
+          particular server.
+        </li>
+      </ul>
+
+      <h4>Requestable channel classes</h4>
+
+      <p>If the connection supports joining text chat rooms by unique
+        identifier, like Skype, it should advertise a
+        <tp:type>Requestable_Channel_Class</tp:type> matching:</p>
+
+      <blockquote>
+        <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+                                        >Text</tp:dbus-ref>,
+            ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >TargetHandleType</tp:dbus-ref>: Room,
+          },
+  Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+              >TargetID</tp:dbus-ref>,
+              ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+              >TargetHandle</tp:dbus-ref>,
+            ]
+)</pre></blockquote>
+
+      <p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+        >TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+        >TargetHandle</tp:dbus-ref>.</p>
+
+      <p>If, like IRC, the room identifiers are also human-readable, the
+        RCCs should also include RoomID in <var>Allowed_Properties</var>:</p>
+
+      <blockquote>
+        <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+                                        >Text</tp:dbus-ref>,
+            ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >TargetHandleType</tp:dbus-ref>: Room,
+          },
+  Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+              >TargetID</tp:dbus-ref>,
+              ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+              >TargetHandle</tp:dbus-ref>,
+              ...<tp:member-ref>RoomID</tp:member-ref>
+            ]
+),
+
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+                                        >Text</tp:dbus-ref>
+          },
+  Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>,
+            ]
+)</pre></blockquote>
+
+      <p>Requests may specify the RoomID in place of
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+        . Note how <tp:member-ref>RoomID</tp:member-ref> appears
+        in <var>Allowed_Properties</var> of a different RCC because
+        when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+        >TargetHandleType</tp:dbus-ref> is omitted (or is None), both
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+        >TargetHandle</tp:dbus-ref> and
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+        >TargetID</tp:dbus-ref> must also be omitted.
+        <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction
+        with
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+        in some situations, as explained below in the <em>Requesting room
+        channels</em> section.
+      </p>
+
+      <p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref>
+        should also be included in the allowed properties, but
+        CMs MUST use a reasonable default
+        <tp:member-ref>Server</tp:member-ref> if not explicitly
+        specified in a channel request. The CM's default server MAY
+        be configurable by a connection parameter specified on a
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
+        >RequestConnection</tp:dbus-ref> call, similarly to how the
+        fallback conference server is specified on jabber connections in
+        gabble.</p>
+
+      <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref>
+        should be fixed to the empty string, and
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+        should be None:</p>
+
+      <blockquote>
+        <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+                                        >Text</tp:dbus-ref>,
+            ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+            >TargetHandleType</tp:dbus-ref>: None,
+            ...<tp:member-ref>RoomID</tp:member-ref>: "",
+          },
+  Allowed = [ ]
+)</pre></blockquote>
+
+      <h4>Requesting room channels</h4>
+
+      <p>When explicitly joining a room, the CM cannot know whether the room
+        ID is unique or not. As a result, if this is the case, adding an
+        empty string <tp:member-ref>RoomID</tp:member-ref> into the channel
+        request will ensure the CM knows. For example:</p>
+
+      <blockquote>
+        <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+  ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
+  ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org",
+  ...<tp:member-ref>RoomID</tp:member-ref>: ""
+}</pre></blockquote>
+
+      <p>If <tp:member-ref>RoomID</tp:member-ref> features in
+        <var>Allowed_Properties</var> then the only value allowed in conjunction
+        with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+        or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+        is the empty string. Requests with conflicting
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+        and <tp:member-ref>RoomID</tp:member-ref> properties
+        will fail with InvalidArgument.</p>
+
+      <p>To create a XEP-0045 §10.1.4 uniquely-named room channel
+        on the conference.jabber.org server, then the following channel
+        request should be made:</p>
+
+      <blockquote>
+        <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+  ...<tp:member-ref>RoomID</tp:member-ref>: ""
+  ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
+}</pre>
+      </blockquote>
+
+      <p>If everything is successful, then when the channel request is
+        satisfied, a new channel will appear with the following properties:</p>
+
+      <blockquote>
+        <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+  ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
+  ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
+  ...<tp:member-ref>RoomID</tp:member-ref>: ""
+  ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
+}</pre>
+      </blockquote>
+
+      <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs)
+        and then created a room with such a name on the said server. The empty
+        <tp:member-ref>RoomID</tp:member-ref> property shows that the room name
+        is not human-readable.</p>
+
+    </tp:docstring>
+
+    <property name="RoomID" tp:name-for-bindings="Room_ID" type="s"
+              access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The human-readable identifier of a chat room. Note that if
+          non-empty, this property (and perhaps also
+          <tp:member-ref>Server</tp:member-ref>) should be sufficient in
+          a channel request to join the room. XMPP MUCs have a room name
+          concept which is more like a topic, except more
+          persistent. This D-Bus property is <strong>not</strong> this
+          XMPP room name, but the bit before the @ in the room jid.</p>
+
+        <p>This property cannot change during the lifetime of the channel. It
+          should appear in the <var>Allowed_Properties</var> of a
+          <tp:type>Requestable_Channel_Class</tp:type> for the connection if
+          rooms on this connection have human-readable names, and can be joined
+          by name.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Server" tp:name-for-bindings="Server" type="s"
+              access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>For protocols with a concept of chatrooms on multiple servers with
+          different DNS names (like XMPP), the DNS name of the server hosting
+          this channel (for example, <tt>"conference.jabber.org"</tt> or
+          <tt>"groupchat.google.com"</tt>). For other protocols, the empty
+          string.</p>
+
+        <p>This property cannot change during the lifetime of the channel. It
+          should appear in the <var>Allowed_Properties</var> of a
+          <tp:type>Requestable_Channel_Class</tp:type> for the connection if
+          and only if non-empty values are supported.</p>
+      </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:struct>
+
+    <property name="Subject" tp:name-for-bindings="Subject"
+              type="(ssx)" 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).</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>This property may change during the lifetime of the channel and
+          MUST not be included in a channel request.</p>
+      </tp:docstring>
+    </property>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 793db77cb..3a1c676a3 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -8,7 +8,8 @@ EXTRA_DIST = \
     Gabble_Plugin_Gateways.xml \
     Gabble_Plugin_Test.xml \
     OLPC_Activity_Properties.xml \
-    OLPC_Buddy_Info.xml
+    OLPC_Buddy_Info.xml \
+    Channel_Interface_Room.xml
 
 noinst_LTLIBRARIES = libgabble-extensions.la
 
diff --git a/extensions/all.xml b/extensions/all.xml
index 86ad89318..85380615c 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -39,6 +39,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>
 <xi:include href="Channel_Type_FileTransfer_Future.xml"/>
 <xi:include href="Connection_Interface_Gabble_Decloak.xml"/>
 <xi:include href="Connection_Future.xml"/>
+<xi:include href="Channel_Interface_Room.xml"/>
 
 <xi:include href="Gabble_Plugin_Gateways.xml"/>
 <xi:include href="Gabble_Plugin_Test.xml"/>
@@ -70,7 +71,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>
     from="Telepathy specification"/>
   <tp:external-type name="Rich_Presence_Access_Control" type="(uv)"
     from="Telepathy specification"/>
-  <tp:external-type name="Unix_Timestamp64" type="t"
+  <tp:external-type name="Unix_Timestamp64" type="x"
     from="Telepathy specification"/>
   <tp:external-type name="Unix_Timestamp" type="u"
     from="Telepathy specification"/>