[telepathy-spec/master] Conference: move the Merge interface into a new MergeableConference interface
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Dec 1 06:58:00 PST 2009
It might be moved back in a later draft, but the conservative thing to do
is to have less API for now.
---
spec/Channel_Interface_Conference.xml | 65 +-------------
spec/Channel_Interface_Mergeable_Conference.xml | 109 +++++++++++++++++++++++
spec/all.xml | 1 +
3 files changed, 113 insertions(+), 62 deletions(-)
create mode 100644 spec/Channel_Interface_Mergeable_Conference.xml
diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
index 13aafc6..2a44aca 100644
--- a/spec/Channel_Interface_Conference.xml
+++ b/spec/Channel_Interface_Conference.xml
@@ -210,7 +210,9 @@
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:member-ref>Merge</tp:member-ref> on them.
+ <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>
@@ -393,66 +395,5 @@
</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
- <tp:member-ref>Channels</tp:member-ref> if and only if the
- underlying protocol signals the merge in some way. It MUST NOT be
- added to <tp:member-ref>InitialChannels</tp:member-ref> (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 xmlns="http://www.w3.org/1999/xhtml">
- 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).
- <strong>[FIXME: PermissionDenied?]</strong>
- </tp:docstring>
- </tp:error>
- </tp:possible-errors>
- </method>
-
</interface>
</node>
diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml
new file mode 100644
index 0000000..95d815b
--- /dev/null
+++ b/spec/Channel_Interface_Mergeable_Conference.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Mergeable_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.MergeableConference.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Conference.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for multi-user conference channels that can have
+ additional individual channels merged into them after they are
+ created.</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>
+
+ <p>It might be made into a mandatory-to-implement part of Conference,
+ or kept as a separate interface, when stabilized.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.DRAFT.Channels</tp:dbus-ref> if and only if the
+ underlying protocol signals the merge in some way. It MUST NOT be
+ added to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.DRAFT.InitialChannels</tp:dbus-ref> (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 xmlns="http://www.w3.org/1999/xhtml">
+ 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).
+ <strong>[FIXME: PermissionDenied?]</strong>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/all.xml b/spec/all.xml
index d9f16ee..e061871 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -105,6 +105,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_HTML.xml"/>
<xi:include href="Channel_Interface_Password.xml"/>
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
+ <xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
<xi:include href="Channel_Interface_Messages.xml"/>
<xi:include href="Channel_Interface_Splittable.xml"/>
<xi:include href="Channel_Interface_Tube.xml"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list