path: root/spec/Connection_Interface_Requests.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Requests"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
  >
  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2008 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.telepathy.v1.Connection.Interface.Requests">
    <tp:requires interface="im.telepathy.v1.Connection"/>
    <tp:added version="0.17.11">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An interface for channel requests and channel lists. Under
        normal circumstances, applications should deal with this
        interface via the <tp:dbus-ref
          namespace="imt1">ChannelDispatcher</tp:dbus-ref>,
        but lower-level Telepathy applications (such as the
        ChannelDispatcher itself) might need to use this interface
        directly.</p>

      <p>This interface is conceptually part of the core Connection
        interface, but is kept separate so that its properties will
        normally only need to be retrieved by the ChannelDispatcher,
        and its signals will normally only wake up the ChannelDispatcher.</p>
    </tp:docstring>

    <tp:struct name="Channel_Details" array-name="Channel_Details_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>

      <tp:docstring>
        Enough details of a channel that clients can work out how to dispatch
        or handle it.
      </tp:docstring>

      <tp:member name="Channel" type="o">
        <tp:docstring>
          The object path of the channel.
        </tp:docstring>
      </tp:member>

      <tp:member name="Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel.</p>

          <p>Connection managers MUST NOT include properties in this mapping
            if their values can change. Clients MUST ignore properties
            that appear in this mapping if their values can change.</p>

          <tp:rationale>
            <p>If properties that could change were included, the following
              race condition would be likely to exist in some cases:</p>

            <ul>
              <li>NewChannel or Get("Channels") includes a property P with
                value V1</li>
              <li>Client creates a proxy object for the channel</li>
              <li>The value of P changes to V2</li>
              <li>Client connects to PChanged signal</li>
              <li>Client should call Get("P") or GetAll here, to avoid the
                race, but client's author has forgotten to do so</li>
              <li>Proxy object thinks P == V1, but actually P == V2</li>
            </ul>

            <p>We've taken the opportunity to make the API encourage the
              client author to get it right. Where possible, we intend that
              properties whose value will be used in channel dispatching
              or other "early" processing will be defined so that they are
              immutable (can never change).</p>
          </tp:rationale>

          <p>Each dictionary MUST contain the keys
            <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>,
            <tp:dbus-ref>im.telepathy.v1.Channel.TargetEntityType</tp:dbus-ref>,
            <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandle</tp:dbus-ref>,
            <tp:dbus-ref>im.telepathy.v1.Channel.TargetID</tp:dbus-ref>
            and
            <tp:dbus-ref>im.telepathy.v1.Channel.Requested</tp:dbus-ref>.
          </p>

          <tp:rationale>
            <p>We expect these to be crucial to the channel-dispatching
              process.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:changed version="0.17.14">It is now guaranteed that
        CreateChannel returns the channel before NewChannel announces it
        (the reverse was previously guaranteed).</tp:changed>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that an entirely new channel is created.</p>
      </tp:docstring>

      <arg direction="in" name="Request" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties, which MUST include
            <tp:dbus-ref
              namespace="im.telepathy.v1.Channel">ChannelType</tp:dbus-ref>.
            Some properties
            are defined such that only an exact match makes sense, and
            connection managers MUST NOT satisfy a request with a channel
            where that property does not match; some properties are defined
            such that the connection manager MAY treat the request as merely
            a hint, and make a best-effort attempt to satisfy it. This is
            documented separately for each property.</p>

          <p>If this dictionary contains a property whose semantics
            are not known to the connection manager, this method MUST fail
            without side-effects (in particular it must not create a new
            channel).</p>

          <tp:rationale>
            <p>This is necessary if we want to be able to invent properties
              in future that, when used in a request, are hard requirements
              rather than just hints. A connection manager that did not know
              the semantics of those properties could incorrectly return a
              new channel that did not satisfy the requirements.</p>
          </tp:rationale>

          <p>The connection manager MUST NOT respond successfully,
            and SHOULD NOT create a new channel or cause any other
            side-effects, unless it can create a new channel that satisfies
            the client's requirements.</p>

          <p>Properties that will be set by this argument need not have write
            access after the channel has been created - indeed, it is
            expected that most will be read-only.</p>
        </tp:docstring>
      </arg>

      <arg name="Channel" direction="out" type="o">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The Channel object, which MUST NOT be signalled with
            <tp:member-ref>NewChannel</tp:member-ref> until after this method
            returns.</p>

          <tp:rationale>
            <p>This allows the requester to alter its handling of
              NewChannel by knowing whether the channel satisfied
              a request it made.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Properties" direction="out" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel that was produced, equivalent to
            the properties in <tp:type>Channel_Details</tp:type>.
            Connection managers MUST NOT include properties here whose
            values can change, for the same reasons as in
            <tp:type>Channel_Details</tp:type>.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            The channel request was one that can never succeed,
            such as requesting an unsupported channel type, or requesting
            a channel type which this connection manager does not support with
            the given target handle type.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle">
          <tp:docstring>
            An invalid handle was requested as the value of a property whose
            value is a handle (like
            <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
            or a syntactically invalid identifier was requested as the value
            of a property whose value is the string corresponding to a handle
            (like <tp:dbus-ref
            namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
          <tp:docstring>
            The request matched the fixed properties of a
            <tp:type>Requestable_Channel_Class</tp:type> in
            <tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the
            allowed arguments did not make sense; for example, a <tp:dbus-ref
              namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref>
            was requested, but the <tp:dbus-ref
              namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
            property provided was not a valid DNS name.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotCapable">
          <tp:docstring>
            The requested channel cannot be created because the requested
            contact is using a client that lacks a particular feature.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.Offline">
          <tp:docstring>
            The requested channel cannot be created because the target is
            offline.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotAvailable">
          <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
            <p>The requested channel cannot be created, but in
              principle, a similar request might succeed in future.
              For instance, this might be because:</p>

            <ul>
              <li>a channel matching the request already exists and the
                protocol requires that only one such channel can exist at a
                time</li>
              <li>a channel matching the request has already been requested
                (by a previous call to CreateChannel,
                <tp:member-ref>EnsureChannel</tp:member-ref>,
                or similar) and the protocol requires that only one such
                channel can exist at a time</li>
            </ul>
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
        <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
        <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
        <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
      <tp:added version="0.17.12"/>
      <tp:changed version="0.17.14">It is now guaranteed that if
        the channel was created by this call to EnsureChannel, it's returned
        before NewChannel announces it (the reverse was previously
        guaranteed).</tp:changed>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that channels are ensured to exist.</p>

        <tp:rationale>
          <p>The connection manager is in the best position to determine which
            existing channels could satisfy which requests.</p>
        </tp:rationale>

      </tp:docstring>

      <arg direction="in" name="Request" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties, with the same
            semantics as the corresponding parameter to
            <tp:member-ref>CreateChannel</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg name="Yours" direction="out" type="b">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If false, the caller of EnsureChannel MUST assume that some
            other process is handling this channel; if true, the caller of
            EnsureChannel SHOULD handle it themselves or delegate it to another
            client.</p>

          <p>If the creation of a channel makes several calls to EnsureChannel
            (and no other requests) successful, exactly one of those calls MUST
            return a true value for this argument.</p>

          <p>If the creation of a channel makes other requests successful,
            the value returned for this argument MUST be such that exactly
            one of the clients making requests ends up responsible for the
            channel. In particular, if
            <tp:member-ref>CreateChannel</tp:member-ref> returns a channel
            <em>C</em>, any EnsureChannel calls that also return <em>C</em>
            MUST return a false value for this argument.</p>
        </tp:docstring>
      </arg>

      <arg name="Channel" direction="out" type="o">
        <tp:docstring>
          The Channel object. If it was created as a result of this method
          call, it MUST NOT be signalled by
          <tp:member-ref>NewChannel</tp:member-ref> until after this method
          returns.

          <tp:rationale>
            <p>This allows the requester to alter its handling of
              NewChannel by knowing whether the channel satisfied
              a request it made.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Properties" direction="out" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel that was produced, equivalent to
            the properties in <tp:type>Channel_Details</tp:type>.
            Connection managers MUST NOT include properties here whose
            values can change, for the same reasons as in
            <tp:type>Channel_Details</tp:type>.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            The channel request was one that can never succeed,
            such as requesting an unsupported channel type, or requesting
            a channel type which this connection manager does not support with
            the given target handle type.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle">
          <tp:docstring>
            An invalid handle was requested as the value of a property whose
            value is a handle (like
            <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
            or a syntactically invalid identifier was requested as the value
            of a property whose value is the string corresponding to a handle
            (like <tp:dbus-ref
            namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
          <tp:docstring>
            The request matched the fixed properties of a
            <tp:type>Requestable_Channel_Class</tp:type> in
            <tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the
            allowed arguments did not make sense; for example, a <tp:dbus-ref
              namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref>
            was requested, but the <tp:dbus-ref
              namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
            property provided was not a valid DNS name.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotCapable">
          <tp:docstring>
            The requested channel cannot be created because the requested
            contact is using a client that lacks a particular feature.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.Offline">
          <tp:docstring>
            The requested channel cannot be created because the target is
            offline.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotAvailable">
          <tp:docstring>
            The requested channel cannot be created, but in
            principle, a similar request might succeed in future.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
        <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
        <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
        <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <signal name="NewChannel" tp:name-for-bindings="New_Channel">
      <tp:added version="0.99.7"/>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A new channel has been created.</p>

        <p>Unlike in some previous Telepathy versions, the connection manager
          cannot emit a single signal for multiple channels.
          For example, joining a MUC Tube in XMPP requires joining the
          corresponding MUC (chatroom). Either the connection manager
          should announce a new <tp:dbus-ref
          namespace="imt1.Channel.Type">Text</tp:dbus-ref> channel
          separately, or not expose the Text channel on the bus
          until it's actually requested (or an incoming message
          appears).</p>

        <tp:rationale>
          <p>Signalling the creation of multiple channels together
            makes writing simple clients much more complicated, can
            result in lost messages, and isn't nearly as useful in
            practice as it sounds.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Channel" type="o">
        <tp:docstring>
          The object path of the channel.
        </tp:docstring>
      </arg>

      <arg name="Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The same properties of the channel that would appear in the
            <tp:type>Channel_Details</tp:type> struct.</p>
        </tp:docstring>
      </arg>
    </signal>

    <property name="Channels" tp:name-for-bindings="Channels"
      type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring>
        A list of all the channels which currently exist on this connection.
        Change notification is via the
        <tp:member-ref>NewChannel</tp:member-ref> and
        <tp:member-ref>ChannelClosed</tp:member-ref> signals.
      </tp:docstring>
    </property>

    <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring>
        Emitted when a channel is closed and hence disappears from the
        <tp:member-ref>Channels</tp:member-ref> property.

        <tp:rationale>
          This is redundant with the <tp:dbus-ref
            namespace="im.telepathy.v1.Channel">Closed</tp:dbus-ref>
          signal on the channel itself, but it does provide full change
          notification for the Channels property.
        </tp:rationale>
      </tp:docstring>

      <arg name="Removed" type="o">
        <tp:docstring>
          The channel which has been removed from the Channels property
        </tp:docstring>
      </arg>
    </signal>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->