02110-1301, USA.</p>
</tp:license>
<interface
- name="org.freedesktop.Telepathy.Channel.Interface.Conference.DRAFT"
+ name="org.freedesktop.Telepathy.Channel.Interface.Conference.DRAFT2"
tp:causes-havoc="experimental">
<tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:changed version="0.19.UNRELEASED">(second, backwards-incompatible
+ draft)</tp:changed>
<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>
+ from" one or more individual channels. This could be used to invite
+ other contacts to an existing 1-1 text conversation, combine two phone
+ calls into one conference call, and so on, with roughly the same API in
+ each case.</p>
<tp:rationale>
<p>This interface addresses freedesktop.org <a
#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>
+ See those bugs for more rationale and use cases.</p>
</tp:rationale>
+ <p>Existing channels are upgraded by requesting a new channel of the same
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>,
+ listing the channels to be merged into the new conference in the
+ <tp:member-ref>InitialChannels</tp:member-ref> property of the request.
+ If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>,
+ ad-hoc conferences to a set of contacts may be created by requesting a
+ channel, specifying
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in
+ question. A request may specify these alongside
+ <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously
+ upgrade a channel to a conference and invite others to join it.</p>
+
+ <p>Channels with this interface MAY also implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref>
+ to support merging more 1-1 channels into an ongoing conference.
+ Similarly, 1-1 channels MAY implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to
+ support being broken out of a Conference channel.</p>
+
<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>
+ >Group</tp:dbus-ref> interface on Conference channels MAY use
+ 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>
+ channel-specific handles, to represent the fact that the same
+ phone number may be in a conference twice (for instance, it could be
+ the number of a corporate switchboard).</p>
<p>In the XMPP case, the Conference's Group interface SHOULD have
channel-specific handles, to reflect the fact that the participants
be misleading.</p>
</tp:rationale>
+ <h4>Examples of usage</h4>
+
+ <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged
+ into a single conference call by calling:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]
+ })</code>
+ </blockquote>
+
+ <p>which returns a new channel <var>Cn</var> implementing the conference
+ interface. (As a quirk of GSM, both 1-1 will cease to function normally
+ until they are <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref>
+ from the conference, or the conference ends.)</p>
+
+ <p>An XMPP 1-1 conversation <var>C3</var> (with
+ <tt>chris@example.com</tt>, say) can be continued in a newly created
+ multi-user chatroom by calling:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC
+ at the same time:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3],
+ ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net']
+ })</code>
+ </blockquote>
+
+ <p>To continue <var>C3</var> in a particular multi-user
+ chatroom (rather than the implementation inventing a unique name for
+ the room), call:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
+ ...ChannelType: ...Text,
+ ...<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>: 'telepathy@conf.example.com',
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Note the use of EnsureChannel — if a channel for
+ <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be
+ equivalent to inviting <tt>chris@example.com</tt> to the existing
+ channel.</p>
+
+ <p>In the above cases, the text channel <var>C3</var> SHOULD remain open
+ and fully functional (until explicitly closed by a client); new
+ incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in
+ <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed
+ only to <tt>chris@example.com</tt>.</p>
+
+ <tp:rationale>
+ <p>If there is an open 1-1 text channel with a contact, in every
+ other situation new messages will appear in that channel. Given
+ that the old channel remains open — which is the least surprising
+ behaviour, and eases us towards a beautiful world where channels
+ never close themselves — it stands to reason that it should be
+ where new messages from Chris should appear. On MSN, creating a
+ conference from <var>C3</var> should migrate the underlying
+ switchboard from <var>C3</var> to the new channel; this is an
+ implementation detail, and should not affect the representation on
+ D-Bus. With a suitable change of terminology, Skype has the same
+ behaviour.</p>
+
+ <p>If the current handler of that channel doesn't want this to happen
+ (maybe it transformed the existing tab into the group chat window,
+ and so there'd be no UI element still around to show new messages),
+ then it should just <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the
+ old 1-1 channel; it'll respawn if necessary.</p>
+ </tp:rationale>
+
+ <p>Either of the XMPP cases could work for Call channels, to
+ upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases
+ could in principle work for link-local XMPP (XEP-0174).</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>
+
+ <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref></h4>
+
+ <p>A GSM connection might advertise the following channel class for
+ conference calls:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/>
+ },<br/>
+ Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia'
+ >InitialAudio</tp:dbus-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>This indicates support for starting audio-only conference calls by
+ merging two or more existing channels (since
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p>
+
+ <p>An XMPP connection might advertise the following classes for ad-hoc
+ multi-user text chats:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/>
+ },<br/>
+ Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+),<br/>
+( Fixed = {<br/>
+ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/>
+ ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>:
+ Room<br/>
+ },<br/>
+ Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/>
+ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>The first class indicates support for starting ad-hoc (nameless) chat
+ rooms, upgraded from existing 1-1 channels and/or inviting new
+ contacts, along with a message to be sent along with the invitations.
+ The second indicates support for upgrading to a particular named chat
+ room.</p>
</tp:docstring>
<property name="Channels" tp:name-for-bindings="Channels"
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>This property MUST NOT be requestable; instead, the
+ <tp:member-ref>InitialChannels</tp:member-ref> property may be
+ specified when requesting a channel.</p>
+
+ <tp:rationale>
+ <p>This is consistent with requesting
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than
+ requesting <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref>
+ and some hypothetical ID version of that property.</p>
+ </tp:rationale>
<p>Change notification is via the
<tp:member-ref>ChannelMerged</tp:member-ref> and
<tp:docstring>The channel that was added to
<tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
</arg>
+
+ <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A new channel-specific handle for the <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of
+ <var>Channel</var>, as will appear in
+ <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a
+ global handle is used for
+ <var>Channel</var>'s TargetHandle on the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface
+ of this channel.</tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring>
+ </arg>
</signal>
<signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
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>
+ <p>If a channel is removed because it was closed, <tp:dbus-ref
+ namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted
+ before this signal.</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>
+
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Additional information about the removal, which may include
+ the same well-known keys as the Details argument of
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Group"
+ >MembersChangedDetailed</tp:dbus-ref>, with the same semantics.
+ </tp:docstring>
+ </arg>
</signal>
<property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
<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>
+ where its value has at least two channel paths SHOULD be expected to
+ succeed on any implementation of this interface. If
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref>, then requests with zero
+ or one channel paths SHOULD also succeed; otherwise, clients SHOULD
+ NOT make requests with zero or one paths for this property.</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>
+ <p>In GSM, a pair of calls can be merged into a conference, but you
+ can't start a conference call from zero or one existing calls. 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
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>
+ >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p>
<tp:rationale>
<p>In Jingle, nothing special will happen to merged calls. UIs MAY
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"
<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
+ <p>If it is possible to invite new contacts when creating a conference
+ (as opposed to merging several channels into one new conference
+ channel), 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>
+ >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property
+ SHOULD NOT be requestable, and its value SHOULD always be the empty
+ list.</p>
+
+ <tp:rationale>
+ <p>On GSM you have to place a 1-1 call before you can merge it into a
+ conference; on the other hand, you can invite new contacts to XMPP
+ Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a
+ 1-1 channel with them first.</p>
+ </tp:rationale>
<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
+ <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after
the channel was created.</p>
<tp:rationale>
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
(if that information is known).</p>
<p>This property is immutable.</p>
+
+ <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be
+ combined in a single request.</p>
+
+ <tp:rationale>
+ <p>For example, if you have a 1-1 channel C1 with Rob, and you want
+ to invite Sjoerd to join the discussion, you can do so by
+ requesting a channel with InitialChannels=[C1] and
+ InitialInviteeHandles=[sjoerd],
+ or InitialChannels=[C1] and
+ InitialInviteeIDs=["sjoerd@example.com"].</p>
+ </tp:rationale>
+
+ <p>If a request includes some combination of InitialInviteeHandles,
+ InitialInviteeIDs and InitialChannels, then the value of
+ InitialInviteeHandles on the resulting channel SHOULD be the union of
+ the handles from InitialInviteeHandles, the handles corresponding
+ to the InitialInviteeIDs, and the target handles of the
+ InitialChannels, with any duplicate handles removed. Because this
+ property is immutable, its value SHOULD be computed before the
+ channel is announced via the NewChannels signal.</p>
+
+ <tp:rationale>
+ <p>This simplifies identification of new channels in clients - they
+ only have to look at one of the properties, not both. For example,
+ after either of the requests mentioned above, the NewChannels
+ signal would announce the channel with InitialChannels=[C1],
+ InitialInviteeHandles=[rob, sjoerd], and
+ InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
+ </tp:rationale>
</tp:docstring>
</property>
<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>This property SHOULD be requestable if and only if
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable.
+ Its semantics are the same, except that it takes a list of the
+ string representations of contact handles; invitations are sent to
+ any contact present in either or both of these properties.</p>
<p>When a channel is created, the values of InitialInviteeHandles and
- InitialInviteeIDs MUST correspond to each other.</p>
+ InitialInviteeIDs MUST correspond to each other. In particular, this
+ means that the value of InitialInviteeIDs will include the TargetID
+ of each channel in InitialChannels, and the ID corresponding to each
+ handle in InitialInviteeHandles.</p>
<p>This property is immutable.</p>
</tp:docstring>
</tp:docstring>
</property>
- <property name="SupportsNonMerges"
- tp:name-for-bindings="Supports_Non_Merges"
- access="read" type="b">
+ <property name="OriginalChannels" tp:name-for-bindings="Original_Channels"
+ type="a{uo}" tp:type="Channel_Originator_Map"
+ access="read">
<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>On GSM conference calls, it is possible to have the same phone
+ number in a conference twice; for instance, it could be the number of
+ a corporate switchboard. This is represented using channel-specific
+ handles; whether or not a channel uses channel-specific handles is
+ reported in <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>.
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref>
+ property specifies the mapping from opaque channel-specific handles
+ to actual numbers; this property specifies the original 1-1 channel
+ corresponding to each channel-specific handle in the conference.</p>
+
+ <p>For example, consider this situation:</p>
+
+ <ol>
+ <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact
+ <tt>+441234567890</tt> (which is assigned the handle <var>h</var>,
+ say), and ask to be put through to Simon McVittie;</li>
+ <li>Put that call on hold;</li>
+ <li>Place another call (with path <tt>/call/to/jonny</tt>) to
+ <tt>+441234567890</tt>, and ask to be put
+ through to Jonny Lamb;</li>
+ <li>Request a new channel with
+ <tp:member-ref>InitialChannels</tp:member-ref>:
+ <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li>
+ </ol>
+
+ <p>The new channel will have the following properties, for some handles
+ <var>s</var> and <var>j</var>:</p>
+
+ <blockquote>
+ <code>{<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>:
+ Channel_Specific_Handles | (other flags),<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>:
+ [self_handle, s, j],<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>:
+ { s: h, j: h },<br/>
+ ...<tp:member-ref>InitialChannels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>Channels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>OriginalChannels</tp:member-ref>:
+ { s: '/call/to/simon', j: '/call/to/jonny' },<br/>
+ # ...standard properties like ChannelType: Group elided...<br/>
+ }</code>
+ </blockquote>
- <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>
+ <p>Change notification is via the
+ <tp:member-ref>ChannelMerged</tp:member-ref> and
+ <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if
+ <var>Channel_Specific_Handle</var> in the former is non-zero, this
+ property SHOULD be updated to map that handle to the merged channel's
+ path.</p>
</tp:docstring>
</property>
+ <tp:mapping name="Channel_Originator_Map">
+ <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A channel-specific handle for a participant in this conference.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Original_Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The object path of <tp:member-ref>Channels</tp:member-ref>
+ representing the original 1-1 channel with
+ <var>Channel_Specific_Handle</var>.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A mapping from members of a conference to the original 1-1 channel with
+ that contact, if any. See
+ <tp:member-ref>OriginalChannels</tp:member-ref> for details.
+ </tp:docstring>
+ </tp:mapping>
</interface>
</node>
projects / empathy.git / commitdiff