path: root/spec/Connection_Interface_Contact_Capabilities1.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_Capabilities1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright (C) 2005, 2006, 2008 Collabora Limited </tp:copyright>
  <tp:copyright> Copyright (C) 2005, 2006, 2008 Nokia Corporation </tp:copyright>
  <tp:copyright> Copyright (C) 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="im.telepathy1.Connection.Interface.ContactCapabilities1">
    <tp:requires interface="im.telepathy1.Connection"/>
    <tp:added version="0.17.28">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Contact capabilities describe the channel classes which may be
        created with a given contact in advance of attempting to create a
        channel. Each capability represents a commitment by the
        connection manager that it will ordinarily be able to create a channel
        with a contact when given a request with the properties defined by the
        channel class.</p>

      <p>Capabilities pertain to particular contact handles, and represent
        activities such as having a text chat, a voice call with the user or a
        stream tube of a defined type.</p>

      <p>This interface also enables user interfaces to notify the connection
        manager what capabilities to advertise for the user to other contacts.
        This is done by using the
        <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p>

      <tp:rationale>
        <p>XMPP is a major user of this interface: XMPP contacts will not,
          in general, be callable using VoIP unless they advertise suitable
          Jingle capabilities.</p>

        <p>Many other protocols also have some concept of capability flags,
          which this interface exposes in a protocol-independent way.</p>
      </tp:rationale>
    </tp:docstring>

    <tp:struct name="Handler_Capabilities"
      array-name="Handler_Capabilities_List">
      <tp:docstring>
        A structure representing the capabilities of a single client.
      </tp:docstring>

      <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name">
        <tp:docstring>
          For implementations of the <tp:dbus-ref
            namespace="im.telepathy1">Client</tp:dbus-ref>
          interface, the well-known bus name name of the client; for any other
          process, any other reversed domain name that uniquely identifies it.
        </tp:docstring>
      </tp:member>

      <tp:member name="Channel_Classes" type="aa{sv}"
           tp:type="String_Variant_Map[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          An array of channel classes that can be handled by this client.
          This will usually be a copy of the client's <tp:dbus-ref
            namespace="im.telepathy1.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
          property.
        </tp:docstring>
      </tp:member>

      <tp:member name="Capabilities"
        type="as" tp:type="Handler_Capability_Token[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          An array of client capabilities supported by this client, to be
          used by the connection manager to determine what capabilities to
          advertise. This will usually be a copy of the client's <tp:dbus-ref
            namespace="im.telepathy1.Client.Handler">Capabilities</tp:dbus-ref>
          property.
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Alter the connection's advertised capabilities to include
          the intersection of the given clients' capabilities with what the
          connection manager is able to implement.</p>

        <p>On connections managed by the ChannelDispatcher, processes other
          than the ChannelDispatcher SHOULD NOT call this method, and the
          ChannelDispatcher SHOULD use this method to advertise the
          capabilities of all the registered <tp:dbus-ref
            namespace="im.telepathy1">Client.Handler</tp:dbus-ref>
          implementations.On connections not managed by the ChannelDispatcher,
          clients MAY use this method directly, to indicate the channels they
          will handle and the extra capabilities they have.</p>

        <p>Upon a successful invocation of this method, the connection manager
          will only emit the
          <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
          for the user's <tp:dbus-ref
            namespace="im.telepathy1.Connection">SelfHandle</tp:dbus-ref>
          if, in the underlying protocol, the new capabilities are distinct
          from the previous state.</p>

        <tp:rationale>
          <p>The connection manager will essentially intersect the provided
            capabilities and the channel classes it implements. Therefore,
            certain properties which are never fixed for a channel class
            (such as the target handle, or the Parameters property of a tube
            channel) will almost certainly not be advertised.</p>
        </tp:rationale>

        <p>This method MAY be called on a newly-created connection while it
          is still in the DISCONNECTED state, to request that when the
          connection connects, it will do so with the appropriate
          capabilities. Doing so MUST NOT fail.</p>
      </tp:docstring>

      <arg direction="in" name="Handler_Capabilities" type="a(saa{sv}as)"
        tp:type="Handler_Capabilities[]">
        <tp:docstring>
          <p>The capabilities of one or more clients.</p>

          <p>For each client in the given list, any capabilities previously
            advertised for the same client name are discarded, then replaced by
            the capabilities indicated.</p>

          <p>As a result, if a client becomes unavailable, this method SHOULD
            be called with a <tp:type>Handler_Capabilities</tp:type> structure
            containing its name, an empty list of channel classes, and an
            empty list of capabilities. When this is done, the connection
            manager SHOULD free all memory associated with that client name.</p>

          <tp:rationale>
            <p>This method takes a list of clients so that
              when the channel dispatcher first calls it (with a list of all
              the Handlers that are initially available), the changes can be
              made atomically, with only one transmission of updated
              capabilities to the network. Afterwards, the channel dispatcher
              will call this method with a single-element list every time
              a Handler becomes available or unavailable.</p>
          </tp:rationale>

          <p>The connection manager MUST ignore any channel classes and client
            capabilities for which there is no representation in the protocol
            or no support in the connection manager.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.NetworkError"/>
      </tp:possible-errors>
    </method>

    <method name="GetContactCapabilities"
            tp:name-for-bindings="Get_Contact_Capabilities">
      <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>An array of contact handles for this connection.</p>

          <p>The handle zero MUST NOT be included in the request.</p>
        </tp:docstring>
      </arg>
      <arg direction="out" type="a{ua(a{sv}as)}"
           tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A map from contact handles to lists of requestable channel
            classes, representing the channel requests that are expected
            to succeed for that contact.</p>

          <p>Contacts listed among Handles whose capabilities are unknown
            SHOULD be omitted from this map; contacts known to have an empty
            set of capabilities SHOULD be included in the keys of this map,
            with an empty array as the corresponding value.</p>
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Returns an array of requestable channel classes for the given
          contact handles, representing the channel requests that are
          expected to succeed.</p>
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.Disconnected"/>
        <tp:error name="im.telepathy1.Error.InvalidHandle">
          <tp:docstring>
            The handle does not represent a contact. Zero is always invalid.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="ContactCapabilitiesChanged"
            tp:name-for-bindings="Contact_Capabilities_Changed">
      <arg name="caps" type="a{ua(a{sv}as)}"
           tp:type="Contact_Capabilities_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          All the capabilities of the contacts
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Announce that there has been a change of capabilities on the
          given handles. A single signal can be emitted for several
        contacts.</p>

        <tp:rationale>
          <p>The underlying protocol can get several contacts' capabilities at
            the same time.</p>
        </tp:rationale>

      </tp:docstring>
    </signal>

  <tp:mapping name="Contact_Capabilities_Map"
              array-name="Contact_Capabilities_Map_List">
    <tp:docstring>A mapping from contact handle to their capabilities.
    </tp:docstring>
    <tp:member type="u" name="Key" tp:type="Contact_Handle">
      <tp:docstring>
        A contact handle.
      </tp:docstring>
    </tp:member>
    <tp:member type="a(a{sv}as)" name="Value"
               tp:type="Requestable_Channel_Class[]">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The contact's capabilities. These should be represented
          in the same way as in <tp:dbus-ref
            namespace="im.telepathy1.Connection.Interface.Requests"
            >RequestableChannelClasses</tp:dbus-ref>,
          except that they may have more fixed properties or fewer allowed
          properties, to represent contacts who do not have all the
          capabilities of the connection.</p>

        <p>In particular, requestable channel classes for channels with
          target handle type Contact MUST list <tp:dbus-ref
            namespace="im.telepathy1.Channel"
            >TargetHandleType</tp:dbus-ref> among their fixed properties when
          they appear here, and clients MAY assume that this will be the
          case.</p>

        <tp:rationale>
          <p>This matches the initial implementations - service-side in
            telepathy-gabble, and client-side in telepathy-qt4 - and means
            that clients can use exactly the same code to interpret
            RequestableChannelClasses and contact capabilities.</p>
        </tp:rationale>

        <p>Channel classes with target handle type Handle_Type_Contact
          indicate that a request that matches the channel class, and also
          either has the contact's handle as <tp:dbus-ref
            namespace="im.telepathy1.Channel"
            >TargetHandle</tp:dbus-ref> or the contact's identifier as
          <tp:dbus-ref namespace="im.telepathy1.Channel"
            >TargetID</tp:dbus-ref>, can be expected to succeed. Connection
          managers SHOULD NOT include the TargetHandle or TargetID as a
          fixed property in contact capabilities.</p>

        <tp:rationale>
          <p>This makes one channel class sufficient to describe requests via
            TargetHandle or TargetID, and is necessary in order to allow
            clients to interpret RequestableChannelClasses and contact
            capabilities with the same code.</p>
        </tp:rationale>

        <p>Channel classes with target handle type Handle_Type_Room or
          Handle_Type_None indicate that if a channel matching the channel
          class is created, then inviting the contact to that channel
          can be expected to succeed.</p>

        <tp:rationale>
          <p>To support room-based XMPP protocols like
            <a href="http://telepathy.freedesktop.org/wiki/Muji">Muji</a>
            and MUC Tubes, it's necessary to be able to discover who can be
            invited to a given room channel; most XMPP contacts won't
            support being invited into a Muji conference call, at least
            in the short to medium term.</p>
        </tp:rationale>

        <p>No interpretation is defined for channel classes with any other
          target handle type, or for channel classes that do not fix a
          target handle type, in this version of the Telepathy
          specification.</p>
      </tp:docstring>
    </tp:member>
  </tp:mapping>

    <tp:contact-attribute name="capabilities"
      type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The same structs that would be returned by
          <tp:member-ref>GetContactCapabilities</tp:member-ref>.
          Omitted from the result if the contact's capabilities
          are not known; present in the result as an empty array if the
          contact is known to have no capabilities at all.</p>
      </tp:docstring>
    </tp:contact-attribute>

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