path: root/spec/Channel_Interface_Conference.xml

<?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="im.telepathy1.Channel.Interface.Conference1">
    <tp:added version="0.19.13">(as stable API)</tp:added>
    <tp:requires interface="im.telepathy1.Channel"/>
    <tp:requires
      interface="im.telepathy1.Channel.Interface.Group1"/>

    <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="im.telepathy1.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="im.telepathy1.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='imt1.Channel.Interface'>MergeableConference1</tp:dbus-ref>
        to support merging more 1-1 channels into an ongoing conference.
        Similarly, 1-1 channels MAY implement <tp:dbus-ref
        namespace='imt1.Channel.Interface'>Splittable1</tp:dbus-ref> to
        support being broken out of a Conference channel.</p>

      <p>The <tp:dbus-ref
          namespace="im.telepathy1.Channel.Interface"
          >Group1</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="im.telepathy1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
            ...<tp:dbus-ref namespace="im.telepathy1.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="imt1.Channel.Interface.Splittable1">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="im.telepathy1.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
            ...ChannelType: ...Text,
            ...<tp:dbus-ref namespace="im.telepathy1.Channel">TargetHandleType</tp:dbus-ref>: ...Room,
            ...<tp:dbus-ref namespace="im.telepathy1.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="im.telepathy1.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='imt1.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='imt1.Channel'>ChannelType</tp:dbus-ref>:
      ...<tp:dbus-ref namespace='imt1.Channel.Type'>Call1</tp:dbus-ref><br/>
  },<br/>
  Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
              <tp:dbus-ref namespace='imt1.Channel.Type.Call1'
                          >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='imt1.Channel'>ChannelType</tp:dbus-ref>:
      ...<tp:dbus-ref namespace='imt1.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='imt1.Channel'>ChannelType</tp:dbus-ref>:
      ...<tp:dbus-ref namespace='imt1.Channel.Type'>Text</tp:dbus-ref>,<br/>
    ...<tp:dbus-ref namespace='imt1.Channel'>TargetHandleType</tp:dbus-ref>:
      Room<br/>
  },<br/>
  Allowed = [ <tp:dbus-ref namespace='imt1.Channel'>TargetHandle</tp:dbus-ref>,
              <tp:dbus-ref namespace='imt1.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="im.telepathy1">Channel</tp:dbus-ref>s that
          are continued by this conference, which have the same <tp:dbus-ref
              namespace="im.telepathy1.Channel"
              >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
              namespace="im.telepathy1.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="im.telepathy1.Channel.Interface">Group1.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="imt1.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="imt1.Channel.Interface">Group1</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="im.telepathy1.Channel.Interface"
            >Splittable1.Split</tp:dbus-ref> method.</p>

        <p>If a channel is removed because it was closed, <tp:dbus-ref
          namespace='imt1.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="imt1.Channel.Interface.Group1"
            >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='imt1.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="im.telepathy1.Channel.Interface"
            >MergeableConference1.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="im.telepathy1"
              >Channel.Interface.Splittable1.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="im.telepathy1.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="im.telepathy1.Channel.Interface"
            >Group1.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="im.telepathy1.Channel.Interface"
            >Group1.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="im.telepathy1.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='imt1.Channel.Interface'>Group1.GroupFlags</tp:dbus-ref>.
          The <tp:dbus-ref
            namespace="im.telepathy1.Channel.Interface">Group1.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="imt1.Channel.Interface">Group1.GroupFlags</tp:dbus-ref>:
                Channel_Specific_Handles | (other flags),<br/>
            ...<tp:dbus-ref
              namespace="imt1.Channel.Interface">Group1.Members</tp:dbus-ref>:
                [self_handle, s, j],<br/>
            ...<tp:dbus-ref
              namespace="imt1.Channel.Interface">Group1.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>