<?xml version="1.0" ?>
<node name="/Channel_Interface_Conference"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2009 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.Conference.DRAFT"
tp:causes-havoc="experimental">
<tp:added version="0.19.0">(draft 1)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires
interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for multi-user conference channels that can "continue
from" one or more individual channels.</p>
<tp:rationale>
<p>This interface addresses freedesktop.org <a
href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
#24906</a> (GSM-compatible conference calls) and <a
href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug
#24939</a> (upgrading calls and chats to multi-user).
See those bugs for rationale and use cases.</p>
<p>Examples of usage:</p>
<p>Active and held GSM calls C1, C2 can be merged into a single
channel Cn with the Conference interface, by calling
<code>CreateChannel({...ChannelType: ...Call,
...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]})</code>
which returns Cn.</p>
<p>An XMPP 1-1 conversation C1 can be continued in a newly created
multi-user chatroom Cn by calling
<code>CreateChannel({...ChannelType: ...Text,
...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
which returns Cn.</p>
<p>An XMPP 1-1 conversation C1 can be continued in a specified
multi-user chatroom by calling
<code>CreateChannel({...ChannelType: ...Text, ...HandleType: ROOM,
...TargetID: 'telepathy@conf.example.com',
...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
which returns a Conference channel.</p>
<p>Either of the XMPP cases could work for Call channels, to
upgrade from 1-1 Jingle to multi-user Muji. Any of the XMPP cases
could in principle work for link-local XMPP (XEP-0174).</p>
<p>The underlying switchboard representing an MSN 1-1 conversation C1
with a contact X can be moved to a representation as a nameless
chatroom, Cn, to which more contacts can be invited, by calling
<code>CreateChannel({...ChannelType: ...Text,
...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
which returns Cn. C1 SHOULD remain open, with no underlying
switchboard attached. If X establishes a new switchboard with the
local user, C1 SHOULD pick up that switchboard rather than letting
it create a new channel.
<strong>[FIXME: should it?]</strong>
Similarly, if the local user sends a message in C1, then
a new switchboard to X should be created and associated with C1.</p>
<p>XMPP and MSN do not natively have a concept of merging two or more
channels C1, C2... into one channel, Cn. However, the GSM-style
merging API can be supported on XMPP and MSN, as an API short-cut
for upgrading C1 into a conference Cn (which invites the
TargetHandle of C1 into Cn), then immediately inviting the
TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p>
<p>With a suitable change of terminology, Skype has behaviour similar
to MSN.</p>
</tp:rationale>
<p>The <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface"
>Group</tp:dbus-ref> MAY have channel-specific handles for participants;
clients SHOULD support both Conferences that have channel-specific handles,
and those that do not.</p>
<tp:rationale>
<p>In the GSM case, the Conference's Group interface MAY have
channel-specific handles, to reflect the fact that the identities of
the participants might not be known - it can be possible to know that
there is another participant in the Conference, but not know who
they are.
<strong>[FIXME: fact check from GSM gurus needed]</strong>
</p>
<p>In the XMPP case, the Conference's Group interface SHOULD have
channel-specific handles, to reflect the fact that the participants
have MUC-specific identities, and the user might also be able to see
their global identities, or not.</p>
<p>In most other cases, including MSN and link-local XMPP, the
Conference's Group interface SHOULD NOT have channel-specific
handles, since users' identities are always visible.</p>
</tp:rationale>
<p>Connection managers implementing channels with this interface
MUST NOT allow the object paths of channels that could be merged
into a Conference to be re-used, unless the channel re-using the
object path is equivalent to the channel that previously used it.</p>
<tp:rationale>
<p>If you upgrade some channels into a conference, and then close
the original channels, <tp:member-ref>InitialChannels</tp:member-ref>
(which is immutable) will contain paths to channels which no longer
exist. This implies that you should not re-use channel object paths,
unless future incarnations of the path are equivalent.</p>
<p>For instance, on protocols where you can only have
zero or one 1-1 text channels with Emily at one time, it would
be OK to re-use the same object path for every 1-1 text channel
with Emily; but on protocols where this is not true, it would
be misleading.</p>
</tp:rationale>
</tp:docstring>
<property name="Channels" tp:name-for-bindings="Channels"
access="read" type="ao">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The individual <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that
are continued by this conference, which have the same <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel"
>ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel"
>TargetHandleType</tp:dbus-ref> = CONTACT.</p>
<p>This property MUST NOT be requestable.
<strong>[FIXME: or would it be better for this one, and not IC, to be
requestable?]</strong>
</p>
<p>Change notification is via the
<tp:member-ref>ChannelMerged</tp:member-ref> and
<tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p>
</tp:docstring>
</property>
<signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when a new channel is added to the value of
<tp:member-ref>Channels</tp:member-ref>.</p>
</tp:docstring>
<arg name="Channel" type="o">
<tp:docstring>The channel that was added to
<tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
</arg>
</signal>
<signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when a channel is removed from the value of
<tp:member-ref>Channels</tp:member-ref>, either because it closed
or because it was split using the <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface"
>Splittable.DRAFT.Split</tp:dbus-ref> method.</p>
<p><strong>[FIXME: relative ordering of this vs. Closed? Do we
care?]</strong></p>
</tp:docstring>
<arg name="Channel" type="o">
<tp:docstring>The channel that was removed from
<tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
</arg>
</signal>
<property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
access="read" type="ao">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p>
<p>This property SHOULD be requestable. Omitting it from a request is
equivalent to providing it with an empty list as value. Requests
where its value has at least two elements SHOULD be expected to
succeed on any implementation of this interface.</p>
<p>Whether a request with 0 or 1 elements in the list will succeed is
indicated by <tp:member-ref>SupportsNonMerges</tp:member-ref>.</p>
<tp:rationale>
<p>In GSM, a pair of calls can be merged into a conference. In XMPP
and MSN, you can create a new chatroom, or upgrade one 1-1 channel
into a chatroom; however, on these protocols, it is also possible
to fake GSM-style merging by upgrading the first channel, then
inviting the targets of all the other channels into it.</p>
</tp:rationale>
<p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD
NOT be altered by merging them into a conference. However, depending on
the protocol, the Channels MAY be placed in a "frozen" state by placing
them in this property's value or by calling
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface"
>MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.
<strong>[FIXME: there's nothing in RequestableChannelClasses yet
to say what will happen, see #24906 comment 6]</strong></p>
<tp:rationale>
<p>In Jingle, nothing special will happen to merged calls. UIs MAY
automatically place calls on hold before merging them, if that is
the desired behaviour; this SHOULD always work. Not doing
an implicit hold/unhold seems to preserve least-astonishment.</p>
<p><strong>[FIXME: check whether ring supports faking Hold on both
channels, as it probably should: see #24906 comment 6]</strong>
</p>
<p>In GSM, the calls that are merged go into a state similar to
Hold, but they cannot be unheld, only split from the conference
call using <tp:dbus-ref namespace="org.freedesktop.Telepathy"
>Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p>
</tp:rationale>
<p>Depending on the protocol, it might be signalled to remote users
that this channel is a continuation of all the requested channels,
or that it is only a continuation of the first channel in the
list.</p>
<tp:rationale>
<p>In MSN, the conference steals the underlying switchboard (protocol
construct) from one of its component channels, so the conference
appears to remote users to be a continuation of that channel and no
other. The connection manager has to make some arbitrary choice, so
we arbitrarily mandate that it SHOULD choose the first channel in
the list as the one to continue.</p>
</tp:rationale>
<p>This property is immutable.</p>
</tp:docstring>
</property>
<property name="InitialInviteeHandles"
tp:name-for-bindings="Initial_Invitee_Handles"
access="read" type="au" tp:type="Contact_Handle[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of additional contacts invited to this conference when it
was created.</p>
<p>This property SHOULD be requestable, and appear in the allowed
properties in <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref>, in all connection
managers that can implement its semantics (in practice, this is
likely to mean exactly those connection managers where
<tp:member-ref>SupportsNonMerges</tp:member-ref> will be true).</p>
<p>If included in a request, the given contacts are automatically
invited into the new channel, as if they had been added with
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
>Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
<tp:member-ref>InvitationMessage</tp:member-ref> immediately after
the channel was created.</p>
<tp:rationale>
<p>This is a simple convenience API for the common case that a UI
upgrades a 1-1 chat to a multi-user chat solely in order to invite
someone else to participate.</p>
</tp:rationale>
<p>At most one of InitialInviteeHandles and InitialInviteeIDs may
appear in each request.</p>
<p>If the local user was not the initiator of this channel, the
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
>Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
property, together with any other contacts invited at the same time
(if that information is known).</p>
<p>This property is immutable.</p>
</tp:docstring>
</property>
<property name="InitialInviteeIDs"
tp:name-for-bindings="Initial_Invitee_IDs"
access="read" type="as">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of additional contacts invited to this conference when it
was created.</p>
<p>This property SHOULD be requestable, as an alternative to
<tp:member-ref>InitialInviteeHandles</tp:member-ref>. Its semantics
are the same, except that it takes a list of the string
representations of contact handles.</p>
<p>At most one of InitialInviteeHandles and InitialInviteeIDs may
appear in each request.</p>
<p>When a channel is created, the values of InitialInviteeHandles and
InitialInviteeIDs MUST correspond to each other.</p>
<p>This property is immutable.</p>
</tp:docstring>
</property>
<property name="InvitationMessage" tp:name-for-bindings="Invitation_Message"
access="read" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The message that was sent to the
<tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were
invited.</p>
<p>This property SHOULD be requestable, and appear in the allowed
properties in <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref>, in protocols where
invitations can have an accompanying text message.</p>
<tp:rationale>
<p>This allows invitations with a message to be sent when using
<tp:member-ref>InitialInviteeHandles</tp:member-ref> or
<tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p>
</tp:rationale>
<p>If the local user was not the initiator of this channel, the
message with which they were invited (if any) SHOULD appear in the
value of this property.</p>
<p>This property is immutable.</p>
</tp:docstring>
</property>
<property name="SupportsNonMerges"
tp:name-for-bindings="Supports_Non_Merges"
access="read" type="b">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p><strong>[FIXME: needs a better name; or perhaps it could be implied
by InitialInviteeHandles being requestable in XMPP/MSN but not in
GSM?]</strong></p>
<p>If true, requests with <tp:member-ref>InitialChannels</tp:member-ref>
omitted, empty, or one element long should be expected to succeed.</p>
<p>This property SHOULD appear in <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref> for
conference channels if and only if its value on those channels will
be true.</p>
<tp:rationale>
<p>Putting this in <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref> means clients can find
out whether their request will succeed early enough to do
something about it.</p>
<p>In XMPP, you can request a channel of type ROOM without
incorporating any 1-1 chats at all - indeed, this is the normal
way to do it - or as a continuation of a single 1-1 chat, and then
invite other people in later.</p>
<p>The sense of this property is a bit awkward, but it avoids making it
an anti-capability. If the sense were inverted, then its presence in
RequestableChannelClasses would imply that the protocol <em>lacks</em>
a feature; as it stands, it is additive. (Contrast with
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"
>ImmutableStreams</tp:dbus-ref>, which is the wrong way around for
backwards-compatibility reasons.)</p>
</tp:rationale>
<p>If false, <tp:member-ref>InitialChannels</tp:member-ref> SHOULD be
supplied in all requests for this channel class, and contain at least
two channels. Requests where this requirement is not met SHOULD fail
with NotImplemented.
</p>
<tp:rationale>
<p>In GSM, you can only make a conference call by merging at least
two channels.
<strong>[FIXME: the CM could conceivably fake it, but that would be
rather nasty]</strong>
</p>
</tp:rationale>
</tp:docstring>
</property>
</interface>
</node>
