[telepathy-spec/master] fd.o #24906, #24939: add first draft of Conference and Splittable
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Nov 25 05:25:57 PST 2009
---
spec/Channel_Interface_Conference.xml | 296 +++++++++++++++++++++++++++++++++
spec/Channel_Interface_Splittable.xml | 70 ++++++++
spec/all.xml | 2 +
3 files changed, 368 insertions(+), 0 deletions(-)
create mode 100644 spec/Channel_Interface_Conference.xml
create mode 100644 spec/Channel_Interface_Splittable.xml
diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
new file mode 100644
index 0000000..9f08d9f
--- /dev/null
+++ b/spec/Channel_Interface_Conference.xml
@@ -0,0 +1,296 @@
+<?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: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,
+ ...InitialChannels: [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,
+ ...InitialChannels: [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 at conf.example.com',
+ ...InitialChannels: [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,
+ ...InitialChannels: [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 Group 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>
+
+ </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
+ <strong>[FIXME: add some sort of signal]</strong>.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <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 Channels.</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>
+
+ Whether a request with 0 or 1 elements in the list will succeed is
+ indicated by SupportsNonMerges.
+
+ <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 Channels' 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 Merge 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="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]</strong></p>
+
+ <p>If true, requests with InitialChannels omitted, empty, or one
+ element long should be expected to succeed.</p>
+
+ <p>This property SHOULD appear in requestable channel classes for
+ conference channels if and only if its value on those channels will
+ be true.</p>
+
+ <tp:rationale>
+ <p>Putting this in RequestableChannelClasses 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>
+ </tp:rationale>
+
+ <p>If false, InitialChannels 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>
+
+ <method name="Merge"
+ tp:name-for-bindings="Merge">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given channel be incorporated into this
+ channel.</p>
+
+ <p>The given channel SHOULD be added to Channels if and only if the
+ underlying protocol signals the merge in some way. It MUST NOT be
+ added to InitialChannels (to preserve immutability).</p>
+
+ <tp:rationale>
+ <p>In GSM it is possible to merge additional calls into an ongoing
+ conference.</p>
+
+ <p>In XMPP this method could be implemented to merge a 1-1 Text
+ channel into a MUC Text channel by inviting the peer from the Text
+ channel into the MUC, or to merge a 1-1 Jingle call into a Muji
+ call by inviting the peer from the Jingle call into the Muji call.
+ (MUC and Muji channels are both implemented by XMPP MUCs, with
+ Handle_Type_Room.)</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel with 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>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Errors.InvalidArgument">
+ <tp:docstring>
+ The given channel isn't suitable for merging into this one: for
+ instance, it might have the wrong channel type or handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Errors.NotImplemented">
+ <tp:docstring>
+ It will never be possible to merge channels into this particular
+ conference.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+ <tp:docstring>
+ The given channel is theoretically suitable for merging into this
+ one, but that's not currently possible for some reason (for
+ instance, this SHOULD be raised if a limit on the number of
+ channels in a conference is exceeded). [FIXME: PermissionDenied?]
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml
new file mode 100644
index 0000000..6e461be
--- /dev/null
+++ b/spec/Channel_Interface_Splittable.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Splittable"
+ 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.Splittable.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels that can be made conceptually part of a
+ conference, and can then be detached from that conference.</p>
+
+ <tp:rationale>
+ <p>This interface addresses part of freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls). GSM is currently
+ the only protocol known to implement this; PBXs might implement
+ it too.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <method name="Split"
+ tp:name-for-bindings="Split">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that this channel is removed from any conference of which
+ it is a part.</p>
+
+ <p>This implies that the media streams within the conference are put on
+ hold and the media streams within the member channel leaving the
+ conference are unheld.
+ <strong>[FIXME: or, maybe it'd be less surprising if it didn't do
+ this?]</strong>
+ </p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Errors.InvalidArgument">
+ <tp:docstring>
+ This channel isn't in a conference.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+ <tp:docstring>
+ This channel is in a conference but can't currently be split away
+ from it.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/all.xml b/spec/all.xml
index 1b970f6..69f9cfd 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -98,6 +98,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_Call_Merging.xml"/>
<xi:include href="Channel_Interface_Call_State.xml"/>
<xi:include href="Channel_Interface_Chat_State.xml"/>
+ <xi:include href="Channel_Interface_Conference.xml"/>
<xi:include href="Channel_Interface_Destroyable.xml"/>
<xi:include href="Channel_Interface_DTMF.xml"/>
<xi:include href="Channel_Interface_Group.xml"/>
@@ -106,6 +107,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_Password.xml"/>
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
<xi:include href="Channel_Interface_Messages.xml"/>
+ <xi:include href="Channel_Interface_Splittable.xml"/>
<xi:include href="Channel_Interface_Tube.xml"/>
</tp:section>
</tp:section>
--
1.5.6.5
More information about the telepathy-commits
mailing list