<?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>&</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: -->