diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_Conference.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_Conference.xml | 628 |
1 files changed, 0 insertions, 628 deletions
diff --git a/qt4/spec/Channel_Interface_Conference.xml b/qt4/spec/Channel_Interface_Conference.xml deleted file mode 100644 index abda59eef..000000000 --- a/qt4/spec/Channel_Interface_Conference.xml +++ /dev/null @@ -1,628 +0,0 @@ -<?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"> - <tp:added version="0.19.13">(as stable API)</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. 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 - 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 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> 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 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 - 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> - - <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" - 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; 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: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> - - <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"> - <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>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" - access="read" type="ao" tp:immutable="yes" tp:requestable="yes"> - <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 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, 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 - 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.</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>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> - </tp:docstring> - </property> - - <property name="InitialInviteeHandles" - tp:name-for-bindings="Initial_Invitee_Handles" - access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes" - tp:requestable="yes"> - <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>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>. 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 - 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>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>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> - - <property name="InitialInviteeIDs" - tp:name-for-bindings="Initial_Invitee_IDs" - access="read" type="as" tp:immutable="yes" tp:requestable="yes"> - <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 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. 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> - </tp:docstring> - </property> - - <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message" - access="read" type="s" tp:immutable="yes" tp:requestable="yes"> - <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> - </tp:docstring> - </property> - - <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>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>In protocols where this situation cannot arise, such as XMPP, - this property MAY remain empty.</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>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> |