path: root/spec/Channel.xml

<?xml version="1.0" ?>
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
  <tp:copyright>Copyright © 2006 INdT</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">

    <property name="ChannelType" type="s" tp:type="DBus_Interface"
      access="read" tp:name-for-bindings="Channel_Type">
      <tp:added version="0.17.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The channel's type. This cannot change once the channel has
          been created.</p>

        <p>For compatibility between older connection managers and newer
          clients, if this is unavailable or is an empty string,
          clients MUST use the result of calling
          <tp:member-ref>GetChannelType</tp:member-ref>.</p>

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip, which is desirable.
        </tp:rationale>

        <p>When requesting a channel, the request MUST specify a channel
          type, and the request MUST fail if the specified channel type
          cannot be supplied.</p>

        <tp:rationale>
          Common sense.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" tp:type="DBus_Interface[]" access="read">
      <tp:added version="0.17.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Extra interfaces provided by this channel. This SHOULD NOT include
          the channel type and the Channel interface itself, and cannot
          change once the channel has been created.</p>

        <p>For compatibility between older connection managers and newer
          clients, if this is unavailable, or if this is an empty list and
          <tp:member-ref>ChannelType</tp:member-ref> is an empty string,
          clients MUST use the result of calling
          <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an
          empty list but ChannelType is non-empty, clients SHOULD NOT call
          GetInterfaces; this implies that connection managers that implement
          the ChannelType property MUST also implement the Interfaces property
          correctly.</p>

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip, which is desirable.
        </tp:rationale>

        <p>When requesting a channel with a particular value for this
          property, the request must fail without side-effects unless the
          connection manager expects to be able to provide a channel whose
          interfaces include at least the interfaces requested.</p>
      </tp:docstring>
    </property>

    <property name="TargetHandle" type="u" access="read" tp:type="Handle"
      tp:name-for-bindings="Target_Handle">
      <tp:added version="0.17.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The handle (a representation for the identifier) of the contact,
          chatroom, etc. with which this handle communicates. Its type
          is given by the <tp:member-ref>TargetHandleType</tp:member-ref>
          property.</p>

        <p>This is fixed for the lifetime of the channel, so channels which
          could potentially be used to communicate with multiple contacts,
          and do not have an identity of their own (such as a Handle_Type_Room
          handle), must have TargetHandleType set to Handle_Type_None and
          TargetHandle set to 0.</p>

        <p>Unlike in the telepathy-spec 0.16 API, there is no particular
          uniqueness guarantee - there can be many channels with the same
          (channel type, handle type, handle) tuple. This is necessary
          to support conversation threads in XMPP and SIP, for example.</p>

        <p>If this is present in a channel request, it must be nonzero,
          <tp:member-ref>TargetHandleType</tp:member-ref>
          MUST be present and not Handle_Type_None, and
          <tp:member-ref>TargetID</tp:member-ref> MUST NOT be
          present. Properties from
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref>
          MUST NOT be present.</p>

        <p>The channel that satisfies the request MUST either:</p>

        <ul>
          <li>have the specified TargetHandle property; or</li>
          <li>have <tp:member-ref>TargetHandleType</tp:member-ref> =
            Handle_Type_None, TargetHandle = 0, and be configured such that
            it could communicate with the specified handle in some other way
            (e.g. have the requested contact handle in its Group
            interface)</li>
        </ul>
      </tp:docstring>
    </property>

    <property name="TargetID" tp:name-for-bindings="Target_ID"
      type="s" access="read">
      <tp:added version="0.17.9"/>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The string that would result from inspecting the
          <tp:member-ref>TargetHandle</tp:member-ref>
          property (i.e. the identifier in the IM protocol of the contact,
          room, etc. with which this channel communicates), or the empty
          string if the TargetHandle is 0.</p>

        <tp:rationale>
          <p>The presence of this property avoids the following race
            condition:</p>

          <ul>
            <li>New channel C is signalled with target handle T</li>
            <li>Client calls <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [T])</li>
            <li>Channel C closes, removing the last reference to handle T</li>
            <li><tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [T]) returns an error</li>
          </ul>
        </tp:rationale>

        <p>If this is present in a channel request,
          <tp:member-ref>TargetHandleType</tp:member-ref>
          MUST be present and not Handle_Type_None, and
          <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be
          present. Properties from
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref>
          MUST NOT be present.The request MUST fail with error InvalidHandle,
          without side-effects, if the requested TargetID would not be
          accepted by
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>

        <p>The returned channel must be related to the handle corresponding
          to the given identifier, in the same way as if TargetHandle
          had been part of the request instead.</p>

        <tp:rationale>
          <p>Requesting channels with a string identifier saves a round-trip
            (the call to RequestHandles). It also allows the channel
            dispatcher to accept a channel request for an account that is not
            yet connected (and thus has no valid handles), bring the account
            online, and pass on the same parameters to the new connection's
            CreateChannel method.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="TargetHandleType" type="u" access="read"
      tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type">
      <tp:added version="0.17.7"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p>

        <p>If this is omitted from a channel request, connection managers
          SHOULD treat this as equivalent to Handle_Type_None.</p>

        <p>If this is omitted or is Handle_Type_None,
          <tp:member-ref>TargetHandle</tp:member-ref> and
          <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the
          request.</p>
      </tp:docstring>
    </property>

    <method name="Close" tp:name-for-bindings="Close">
      <tp:docstring>
        Request that the channel be closed. This is not the case until
        the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and
        depending on the connection
        manager this may simply remove you from the channel on the server,
        rather than causing it to stop existing entirely. Some channels
        such as contact list channels may not be closed.
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            This channel may never be closed, e.g. a contact list
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            This channel is not currently in a state where it can be closed,
            e.g. a non-empty user-defined contact group
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="Closed" tp:name-for-bindings="Closed">
      <tp:docstring>
        Emitted when the channel has been closed. Method calls on the
        channel are no longer valid after this signal has been emitted,
        and the connection manager may then remove the object from the bus
        at any point.
      </tp:docstring>
    </signal>

    <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type">
      <tp:deprecated version="0.17.7">Use the ChannelType
        property if possible.</tp:deprecated>
      <arg direction="out" type="s" tp:type="DBus_Interface"
        name="Channel_Type">
        <tp:docstring>The interface name</tp:docstring>
      </arg>
      <tp:docstring>
        Returns the interface name for the type of this channel.  Clients
        SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property
        instead, falling back to this method only if necessary.

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
      </tp:docstring>
    </method>

    <method name="GetHandle" tp:name-for-bindings="Get_Handle">
      <tp:deprecated version="0.17.7">Use the TargetHandleType
        and TargetHandle properties if possible.</tp:deprecated>
      <arg direction="out" type="u" tp:type="Handle_Type"
        name="Target_Handle_Type">
        <tp:docstring>
          The same as TargetHandleType.
        </tp:docstring>
      </arg>
      <arg direction="out" type="u" tp:type="Handle" name="Target_Handle">
        <tp:docstring>
          The same as TargetHandle.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Returns the handle type and number if this channel represents a
        communication with a particular contact, room or server-stored list, or
        zero if it is transient and defined only by its contents. Clients
        SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and
        <tp:member-ref>TargetHandleType</tp:member-ref> properties instead,
        falling back to this method only if necessary.

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
      </tp:docstring>
    </method>

    <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
      <tp:deprecated version="0.17.7">Use the Interfaces
        property if possible.</tp:deprecated>
      <arg direction="out" type="as" tp:type="DBus_Interface[]"
        name="Interfaces">
        <tp:docstring>
          An array of the D-Bus interface names
        </tp:docstring>
      </arg>
      <tp:docstring>
        Get the optional interfaces implemented by the channel.
        Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref>
        property instead, falling back to this method only if necessary.

        <tp:rationale>
          The GetAll method lets clients retrieve all properties in one
          round-trip.
        </tp:rationale>
      </tp:docstring>
    </method>

    <property name="Requested" tp:name-for-bindings="Requested"
      type="b" access="read">
      <tp:added version="0.17.13">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>True if this channel was created in response to a local request,
          such as a call to
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
          or
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>

        <tp:rationale>
          <p>The idea of this property is to distinguish between "incoming"
            and "outgoing" channels, in a way that doesn't break down when
            considering special cases like contact lists that are automatically
            created on connection to the server, or chatrooms that an
            IRC proxy/bouncer like irssi-proxy or bip was already in.</p>

          <p>The reason we want to make that distinction is that UIs for
            things that the user explicitly requested should start up
            automatically, whereas for incoming messages and VoIP calls we
            should first ask the user whether they want to open the messaging
            UI or accept the call.</p>
        </tp:rationale>

        <p>If the channel was not explicitly requested (even if it was
          created as a side-effect of a call to one of those functions,
          e.g. because joining a Tube in a MUC context on XMPP implies
          joining that MUC), then this property is false.</p>

        <p>For compatibility with older connection managers, clients SHOULD
          assume that this property is true if they see a channel announced
          by the
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
          signal with the suppress_handler parameter set to true.</p>

        <tp:rationale>
          <p>In a correct connection manager, the only way to get such a
            channel is to request it.</p>
        </tp:rationale>

        <p>Clients MAY additionally assume that this property is false
          if they see a channel announced by the NewChannel signal with the
          suppress_handler parameter set to false.</p>

        <tp:rationale>
          <p>This is more controversial, since it's possible to get that
            parameter set to false by requesting a channel. However, there's
            no good reason to do so, and we've deprecated this practice.</p>

          <p>In the particular case of the channel dispatcher, the only
            side-effect of wrongly thinking a channel is unrequested
            is likely to be that the user has to confirm that they want to
            use it, so it seems fairly harmless to assume in the channel
            dispatcher that channels with suppress_handler false are
            indeed unrequested.</p>
        </tp:rationale>

        <p>It does not make sense for this property to be in channel
          requests—it will always be true for channels returned by
          CreateChannel, and callers of EnsureChannel cannot control whether an
          existing channel was originally requested locally—so it MUST NOT
          be accepted.</p>
      </tp:docstring>
    </property>

    <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
      access="read" tp:name-for-bindings="Initiator_Handle">
      <tp:added version="0.17.13">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The contact who initiated the channel; for instance, the contact
          who invited the local user to a chatroom, or the contact who
          initiated a call.</p>

        <p>This does <em>not</em> necessarily represent the contact who
          created the underlying protocol-level construct. For instance, if
          Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
          to join it, then Simon will see Will as the InitiatorHandle of the
          channel representing the chatroom.</p>

        <tp:rationale>
          <p>The room creator is generally a less useful piece of information
            than the inviter, is less likely to be available at invitation
            time (i.e. can't necessarily be an immutable property), and is
            less likely to be available at all. The creator of a chatroom
            is not currently available via Telepathy; if added in future, it
            is likely to be made available as a property on the Chatroom
            interface (<a
              href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
        </tp:rationale>

        <p>For channels requested by the
          local user, this MUST be the value of
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
          at the time the channel was created (i.e. not a channel-specific
          handle).</p>

        <tp:rationale>
          <p>On some protocols, the SelfHandle may change (as signalled by
            <tp:dbus-ref
              namespace="org.freedesktop.Telepathy">Connection.SelfContactChanged</tp:dbus-ref>),
            but this property is immutable. Hence, locally-requested channels'
            InitiatorHandle and InitiatorID may not match the current
            SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
            determine whether the channel was created locally.</p>
        </tp:rationale>

        <p>For channels requested by a remote user, this MUST be their handle.
          If unavailable or not applicable, this MUST be 0 (for instance,
          contact lists are not really initiated by anyone in particular, and
          it's easy to imagine a protocol where chatroom invitations can be
          anonymous).</p>

        <p>For channels with the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
          interface, this SHOULD be the same
          contact who is signalled as the "Actor" causing the self-handle
          to be placed in the local-pending set.</p>

        <p>This SHOULD NOT be a channel-specific handle, if possible.</p>

        <p>It does not make sense for this property to be in channel
          requests - the initiator will always be the local user - so it
          MUST NOT be accepted.</p>
      </tp:docstring>
    </property>

    <property name="InitiatorID" type="s" access="read"
      tp:name-for-bindings="Initiator_ID">
      <tp:added version="0.17.13">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The string that would result from inspecting the
          <tp:member-ref>InitiatorHandle</tp:member-ref>
          property (i.e. the initiator's identifier in the IM protocol).</p>

        <tp:rationale>
          <p>The presence of this property avoids the following race
            condition:</p>

          <ul>
            <li>New StreamedMedia channel C is signalled with initiator
              handle I</li>
            <li>Client calls <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [I])</li>
            <li>Channel C closes, removing the last reference to handle I</li>
            <li><tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
              [I]) returns an error</li>
            <li>Client can indicate that a call was missed, but not who
              called!</li>
          </ul>
        </tp:rationale>

        <p>It does not make sense for this property to be in channel
          requests - the initiator will always be the local user - so it
          MUST NOT be accepted.</p>
      </tp:docstring>
    </property>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
    <p>All communication in the Telepathy framework is carried out via channel
    objects which are created and managed by connections. This interface must
    be implemented by all channel objects, along with one single channel type,
    such as <tp:dbus-ref
    namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref>
    which represents a list of people (such as a buddy list) or <tp:dbus-ref
    namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which
    represents a channel over which textual messages are sent and received.</p>

    <p>Each Channel's object path MUST start with the object path of
      its associated <tp:dbus-ref
      namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed
      by '/'. There MAY be any number of additional object-path components,
      which clients MUST NOT attempt to parse.</p>

    <tp:rationale>
      <p>This ensures that Channel object paths are unique, even between
        Connections and CMs, because Connection object paths are
        guaranteed-unique via their link to the well-known bus name.</p>

      <p>If all connection managers in use are known to comply with at least
        spec version 0.17.10, then the Connection's object path can
        even be determined from the Channel's without any additional
        information, by taking the first 7 components.</p>
    </tp:rationale>

    <p>Each channel has a number of immutable properties (which cannot vary
      after the channel has been announced with <tp:dbus-ref
        namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>),
      provided to clients in the
      <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>,
      <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
      <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref>
      methods to permit immediate identification of the channel. This interface
      contains immutable properties common to all channels. In brief:</p>

    <ul>
      <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of
        communication carried out on this channel;</li>
      <li><tp:member-ref>TargetHandleType</tp:member-ref>,
        <tp:member-ref>TargetHandle</tp:member-ref> and
        <tp:member-ref>TargetID</tp:member-ref> specify the entity with which
        this channel communicates, such as the other party in a 1-1 call, or
        the name of a multi-user chat room;</li>
      <li><tp:member-ref>InitiatorHandle</tp:member-ref> and
        <tp:member-ref>InitiatorID</tp:member-ref> specify who created this
        channel;</li>
      <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local
        user requested this channel, or whether it is an incoming call, a text
        conversation started by a remote contact, a chatroom invitation,
        etc.</li>
    </ul>

    <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be
      implemented to indicate other available
      functionality, such as <tp:dbus-ref
        namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
      if the channel contains a number of contacts, <tp:dbus-ref
        namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
      to indicate that a channel may have a password set to require entry, and
      <tp:dbus-ref
        namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref>
      for typing notifications. The interfaces implemented may not vary after
      the channel has been created. These other interfaces (along with the
      interface named by <tp:member-ref>ChannelType</tp:member-ref>) may
      themselves specify immutable properties to be announced up-front along
      with the properties on this interface.</p>

    <p>Some channels are “anonymous”, with
      <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>,
      which indicates that the channel is defined by some other properties. For
      instance, transient ad-hoc chat rooms may be defined only by their members (as visible
      through the <tp:dbus-ref
        namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
      interface), and <tp:dbus-ref
        namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref>
      channels represent a single search attempt for a particular <tp:dbus-ref
        namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p>

    <p>Specific connection manager implementations may implement channel types and
    interfaces which are not contained within this specification in order to
    support further functionality. To aid interoperability between client and
    connection manager implementations, the interfaces specified here should be
    used wherever applicable, and new interfaces made protocol-independent
    wherever possible. Because of the potential for 3rd party interfaces adding
    methods or signals with conflicting names, the D-Bus interface names should
    always be used to invoke methods and bind signals.</p>
    </tp:docstring>

    <tp:changed version="0.17.7">Previously we guaranteed that, for
      any handle type other than Handle_Type_None, and for any channel type
      and any handle, there would be no more than one channel with that
      combination of channel type, handle type and handle. This guarantee
      has now been removed in order to accommodate features like message
      threads.
    </tp:changed>

    <tp:changed version="0.17.10">Previously we did not explicitly
      guarantee that Channels' object paths had the Connection's object path
      as a prefix.
    </tp:changed>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->