extensions/Channel_Interface_Conference.xml

   1 <?xml version="1.0" ?>
   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>
  11
  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>
  16
  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
  20       02110-1301, USA.</p>
  21   </tp:license>
  22   <interface
  23     name="org.freedesktop.Telepathy.Channel.Interface.Conference">
  24     <tp:added version="0.19.13">(as stable API)</tp:added>
  25     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
  26     <tp:requires
  27       interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
  28
  29     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  30       <p>An interface for multi-user conference channels that can "continue
  31         from" one or more individual channels. This could be used to invite
  32         other contacts to an existing 1-1 text conversation, combine two phone
  33         calls into one conference call, and so on, with roughly the same API in
  34         each case.</p>
  35
  36       <tp:rationale>
  37         <p>This interface addresses freedesktop.org <a
  38             href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
  39             #24906</a> (GSM-compatible conference calls) and <a
  40             href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug
  41             #24939</a> (upgrading calls and chats to multi-user).
  42           See those bugs for more rationale and use cases.</p>
  43       </tp:rationale>
  44
  45       <p>Existing channels are upgraded by requesting a new channel of the same
  46         <tp:dbus-ref
  47         namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>,
  48         listing the channels to be merged into the new conference in the
  49         <tp:member-ref>InitialChannels</tp:member-ref> property of the request.
  50         If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
  51         <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
  52         <var>Allowed_Properties</var> in <tp:dbus-ref
  53           namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>,
  54         ad-hoc conferences to a set of contacts may be created by requesting a
  55         channel, specifying
  56         <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or
  57         <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in
  58         question. A request may specify these alongside
  59         <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously
  60         upgrade a channel to a conference and invite others to join it.</p>
  61
  62       <p>Channels with this interface MAY also implement <tp:dbus-ref
  63         namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref>
  64         to support merging more 1-1 channels into an ongoing conference.
  65         Similarly, 1-1 channels MAY implement <tp:dbus-ref
  66         namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to
  67         support being broken out of a Conference channel.</p>
  68
  69       <p>The <tp:dbus-ref
  70           namespace="org.freedesktop.Telepathy.Channel.Interface"
  71           >Group</tp:dbus-ref> interface on Conference channels MAY use
  72           channel-specific handles for participants; clients SHOULD support
  73           both Conferences that have channel-specific handles, and those that
  74           do not.</p>
  75
  76       <tp:rationale>
  77         <p>In the GSM case, the Conference's Group interface MAY have
  78           channel-specific handles, to represent the fact that the same
  79           phone number may be in a conference twice (for instance, it could be
  80           the number of a corporate switchboard).</p>
  81
  82         <p>In the XMPP case, the Conference's Group interface SHOULD have
  83           channel-specific handles, to reflect the fact that the participants
  84           have MUC-specific identities, and the user might also be able to see
  85           their global identities, or not.</p>
  86
  87         <p>In most other cases, including MSN and link-local XMPP, the
  88           Conference's Group interface SHOULD NOT have channel-specific
  89           handles, since users' identities are always visible.</p>
  90       </tp:rationale>
  91
  92       <p>Connection managers implementing channels with this interface
  93         MUST NOT allow the object paths of channels that could be merged
  94         into a Conference to be re-used, unless the channel re-using the
  95         object path is equivalent to the channel that previously used it.</p>
  96
  97       <tp:rationale>
  98         <p>If you upgrade some channels into a conference, and then close
  99           the original channels, <tp:member-ref>InitialChannels</tp:member-ref>
 100           (which is immutable) will contain paths to channels which no longer
 101           exist. This implies that you should not re-use channel object paths,
 102           unless future incarnations of the path are equivalent.</p>
 103
 104         <p>For instance, on protocols where you can only have
 105           zero or one 1-1 text channels with Emily at one time, it would
 106           be OK to re-use the same object path for every 1-1 text channel
 107           with Emily; but on protocols where this is not true, it would
 108           be misleading.</p>
 109       </tp:rationale>
 110
 111       <h4>Examples of usage</h4>
 112
 113       <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged
 114         into a single conference call by calling:</p>
 115
 116       <blockquote>
 117         <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
 118             ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call,
 119             ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]
 120           })</code>
 121       </blockquote>
 122
 123       <p>which returns a new channel <var>Cn</var> implementing the conference
 124         interface. (As a quirk of GSM, both 1-1 will cease to function normally
 125         until they are <tp:dbus-ref
 126           namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref>
 127         from the conference, or the conference ends.)</p>
 128
 129       <p>An XMPP 1-1 conversation <var>C3</var> (with
 130         <tt>chris@example.com</tt>, say) can be continued in a newly created
 131         multi-user chatroom by calling:</p>
 132
 133       <blockquote>
 134         <code>CreateChannel({
 135             ...ChannelType: ...Text,
 136             ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
 137           })</code>
 138       </blockquote>
 139
 140       <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC
 141         at the same time:</p>
 142
 143       <blockquote>
 144         <code>CreateChannel({
 145             ...ChannelType: ...Text,
 146             ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3],
 147             ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net']
 148           })</code>
 149       </blockquote>
 150
 151       <p>To continue <var>C3</var> in a particular multi-user
 152         chatroom (rather than the implementation inventing a unique name for
 153         the room), call:</p>
 154
 155       <blockquote>
 156         <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
 157             ...ChannelType: ...Text,
 158             ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: ...Room,
 159             ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com',
 160             ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
 161           })</code>
 162       </blockquote>
 163
 164       <p>Note the use of EnsureChannel — if a channel for
 165         <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be
 166         equivalent to inviting <tt>chris@example.com</tt> to the existing
 167         channel.</p>
 168
 169       <p>In the above cases, the text channel <var>C3</var> SHOULD remain open
 170         and fully functional (until explicitly closed by a client); new
 171         incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in
 172         <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed
 173         only to <tt>chris@example.com</tt>.</p>
 174
 175       <tp:rationale>
 176         <p>If there is an open 1-1 text channel with a contact, in every
 177           other situation new messages will appear in that channel. Given
 178           that the old channel remains open — which is the least surprising
 179           behaviour, and eases us towards a beautiful world where channels
 180           never close themselves — it stands to reason that it should be
 181           where new messages from Chris should appear. On MSN, creating a
 182           conference from <var>C3</var> should migrate the underlying
 183           switchboard from <var>C3</var> to the new channel; this is an
 184           implementation detail, and should not affect the representation on
 185           D-Bus. With a suitable change of terminology, Skype has the same
 186           behaviour.</p>
 187
 188         <p>If the current handler of that channel doesn't want this to happen
 189           (maybe it transformed the existing tab into the group chat window,
 190           and so there'd be no UI element still around to show new messages),
 191           then it should just <tp:dbus-ref
 192           namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the
 193           old 1-1 channel; it'll respawn if necessary.</p>
 194       </tp:rationale>
 195
 196       <p>Either of the XMPP cases could work for Call channels, to
 197         upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases
 198         could in principle work for link-local XMPP (XEP-0174).</p>
 199
 200       <p>XMPP and MSN do not natively have a concept of merging two or more
 201         channels C1, C2... into one channel, Cn. However, the GSM-style
 202         merging API can be supported on XMPP and MSN, as an API short-cut
 203         for upgrading C1 into a conference Cn (which invites the
 204         TargetHandle of C1 into Cn), then immediately inviting the
 205         TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p>
 206
 207       <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
 208                              >RequestableChannelClasses</tp:dbus-ref></h4>
 209
 210       <p>A GSM connection might advertise the following channel class for
 211         conference calls:</p>
 212
 213       <blockquote>
 214         <code>
 215 ( Fixed = {<br/>
 216     ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
 217       ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/>
 218   },<br/>
 219   Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
 220               <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia'
 221                           >InitialAudio</tp:dbus-ref>
 222             ]<br/>
 223 )
 224         </code>
 225       </blockquote>
 226
 227       <p>This indicates support for starting audio-only conference calls by
 228         merging two or more existing channels (since
 229         <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
 230         <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p>
 231
 232       <p>An XMPP connection might advertise the following classes for ad-hoc
 233         multi-user text chats:</p>
 234
 235       <blockquote>
 236         <code>
 237 ( Fixed = {<br/>
 238     ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
 239       ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/>
 240   },<br/>
 241   Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
 242               <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
 243               <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
 244               <tp:member-ref>InvitationMessage</tp:member-ref>
 245             ]<br/>
 246 ),<br/>
 247 ( Fixed = {<br/>
 248     ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
 249       ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/>
 250     ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>:
 251       Room<br/>
 252   },<br/>
 253   Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>,
 254               <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/>
 255               <tp:member-ref>InitialChannels</tp:member-ref>,
 256               <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
 257               <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
 258               <tp:member-ref>InvitationMessage</tp:member-ref>
 259             ]<br/>
 260 )
 261         </code>
 262       </blockquote>
 263
 264       <p>The first class indicates support for starting ad-hoc (nameless) chat
 265         rooms, upgraded from existing 1-1 channels and/or inviting new
 266         contacts, along with a message to be sent along with the invitations.
 267         The second indicates support for upgrading to a particular named chat
 268         room.</p>
 269     </tp:docstring>
 270
 271     <property name="Channels" tp:name-for-bindings="Channels"
 272       access="read" type="ao">
 273       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 274         <p>The individual <tp:dbus-ref
 275             namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that
 276           are continued by this conference, which have the same <tp:dbus-ref
 277               namespace="org.freedesktop.Telepathy.Channel"
 278               >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
 279               namespace="org.freedesktop.Telepathy.Channel"
 280               >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
 281
 282         <p>This property MUST NOT be requestable; instead, the
 283           <tp:member-ref>InitialChannels</tp:member-ref> property may be
 284           specified when requesting a channel.</p>
 285
 286         <tp:rationale>
 287           <p>This is consistent with requesting
 288             <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
 289             <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than
 290             requesting <tp:dbus-ref
 291             namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref>
 292             and some hypothetical ID version of that property.</p>
 293        </tp:rationale>
 294
 295         <p>Change notification is via the
 296           <tp:member-ref>ChannelMerged</tp:member-ref> and
 297           <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p>
 298       </tp:docstring>
 299     </property>
 300
 301     <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged">
 302       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 303         <p>Emitted when a new channel is added to the value of
 304           <tp:member-ref>Channels</tp:member-ref>.</p>
 305       </tp:docstring>
 306
 307       <arg name="Channel" type="o">
 308         <tp:docstring>The channel that was added to
 309           <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
 310       </arg>
 311
 312       <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
 313         <tp:docstring>A new channel-specific handle for the <tp:dbus-ref
 314           namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of
 315           <var>Channel</var>, as will appear in
 316           <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a
 317           global handle is used for
 318           <var>Channel</var>'s TargetHandle on the <tp:dbus-ref
 319             namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface
 320           of this channel.</tp:docstring>
 321       </arg>
 322
 323       <arg name="Properties" type="a{sv}"
 324            tp:type="Qualified_Property_Value_Map">
 325         <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring>
 326       </arg>
 327     </signal>
 328
 329     <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
 330       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 331         <p>Emitted when a channel is removed from the value of
 332           <tp:member-ref>Channels</tp:member-ref>, either because it closed
 333           or because it was split using the <tp:dbus-ref
 334             namespace="org.freedesktop.Telepathy.Channel.Interface"
 335             >Splittable.DRAFT.Split</tp:dbus-ref> method.</p>
 336
 337         <p>If a channel is removed because it was closed, <tp:dbus-ref
 338           namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted
 339           before this signal.</p>
 340       </tp:docstring>
 341
 342       <arg name="Channel" type="o">
 343         <tp:docstring>The channel that was removed from
 344           <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
 345       </arg>
 346
 347       <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
 348         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 349           Additional information about the removal, which may include
 350           the same well-known keys as the Details argument of
 351           <tp:dbus-ref namespace="ofdT.Channel.Interface.Group"
 352             >MembersChangedDetailed</tp:dbus-ref>, with the same semantics.
 353         </tp:docstring>
 354       </arg>
 355     </signal>
 356
 357     <property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
 358       access="read" type="ao">
 359       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 360         <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p>
 361
 362         <p>This property SHOULD be requestable. Omitting it from a request is
 363           equivalent to providing it with an empty list as value. Requests
 364           where its value has at least two channel paths SHOULD be expected to
 365           succeed on any implementation of this interface. If
 366           <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
 367           <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
 368           <var>Allowed_Properties</var> in <tp:dbus-ref
 369             namespace='ofdT.Connection.Interface.Requests'
 370             >RequestableChannelClasses</tp:dbus-ref>, then requests with zero
 371           or one channel paths SHOULD also succeed; otherwise, clients SHOULD
 372           NOT make requests with zero or one paths for this property.</p>
 373
 374         <tp:rationale>
 375           <p>In GSM, a pair of calls can be merged into a conference, but you
 376             can't start a conference call from zero or one existing calls. In
 377             XMPP and MSN, you can create a new chatroom, or upgrade one 1-1
 378             channel into a chatroom; however, on these protocols, it is also
 379             possible to fake GSM-style merging by upgrading the first channel,
 380             then inviting the targets of all the other channels into it.</p>
 381         </tp:rationale>
 382
 383         <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD
 384           NOT be altered by merging them into a conference. However, depending on
 385           the protocol, the Channels MAY be placed in a "frozen" state by placing
 386           them in this property's value or by calling
 387           <tp:dbus-ref
 388             namespace="org.freedesktop.Telepathy.Channel.Interface"
 389             >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p>
 390
 391         <tp:rationale>
 392           <p>In Jingle, nothing special will happen to merged calls. UIs MAY
 393             automatically place calls on hold before merging them, if that is
 394             the desired behaviour; this SHOULD always work. Not doing
 395             an implicit hold/unhold seems to preserve least-astonishment.</p>
 396
 397           <p>In GSM, the calls that are merged go into a state similar to
 398             Hold, but they cannot be unheld, only split from the conference
 399             call using <tp:dbus-ref namespace="org.freedesktop.Telepathy"
 400               >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p>
 401         </tp:rationale>
 402
 403         <p>Depending on the protocol, it might be signalled to remote users
 404           that this channel is a continuation of all the requested channels,
 405           or that it is only a continuation of the first channel in the
 406           list.</p>
 407
 408         <tp:rationale>
 409           <p>In MSN, the conference steals the underlying switchboard (protocol
 410             construct) from one of its component channels, so the conference
 411             appears to remote users to be a continuation of that channel and no
 412             other. The connection manager has to make some arbitrary choice, so
 413             we arbitrarily mandate that it SHOULD choose the first channel in
 414             the list as the one to continue.</p>
 415         </tp:rationale>
 416
 417         <p>This property is immutable.</p>
 418       </tp:docstring>
 419     </property>
 420
 421     <property name="InitialInviteeHandles"
 422       tp:name-for-bindings="Initial_Invitee_Handles"
 423       access="read" type="au" tp:type="Contact_Handle[]">
 424       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 425         <p>A list of additional contacts invited to this conference when it
 426           was created.</p>
 427
 428         <p>If it is possible to invite new contacts when creating a conference
 429           (as opposed to merging several channels into one new conference
 430           channel), this property SHOULD be requestable, and appear in the allowed
 431           properties in <tp:dbus-ref
 432             namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
 433             >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property
 434           SHOULD NOT be requestable, and its value SHOULD always be the empty
 435           list.</p>
 436
 437         <tp:rationale>
 438           <p>On GSM you have to place a 1-1 call before you can merge it into a
 439             conference; on the other hand, you can invite new contacts to XMPP
 440             Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a
 441             1-1 channel with them first.</p>
 442         </tp:rationale>
 443
 444         <p>If included in a request, the given contacts are automatically
 445           invited into the new channel, as if they had been added with
 446           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
 447             >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
 448           <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after
 449           the channel was created.</p>
 450
 451         <tp:rationale>
 452           <p>This is a simple convenience API for the common case that a UI
 453             upgrades a 1-1 chat to a multi-user chat solely in order to invite
 454             someone else to participate.</p>
 455         </tp:rationale>
 456
 457         <p>If the local user was not the initiator of this channel, the
 458           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
 459             >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
 460           property, together with any other contacts invited at the same time
 461           (if that information is known).</p>
 462
 463         <p>This property is immutable.</p>
 464
 465         <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be
 466           combined in a single request.</p>
 467
 468         <tp:rationale>
 469           <p>For example, if you have a 1-1 channel C1 with Rob, and you want
 470             to invite Sjoerd to join the discussion, you can do so by
 471             requesting a channel with InitialChannels=[C1] and
 472             InitialInviteeHandles=[sjoerd],
 473             or InitialChannels=[C1] and
 474             InitialInviteeIDs=["sjoerd@example.com"].</p>
 475         </tp:rationale>
 476
 477         <p>If a request includes some combination of InitialInviteeHandles,
 478           InitialInviteeIDs and InitialChannels, then the value of
 479           InitialInviteeHandles on the resulting channel SHOULD be the union of
 480           the handles from InitialInviteeHandles, the handles corresponding
 481           to the InitialInviteeIDs, and the target handles of the
 482           InitialChannels, with any duplicate handles removed. Because this
 483           property is immutable, its value SHOULD be computed before the
 484           channel is announced via the NewChannels signal.</p>
 485
 486         <tp:rationale>
 487           <p>This simplifies identification of new channels in clients - they
 488             only have to look at one of the properties, not both. For example,
 489             after either of the requests mentioned above, the NewChannels
 490             signal would announce the channel with InitialChannels=[C1],
 491             InitialInviteeHandles=[rob, sjoerd], and
 492             InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
 493         </tp:rationale>
 494       </tp:docstring>
 495     </property>
 496
 497     <property name="InitialInviteeIDs"
 498       tp:name-for-bindings="Initial_Invitee_IDs"
 499       access="read" type="as">
 500       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 501         <p>A list of additional contacts invited to this conference when it
 502           was created.</p>
 503
 504         <p>This property SHOULD be requestable if and only if
 505           <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable.
 506           Its semantics are the same, except that it takes a list of the
 507           string representations of contact handles; invitations are sent to
 508           any contact present in either or both of these properties.</p>
 509
 510         <p>When a channel is created, the values of InitialInviteeHandles and
 511           InitialInviteeIDs MUST correspond to each other. In particular, this
 512           means that the value of InitialInviteeIDs will include the TargetID
 513           of each channel in InitialChannels, and the ID corresponding to each
 514           handle in InitialInviteeHandles.</p>
 515
 516         <p>This property is immutable.</p>
 517       </tp:docstring>
 518     </property>
 519
 520     <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message"
 521       access="read" type="s">
 522       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 523         <p>The message that was sent to the
 524           <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were
 525           invited.</p>
 526
 527         <p>This property SHOULD be requestable, and appear in the allowed
 528           properties in <tp:dbus-ref
 529             namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
 530             >RequestableChannelClasses</tp:dbus-ref>, in protocols where
 531           invitations can have an accompanying text message.</p>
 532
 533         <tp:rationale>
 534           <p>This allows invitations with a message to be sent when using
 535             <tp:member-ref>InitialInviteeHandles</tp:member-ref> or
 536             <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p>
 537         </tp:rationale>
 538
 539         <p>If the local user was not the initiator of this channel, the
 540           message with which they were invited (if any) SHOULD appear in the
 541           value of this property.</p>
 542
 543         <p>This property is immutable.</p>
 544       </tp:docstring>
 545     </property>
 546
 547     <property name="OriginalChannels" tp:name-for-bindings="Original_Channels"
 548               type="a{uo}" tp:type="Channel_Originator_Map"
 549               access="read">
 550       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 551         <p>On GSM conference calls, it is possible to have the same phone
 552           number in a conference twice; for instance, it could be the number of
 553           a corporate switchboard. This is represented using channel-specific
 554           handles; whether or not a channel uses channel-specific handles is
 555           reported in <tp:dbus-ref
 556           namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>.
 557           The <tp:dbus-ref
 558             namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref>
 559           property specifies the mapping from opaque channel-specific handles
 560           to actual numbers; this property specifies the original 1-1 channel
 561           corresponding to each channel-specific handle in the conference.</p>
 562
 563         <p>In protocols where this situation cannot arise, such as XMPP,
 564           this property MAY remain empty.</p>
 565
 566         <p>For example, consider this situation:</p>
 567
 568         <ol>
 569           <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact
 570             <tt>+441234567890</tt> (which is assigned the handle <var>h</var>,
 571             say), and ask to be put through to Simon McVittie;</li>
 572           <li>Put that call on hold;</li>
 573           <li>Place another call (with path <tt>/call/to/jonny</tt>) to
 574             <tt>+441234567890</tt>, and ask to be put
 575             through to Jonny Lamb;</li>
 576           <li>Request a new channel with
 577             <tp:member-ref>InitialChannels</tp:member-ref>:
 578             <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li>
 579         </ol>
 580
 581         <p>The new channel will have the following properties, for some handles
 582           <var>s</var> and <var>j</var>:</p>
 583
 584         <blockquote>
 585           <code>{<br/>
 586             ...<tp:dbus-ref
 587               namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>:
 588                 Channel_Specific_Handles | (other flags),<br/>
 589             ...<tp:dbus-ref
 590               namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>:
 591                 [self_handle, s, j],<br/>
 592             ...<tp:dbus-ref
 593               namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>:
 594                 { s: h, j: h },<br/>
 595             ...<tp:member-ref>InitialChannels</tp:member-ref>:
 596                 ['/call/to/simon', '/call/to/jonny'],<br/>
 597             ...<tp:member-ref>Channels</tp:member-ref>:
 598                 ['/call/to/simon', '/call/to/jonny'],<br/>
 599             ...<tp:member-ref>OriginalChannels</tp:member-ref>:
 600                 { s: '/call/to/simon', j: '/call/to/jonny' },<br/>
 601             # ...standard properties like ChannelType: Group elided...<br/>
 602           }</code>
 603         </blockquote>
 604
 605         <p>Change notification is via the
 606           <tp:member-ref>ChannelMerged</tp:member-ref> and
 607           <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if
 608           <var>Channel_Specific_Handle</var> in the former is non-zero, this
 609           property SHOULD be updated to map that handle to the merged channel's
 610           path.</p>
 611       </tp:docstring>
 612     </property>
 613
 614     <tp:mapping name="Channel_Originator_Map">
 615       <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
 616         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 617           A channel-specific handle for a participant in this conference.
 618         </tp:docstring>
 619       </tp:member>
 620       <tp:member name="Original_Channel" type="o">
 621         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 622           The object path of <tp:member-ref>Channels</tp:member-ref>
 623           representing the original 1-1 channel with
 624           <var>Channel_Specific_Handle</var>.
 625         </tp:docstring>
 626       </tp:member>
 627
 628       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 629         A mapping from members of a conference to the original 1-1 channel with
 630         that contact, if any. See
 631         <tp:member-ref>OriginalChannels</tp:member-ref> for details.
 632       </tp:docstring>
 633     </tp:mapping>
 634   </interface>
 635 </node>