path: root/spec/Channel_Interface_Room.xml

<?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.UNRELEASED">(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: -->