2 <node name="/Channel_Interface_Conference"
3 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
4 <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
5 <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.</p>
12 <p>This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.</p>
17 <p>You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
23 name="org.freedesktop.Telepathy.Channel.Interface.Conference.DRAFT"
24 tp:causes-havoc="experimental">
25 <tp:added version="0.19.0">(draft 1)</tp:added>
26 <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
28 interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
30 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
31 <p>An interface for multi-user conference channels that can "continue
32 from" one or more individual channels.</p>
35 <p>This interface addresses freedesktop.org <a
36 href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
37 #24906</a> (GSM-compatible conference calls) and <a
38 href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug
39 #24939</a> (upgrading calls and chats to multi-user).
40 See those bugs for rationale and use cases.</p>
42 <p>Examples of usage:</p>
44 <p>Active and held GSM calls C1, C2 can be merged into a single
45 channel Cn with the Conference interface, by calling
46 <code>CreateChannel({...ChannelType: ...Call,
47 ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]})</code>
50 <p>An XMPP 1-1 conversation C1 can be continued in a newly created
51 multi-user chatroom Cn by calling
52 <code>CreateChannel({...ChannelType: ...Text,
53 ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
56 <p>An XMPP 1-1 conversation C1 can be continued in a specified
57 multi-user chatroom by calling
58 <code>CreateChannel({...ChannelType: ...Text, ...HandleType: ROOM,
59 ...TargetID: 'telepathy@conf.example.com',
60 ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
61 which returns a Conference channel.</p>
63 <p>Either of the XMPP cases could work for Call channels, to
64 upgrade from 1-1 Jingle to multi-user Muji. Any of the XMPP cases
65 could in principle work for link-local XMPP (XEP-0174).</p>
67 <p>The underlying switchboard representing an MSN 1-1 conversation C1
68 with a contact X can be moved to a representation as a nameless
69 chatroom, Cn, to which more contacts can be invited, by calling
70 <code>CreateChannel({...ChannelType: ...Text,
71 ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code>
72 which returns Cn. C1 SHOULD remain open, with no underlying
73 switchboard attached. If X establishes a new switchboard with the
74 local user, C1 SHOULD pick up that switchboard rather than letting
75 it create a new channel.
76 <strong>[FIXME: should it?]</strong>
77 Similarly, if the local user sends a message in C1, then
78 a new switchboard to X should be created and associated with C1.</p>
80 <p>XMPP and MSN do not natively have a concept of merging two or more
81 channels C1, C2... into one channel, Cn. However, the GSM-style
82 merging API can be supported on XMPP and MSN, as an API short-cut
83 for upgrading C1 into a conference Cn (which invites the
84 TargetHandle of C1 into Cn), then immediately inviting the
85 TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p>
87 <p>With a suitable change of terminology, Skype has behaviour similar
92 namespace="org.freedesktop.Telepathy.Channel.Interface"
93 >Group</tp:dbus-ref> MAY have channel-specific handles for participants;
94 clients SHOULD support both Conferences that have channel-specific handles,
95 and those that do not.</p>
98 <p>In the GSM case, the Conference's Group interface MAY have
99 channel-specific handles, to reflect the fact that the identities of
100 the participants might not be known - it can be possible to know that
101 there is another participant in the Conference, but not know who
103 <strong>[FIXME: fact check from GSM gurus needed]</strong>
106 <p>In the XMPP case, the Conference's Group interface SHOULD have
107 channel-specific handles, to reflect the fact that the participants
108 have MUC-specific identities, and the user might also be able to see
109 their global identities, or not.</p>
111 <p>In most other cases, including MSN and link-local XMPP, the
112 Conference's Group interface SHOULD NOT have channel-specific
113 handles, since users' identities are always visible.</p>
116 <p>Connection managers implementing channels with this interface
117 MUST NOT allow the object paths of channels that could be merged
118 into a Conference to be re-used, unless the channel re-using the
119 object path is equivalent to the channel that previously used it.</p>
122 <p>If you upgrade some channels into a conference, and then close
123 the original channels, <tp:member-ref>InitialChannels</tp:member-ref>
124 (which is immutable) will contain paths to channels which no longer
125 exist. This implies that you should not re-use channel object paths,
126 unless future incarnations of the path are equivalent.</p>
128 <p>For instance, on protocols where you can only have
129 zero or one 1-1 text channels with Emily at one time, it would
130 be OK to re-use the same object path for every 1-1 text channel
131 with Emily; but on protocols where this is not true, it would
137 <property name="Channels" tp:name-for-bindings="Channels"
138 access="read" type="ao">
139 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
140 <p>The individual <tp:dbus-ref
141 namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that
142 are continued by this conference, which have the same <tp:dbus-ref
143 namespace="org.freedesktop.Telepathy.Channel"
144 >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
145 namespace="org.freedesktop.Telepathy.Channel"
146 >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
148 <p>This property MUST NOT be requestable.
149 <strong>[FIXME: or would it be better for this one, and not IC, to be
150 requestable?]</strong>
153 <p>Change notification is via the
154 <tp:member-ref>ChannelMerged</tp:member-ref> and
155 <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p>
159 <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged">
160 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
161 <p>Emitted when a new channel is added to the value of
162 <tp:member-ref>Channels</tp:member-ref>.</p>
165 <arg name="Channel" type="o">
166 <tp:docstring>The channel that was added to
167 <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
171 <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
172 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
173 <p>Emitted when a channel is removed from the value of
174 <tp:member-ref>Channels</tp:member-ref>, either because it closed
175 or because it was split using the <tp:dbus-ref
176 namespace="org.freedesktop.Telepathy.Channel.Interface"
177 >Splittable.DRAFT.Split</tp:dbus-ref> method.</p>
179 <p><strong>[FIXME: relative ordering of this vs. Closed? Do we
183 <arg name="Channel" type="o">
184 <tp:docstring>The channel that was removed from
185 <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
189 <property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
190 access="read" type="ao">
191 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
192 <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p>
194 <p>This property SHOULD be requestable. Omitting it from a request is
195 equivalent to providing it with an empty list as value. Requests
196 where its value has at least two elements SHOULD be expected to
197 succeed on any implementation of this interface.</p>
199 <p>Whether a request with 0 or 1 elements in the list will succeed is
200 indicated by <tp:member-ref>SupportsNonMerges</tp:member-ref>.</p>
203 <p>In GSM, a pair of calls can be merged into a conference. In XMPP
204 and MSN, you can create a new chatroom, or upgrade one 1-1 channel
205 into a chatroom; however, on these protocols, it is also possible
206 to fake GSM-style merging by upgrading the first channel, then
207 inviting the targets of all the other channels into it.</p>
210 <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD
211 NOT be altered by merging them into a conference. However, depending on
212 the protocol, the Channels MAY be placed in a "frozen" state by placing
213 them in this property's value or by calling
215 namespace="org.freedesktop.Telepathy.Channel.Interface"
216 >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.
217 <strong>[FIXME: there's nothing in RequestableChannelClasses yet
218 to say what will happen, see #24906 comment 6]</strong></p>
221 <p>In Jingle, nothing special will happen to merged calls. UIs MAY
222 automatically place calls on hold before merging them, if that is
223 the desired behaviour; this SHOULD always work. Not doing
224 an implicit hold/unhold seems to preserve least-astonishment.</p>
226 <p><strong>[FIXME: check whether ring supports faking Hold on both
227 channels, as it probably should: see #24906 comment 6]</strong>
230 <p>In GSM, the calls that are merged go into a state similar to
231 Hold, but they cannot be unheld, only split from the conference
232 call using <tp:dbus-ref namespace="org.freedesktop.Telepathy"
233 >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p>
236 <p>Depending on the protocol, it might be signalled to remote users
237 that this channel is a continuation of all the requested channels,
238 or that it is only a continuation of the first channel in the
242 <p>In MSN, the conference steals the underlying switchboard (protocol
243 construct) from one of its component channels, so the conference
244 appears to remote users to be a continuation of that channel and no
245 other. The connection manager has to make some arbitrary choice, so
246 we arbitrarily mandate that it SHOULD choose the first channel in
247 the list as the one to continue.</p>
250 <p>This property is immutable.</p>
254 <property name="InitialInviteeHandles"
255 tp:name-for-bindings="Initial_Invitee_Handles"
256 access="read" type="au" tp:type="Contact_Handle[]">
257 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
258 <p>A list of additional contacts invited to this conference when it
261 <p>This property SHOULD be requestable, and appear in the allowed
262 properties in <tp:dbus-ref
263 namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
264 >RequestableChannelClasses</tp:dbus-ref>, in all connection
265 managers that can implement its semantics (in practice, this is
266 likely to mean exactly those connection managers where
267 <tp:member-ref>SupportsNonMerges</tp:member-ref> will be true).</p>
269 <p>If included in a request, the given contacts are automatically
270 invited into the new channel, as if they had been added with
271 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
272 >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
273 <tp:member-ref>InvitationMessage</tp:member-ref> immediately after
274 the channel was created.</p>
277 <p>This is a simple convenience API for the common case that a UI
278 upgrades a 1-1 chat to a multi-user chat solely in order to invite
279 someone else to participate.</p>
282 <p>At most one of InitialInviteeHandles and InitialInviteeIDs may
283 appear in each request.</p>
285 <p>If the local user was not the initiator of this channel, the
286 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
287 >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
288 property, together with any other contacts invited at the same time
289 (if that information is known).</p>
291 <p>This property is immutable.</p>
295 <property name="InitialInviteeIDs"
296 tp:name-for-bindings="Initial_Invitee_IDs"
297 access="read" type="as">
298 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
299 <p>A list of additional contacts invited to this conference when it
302 <p>This property SHOULD be requestable, as an alternative to
303 <tp:member-ref>InitialInviteeHandles</tp:member-ref>. Its semantics
304 are the same, except that it takes a list of the string
305 representations of contact handles.</p>
307 <p>At most one of InitialInviteeHandles and InitialInviteeIDs may
308 appear in each request.</p>
310 <p>When a channel is created, the values of InitialInviteeHandles and
311 InitialInviteeIDs MUST correspond to each other.</p>
313 <p>This property is immutable.</p>
317 <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message"
318 access="read" type="s">
319 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
320 <p>The message that was sent to the
321 <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were
324 <p>This property SHOULD be requestable, and appear in the allowed
325 properties in <tp:dbus-ref
326 namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
327 >RequestableChannelClasses</tp:dbus-ref>, in protocols where
328 invitations can have an accompanying text message.</p>
331 <p>This allows invitations with a message to be sent when using
332 <tp:member-ref>InitialInviteeHandles</tp:member-ref> or
333 <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p>
336 <p>If the local user was not the initiator of this channel, the
337 message with which they were invited (if any) SHOULD appear in the
338 value of this property.</p>
340 <p>This property is immutable.</p>
344 <property name="SupportsNonMerges"
345 tp:name-for-bindings="Supports_Non_Merges"
346 access="read" type="b">
347 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
348 <p><strong>[FIXME: needs a better name; or perhaps it could be implied
349 by InitialInviteeHandles being requestable in XMPP/MSN but not in
352 <p>If true, requests with <tp:member-ref>InitialChannels</tp:member-ref>
353 omitted, empty, or one element long should be expected to succeed.</p>
355 <p>This property SHOULD appear in <tp:dbus-ref
356 namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
357 >RequestableChannelClasses</tp:dbus-ref> for
358 conference channels if and only if its value on those channels will
362 <p>Putting this in <tp:dbus-ref
363 namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
364 >RequestableChannelClasses</tp:dbus-ref> means clients can find
365 out whether their request will succeed early enough to do
366 something about it.</p>
368 <p>In XMPP, you can request a channel of type ROOM without
369 incorporating any 1-1 chats at all - indeed, this is the normal
370 way to do it - or as a continuation of a single 1-1 chat, and then
371 invite other people in later.</p>
373 <p>The sense of this property is a bit awkward, but it avoids making it
374 an anti-capability. If the sense were inverted, then its presence in
375 RequestableChannelClasses would imply that the protocol <em>lacks</em>
376 a feature; as it stands, it is additive. (Contrast with
378 namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"
379 >ImmutableStreams</tp:dbus-ref>, which is the wrong way around for
380 backwards-compatibility reasons.)</p>
383 <p>If false, <tp:member-ref>InitialChannels</tp:member-ref> SHOULD be
384 supplied in all requests for this channel class, and contain at least
385 two channels. Requests where this requirement is not met SHOULD fail
390 <p>In GSM, you can only make a conference call by merging at least
392 <strong>[FIXME: the CM could conceivably fake it, but that would be
393 rather nasty]</strong>