path: root/spec/Connection.xml

<?xml version="1.0" ?>
<node name="/Connection"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
  >
  <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2005-2009 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.telepathy.v1.Connection">
    <method name="Connect" tp:name-for-bindings="Connect">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that the connection be established. This will be done
          asynchronously and errors will be returned by emitting
          <tp:member-ref>StatusChanged</tp:member-ref> signals.</p>

        <p>Calling this method on a Connection that is already connecting
          or connected is allowed, and has no effect.</p>
      </tp:docstring>
    </method>

    <method name="Disconnect" tp:name-for-bindings="Disconnect">
      <tp:docstring>
        Request that the connection be closed. This closes the connection if
        it's not already in DISCONNECTED state, and destroys the connection
        object.
      </tp:docstring>
    </method>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      access="read" type="as" tp:type="DBus_Interface[]">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The set of optional interfaces supported by this connection.
          Before the connection status changes to CONNECTED,
          this property may change at any time, but it is guaranteed that
          interfaces will only be added, not removed. After the connection
          status changes to CONNECTED, this property cannot
          change further.</p>

        <p>There is no explicit change notification; reasonable behaviour
          for a client would be to retrieve the interfaces list once
          initially, and once more when it becomes CONNECTED.</p>

        <tp:rationale>
          <p>In some connection managers, certain capabilities of a connection
            are known to be implemented for all connections (e.g. support
            for Presence), and some interfaces (like Presence) can
            even be used before connecting. Other capabilities may
            or may not exist, depending on server functionality; by the time
            the connection goes CONNECTED, the connection manager is expected
            to have evaluated the server's functionality and enabled any extra
            interfaces for the remainder of the Connection's lifetime.</p>
        </tp:rationale>

        <tp:rationale>
          <p>It has been mandatory since Telepathy 0.18 in 2009,
            and contains essential functionality for this interface,
            so there seems no point in wasting bytes on capability discovery
            for it.</p>
        </tp:rationale>
      </tp:docstring>
      <tp:added version="0.19.2"/>
    </property>

    <signal name="SelfContactChanged"
        tp:name-for-bindings="Self_Contact_Changed">
      <tp:docstring>
        Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> and
        <tp:member-ref>SelfID</tp:member-ref> property
        changes. If the connection
        is not yet in the CONNECTED state, this signal is not guaranteed
        to be emitted.
      </tp:docstring>
      <tp:added version="0.27.2">Clients MAY assume that if the
        SelfHandle and SelfID property exists, this signal will be emitted when
        necessary.</tp:added>

      <arg type="u" tp:type="Contact_Handle" name="Self_Handle">
        <tp:docstring>
          The new value of the SelfHandle property.
        </tp:docstring>
      </arg>
      <arg type="s" name="Self_ID">
        <tp:docstring>
          The new value of the SelfID property.
        </tp:docstring>
      </arg>
    </signal>

    <property name="SelfHandle" tp:name-for-bindings="Self_Handle"
      type="u" tp:type="Contact_Handle" access="read">
      <tp:docstring>
        The handle which represents the user on this connection, which will
        remain valid for the lifetime of this connection, or until a change
        in the user's identifier is signalled by the
        <tp:member-ref>SelfContactChanged</tp:member-ref> signal.
        If the connection is not yet in the CONNECTED state, the value of
        this property MAY be zero.
      </tp:docstring>
      <tp:added version="0.17.10"/>
    </property>

    <property name="SelfID" tp:name-for-bindings="Self_ID"
      type="s" access="read">
      <tp:docstring>
        The identifier which represents the user on this connection, which will
        remain valid for the lifetime of this connection, or until a change
        in the user's identifier is signalled by the
        <tp:member-ref>SelfContactChanged</tp:member-ref> signal.
        If the connection is not yet in the CONNECTED state, the value of
        this property MAY be empty string.
      </tp:docstring>
      <tp:added version="0.27.2"/>
    </property>

    <property name="Status" tp:name-for-bindings="Status"
      access="read" type="u" tp:type="Connection_Status">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The current status of the connection. Change notification is via
          the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p>

        <p>If retrieval of property succeeds and yields the value Disconnected,
          this indicates that the connection has not yet been established.
          If connection has been attempted and failed, the Connection object
          SHOULD be removed from the bus entirely, meaning that retrieval of
          this property SHOULD fail.</p>
      </tp:docstring>
      <tp:added version="0.19.2"/>
    </property>

    <tp:enum name="Handle_Type" type="u">
      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          A "null" handle type used to indicate the absence of a handle.
          When a handle type and a handle appear as a pair, if the handle
          type is zero, the handle must also be zero.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Contact" value="1">
        <tp:docstring>
          A contact
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Room" value="2">
        <tp:docstring>
          A chat room
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:simple-type name="Handle" type="u" array-name="Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a
        handle</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="Contact_Handle" type="u"
      array-name="Contact_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_Contact</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="Room_Handle" type="u"
      array-name="Room_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_Room</tp:docstring>
    </tp:simple-type>

    <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u">
      <tp:enumvalue suffix="Connected" value="0">
        <tp:docstring>
          The connection is fully connected and all methods are available.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Connecting" value="1">
        <tp:docstring>
          <tp:member-ref>Connect</tp:member-ref> has been called but the
          connection has not yet been established. Some methods may fail
          until the connection has been established.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Disconnected" value="2">
        <tp:docstring>
          If this is retrieved from
          <tp:member-ref>Status</tp:member-ref>, it indicates that
          connection has not yet been attempted. If seen in a
          <tp:member-ref>StatusChanged</tp:member-ref> signal, it
          indicates that the connection has failed; the Connection
          object SHOULD be removed from D-Bus immediately, and all
          subsequent method calls SHOULD fail.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="Connection_Status_Reason" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A reason why the status of the connection changed. Apart from
          Requested, the values of this enumeration only make sense as
          reasons why the status changed to Disconnected.</p>
      </tp:docstring>

      <tp:enumvalue suffix="None_Specified" value="0">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There is no reason set for this state change. Unknown status
            reasons SHOULD be treated like this reason.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Requested" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The change is in response to a user request. Changes to the
            Connecting or Connected status SHOULD always indicate this reason;
            changes to the Disconnected status SHOULD indicate this reason
            if and only if the disconnection was requested by the user.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cancelled</code>.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Network_Error" value="2">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was an error sending or receiving on the network socket.</p>

          <p>When the status changes from Connecting to Disconnected for this
            reason, the equivalent D-Bus error is either
            <code>im.telepathy.v1.Error.NetworkError</code>,
            <code>im.telepathy.v1.Error.ConnectionRefused</code>,
            <code>im.telepathy.v1.Error.ConnectionFailed</code>
            or some more specific error.</p>

          <p>When the status changes from Connected to Disconnected for this
            reason, the equivalent D-Bus error is either
            <code>im.telepathy.v1.Error.NetworkError</code>,
            <code>im.telepathy.v1.Error.ConnectionLost</code>
            or some more specific error.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Authentication_Failed" value="3">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The username or password was invalid.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.AuthenticationFailed</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Encryption_Error" value="4">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was an error negotiating SSL on this connection, or
            encryption was unavailable and require-encryption was set when the
            connection was created.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.EncryptionNotAvailable</code>
            if encryption was not available at all, or
            <code>im.telepathy.v1.Error.EncryptionError</code>
            if encryption failed.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Name_In_Use" value="5">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>In general, this reason indicates that the requested account
            name or other identification could not be used due to conflict
            with another connection. It can be divided into three cases:</p>

          <ul>
            <li>If the status change is from Connecting to Disconnected
              and the 'register' parameter to RequestConnection was present
              and true, the requested account could not be created on the
              server because it already exists.
              The equivalent D-Bus error is
              <code>im.telepathy.v1.Error.RegistrationExists</code>.
            </li>

            <li>If the status change is from Connecting to Disconnected
              but the 'register' parameter is absent or false, the connection
              manager could not connect to the specified account because
              a connection to that account already exists.
              The equivalent D-Bus error is
              <code>im.telepathy.v1.Error.AlreadyConnected</code>.

              <tp:rationale>
                In some protocols, like XMPP (when connecting with the same
                JID and resource as an existing connection), the existing
                connection "wins" and the new one fails to connect.
              </tp:rationale>
            </li>

            <li>If the status change is from Connected to Disconnected,
              the existing connection was automatically disconnected because
              a new connection to the same account (perhaps from a different
              client or location) was established.
              The equivalent D-Bus error is
              <code>im.telepathy.v1.Error.ConnectionReplaced</code>.

              <tp:rationale>
                In some protocols, like MSNP (when connecting twice with the
                same Passport), the new connection "wins" and the
                existing one is automatically disconnected.
              </tp:rationale>
            </li>
          </ul>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Not_Provided" value="6">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server did not provide a SSL certificate.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.NotProvided</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Untrusted" value="7">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is signed by an untrusted certifying
            authority. This error SHOULD NOT be used to represent a self-signed
            certificate: use the more specific Cert_Self_Signed reason for
            that.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.Untrusted</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Expired" value="8">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate has expired.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.Expired</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Not_Activated" value="9">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is not yet valid.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.NotActivated</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate did not match its hostname.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.HostnameMismatch</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate does not have the expected
            fingerprint.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.FingerprintMismatch</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Self_Signed" value="12">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is self-signed.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.SelfSigned</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Other_Error" value="13">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was some other error validating the server's SSL
            certificate.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.Invalid</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Revoked" value="14">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate has been revoked.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.Revoked</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Insecure" value="15">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate uses an insecure algorithm,
	  or is cryptographically weak.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>im.telepathy.v1.Error.Cert.Insecure</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16">
	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	  <p>The length in bytes of the server certificate, or the depth of the
	  sever certificate chain exceed the limits imposed by the crypto
	  library.</p>

	  <p>When disconnected for this reason, the equivalent D-Bus error is
	    <code>im.telepathy.v1.Error.Cert.LimitExceeded</code>
	  </p>
	</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <signal name="ConnectionError" tp:name-for-bindings="Connection_Error">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when an error occurs that renders this connection unusable.
        </p>

        <p>Whenever this signal is emitted, it MUST immediately be followed by
          a <tp:member-ref>StatusChanged</tp:member-ref> signal with status
          Connection_Status_Disconnected and an appropriate reason
          code.</p>

        <p>Connection managers SHOULD emit this signal on disconnection, but
          need not do so. Clients MUST support connection managers that emit
          StatusChanged(Disconnected, ...) without first emitting
          ConnectionError.</p>

        <tp:rationale>
          <p>This signal provides additional information about the reason
            for disconnection. The reason for connection is always
            straightforward - it was requested - so it does not need further
            explanation. However, on errors, it can be useful to provide
            additional information.</p>

          <p>The <tp:type>Connection_Status_Reason</tp:type> is not given
            here, since it will be signalled in
            <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client
            implementation would be to store the information given by this
            signal until StatusChanged is received, at which point the
            information given by this signal can be used to supplement the
            StatusChanged signal.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Error" type="s" tp:type="DBus_Error_Name">
        <tp:docstring>
          The name of a D-Bus error describing the error that occurred,
          which may correspond to a
          <tp:type>Connection_Status_Reason</tp:type>, or may be a more
          specific Telepathy error
          (such as
          <code>im.telepathy.v1.Error.ConnectionRefused</code>
          for Connection_Status_Reason_Network_Error)
          or a protocol-specific or connection-manager-specific error in a
          suitable namespace.

          <tp:rationale>
            For instance, a SIP connection manager could signal
            "402 Payment Required" as an error in a
            connection-manager-specific namespace, or a link-local
            XMPP implementation that used Avahi could provide the error
            given to it by the avahi-daemon.
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Additional information about the error, which may include
            the following well-known keys:</p>

          <dl>
            <dt>debug-message (s)</dt>
            <dd>Debugging information on the change, corresponding to the
              message part of a D-Bus error message, which SHOULD NOT be
              displayed to users under normal circumstances</dd>

            <dt>server-message (s)</dt>
            <dd>A human-readable message from the server explaining what
              happened. This may be in the user's native language, or in the
              server operator's native language, or even in Lojban.</dd>

	    <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
	    <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd>
          </dl>

        </tp:docstring>
      </arg>

    </signal>

    <signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
      <arg name="Status" type="u" tp:type="Connection_Status">
        <tp:docstring>
          An integer indicating the new status, as defined by ConnectionStatus
        </tp:docstring>
      </arg>

      <arg name="Reason" type="u" tp:type="Connection_Status_Reason">
        <tp:docstring>
          An integer indicating the reason for the status change, as defined
          by ConnectionStatusReason
        </tp:docstring>
      </arg>

      <tp:docstring>
        Emitted when the status of the connection changes.  All states and
        reasons have numerical values, as defined in ConnectionStatus
        and ConnectionStatusReason.
      </tp:docstring>
    </signal>

    <tp:contact-attribute name="contact-id" type="s">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The normalized contact's identifier. Not necessarily the same string
          as passed to <tp:member-ref>GetContactByID</tp:member-ref>.
          As a special case, this is always present in the result of
          <tp:member-ref>GetContactAttributes</tp:member-ref> and
          <tp:member-ref>GetContactByID</tp:member-ref>,
          whether it was explicitly requested or not.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest">
      <tp:added version="0.21.3"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Register a client's interest in notifications related to one or
          more interfaces.</p>

        <p>Groups of notifications are identified by a token which is either
          a D-Bus interface name, or a string that starts with a D-Bus
          interface name. The meaning of each token is given by that D-Bus
          interface, which MUST define it in its documentation.</p>

        <tp:rationale>
          <p>Initially, all interests are in entire interface, but allowing
            other strings allows subscription to part of an interface; for
            instance, an interest in ...MailNotification/count could track
            the number of messages without caring about their detailed
            content.</p>
        </tp:rationale>

        <p>For each token with which this method interacts, the
          Connection tracks an "interest count" (like a reference count) for
          each unique bus name that has called this method. When a client
          calls this method, for each token, the interest count for its
          unique bus name is incremented; when
          <tp:member-ref>RemoveClientInterest</tp:member-ref> is called,
          all interest counts for that unique bus name are decremented.
          If the unique bus name leaves the bus (for instance, if the
          client crashes or exits), all interest counts for that unique bus
          name are set to zero.</p>

        <p>The Connection can then use these reference counts to
          avoid subscribing to protocol-level notifications unless at least
          one client has a non-zero interest count for the relevant
          token.</p>

        <tp:rationale>
          <p>This method exists to reduce memory and network overhead when
            there is no active subscription.</p>

          <p>One situation where this is useful is <tp:dbus-ref
              namespace="im.telepathy.v1.Connection.Interface"
              >Location1</tp:dbus-ref>: on XMPP, location updates are received
            over PEP. If the Connection advertises the
            <code>geoloc+notify</code> capability, it will be sent location
            updates for all contacts. To avoid consuming resources for this,
            the connection should avoid advertising that capability until
            a client has expressed an interest in contacts' locations.</p>

          <p>Another example of a protocol that benefits from this method is
            the Google XMPP Mail Notification extension, which can be used
            to implement <tp:dbus-ref
              namespace="im.telepathy.v1.Connection.Interface"
              >MailNotification1</tp:dbus-ref>. In this protocol, the CM
            receives a notification that something has changed, but to get
            more information, the CM must request this information. Knowing
            that nobody is currently interested in this information, the CM
            can avoid generating useless network traffic. Similarly, the CM
            may free the list of unread messages to reduce memory overhead.</p>
        </tp:rationale>

        <p>If this method is called for an interface that might require
          protocol-level subscription, but the connection cannot set up
          that subscription yet (for instance because the
          <tp:member-ref>Status</tp:member-ref> is not Connected yet), the
          Connection MUST remember the client's interest, and attempt to
          subscribe to the appropriate protocol feature when this becomes
          possible.</p>

        <p>Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.</p>

        <tp:rationale>
          <p>The only reason it could fail is if it's unimplemented, in which
            case the only thing the client can usefully do is to proceed as if
            it had succeeded.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Tokens" type="as" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Interfaces or parts of interfaces in which to register an
            interest, represented by either a
            <tp:type>DBus_Interface</tp:type>, or a string prefixed with a
            <tp:type>DBus_Interface</tp:type>.</p>

          <p>If the Connection does not support one of these tokens, this
            is not considered to be an error; the unsupported token is
            simply ignored.</p>
        </tp:docstring>
      </arg>
    </method>

    <method name="RemoveClientInterest"
      tp:name-for-bindings="Remove_Client_Interest">
      <tp:added version="0.21.3"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Release an interest registered using
          <tp:member-ref>AddClientInterest</tp:member-ref>. See that
          method's documentation for details.</p>

        <p>Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.</p>

        <tp:rationale>
          <p>The only reasons it could fail are if it's unimplemented, or if
            the client's reference-counting is wrong and it has tried to
            remove a client interest that it did not add. In both cases,
            there's nothing the client could do about it.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Tokens" type="as" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Interfaces or parts of interfaces that were previously passed to
            <tp:member-ref>AddClientInterest</tp:member-ref>.</p>
        </tp:docstring>
      </arg>
    </method>

    <tp:simple-type name="Contact_Attribute" type="s">
      <tp:docstring>
        A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
        and an identifier for an attribute defined by that interface. The
        attribute identifier SHOULD be in lower case.

        <tp:rationale>
          These aren't D-Bus core Properties, and we want them to look visibly
          different.
        </tp:rationale>
      </tp:docstring>
    </tp:simple-type>

    <tp:mapping name="Single_Contact_Attributes_Map">
      <tp:docstring>
        Some of the attributes of a single contact.
      </tp:docstring>

      <tp:member type="s" tp:type="Contact_Attribute" name="Attribute">
        <tp:docstring>
          The name of the attribute
        </tp:docstring>
      </tp:member>

      <tp:member type="v" name="Value">
        <tp:docstring>
          The value of the attribute
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:mapping name="Contact_Attributes_Map">
      <tp:docstring>Mapping returned by
        <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a
        collection of Contacts and their requested attributes.</tp:docstring>

      <tp:member type="u" tp:type="Contact_Handle" name="Contact">
        <tp:docstring>
          A contact
        </tp:docstring>
      </tp:member>

      <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map"
        name="Attributes">
        <tp:docstring>
          Attributes of that contact
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <method name="GetContactAttributes"
      tp:name-for-bindings="Get_Contact_Attributes">
      <tp:docstring>
        Return any number of contact attributes for the given handles.
      </tp:docstring>

      <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          An array of handles representing contacts.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Interfaces" type="as"
        tp:type="DBus_Interface[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A list of strings indicating which D-Bus interfaces the calling
            process is interested in. All supported attributes from these
            interfaces, whose values can be obtained without additional network
            activity, will be in the reply.</p>

          <p>Attributes from the interface
            <tp:dbus-ref>im.telepathy.v1.Connection</tp:dbus-ref>
            are always returned, and need not be requested explicitly.</p>

          <p>As well as returning cached information immediately, the
            connection MAY start asynchronous requests to obtain better
            values for the contact attributes. If better values are later
            obtained by this process, they will be indicated with the usual
            signals (such as <tp:dbus-ref
              namespace="im.telepathy.v1.Connection.Interface.Aliasing1">AliasesChanged</tp:dbus-ref>).</p>

          <tp:rationale>
            For instance, an XMPP connection manager could download vCards
            in response to a request for <tp:dbus-ref
              namespace="im.telepathy.v1.Connection.Interface">Aliasing1</tp:dbus-ref>
            attributes.
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg direction="out" type="a{ua{sv}}" name="Attributes"
        tp:type="Contact_Attributes_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary mapping the contact handles to contact attributes.
            If any of the requested handles are in fact invalid, they are
            simply omitted from this mapping. If contact attributes are not
            immediately known, the behaviour is defined by the interface;
            the attribute should either be omitted from the result or
            replaced with a default value.</p>

          <p>Each contact's attributes will always include at least the
            identifier that would be obtained by inspecting the handle
            (<code>im.telepathy.v1.Connection/contact-id</code>).</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
      </tp:possible-errors>
    </method>

    <method name="GetContactByID"
      tp:name-for-bindings="Get_Contact_By_ID">
      <tp:added version="0.27.0"/>
      <tp:docstring>
        Return any number of contact attributes for the given identifier.
        <tp:rationale>
          This is for a single identifier to make it simpler to use for the most
          common use case. For multiple contacts case,
          <tp:member-ref>GetContactAttributes</tp:member-ref> should be used.
        </tp:rationale>
      </tp:docstring>

      <arg direction="in" name="Identifier" type="s">
        <tp:docstring>
          An identifier representing a contact.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Interfaces" type="as"
        tp:type="DBus_Interface[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A list of strings indicating which D-Bus interfaces the calling
            process is interested in. All supported attributes from these
            interfaces, whose values can be obtained without additional network
            activity, will be in the reply.</p>
          <p>See <tp:member-ref>GetContactAttributes</tp:member-ref> for
            details.</p>
        </tp:docstring>
      </arg>

      <arg direction="out" name="Handle" type="u" tp:type="Contact_Handle">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The contact's handle</p>
        </tp:docstring>
      </arg>

      <arg direction="out" type="a{sv}" name="Attributes"
        tp:type="Single_Contact_Attributes_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>All supported attributes of the contact on
            the given interfaces that can be returned without network
            round-trips. If contact attributes are not immediately known, the
            behaviour is defined by the interface; the attribute should either
            be omitted from the result or replaced with a default value.</p>

          <p>The contact's attributes will always include at least the
            identifier that would be obtained by inspecting the handle
            (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
      </tp:possible-errors>
    </method>

    <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.TargetHandleType</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.99.UNRELEASED">(as part of Connection)</tp:added>

      <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 one of the channels 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:member-ref>RequestableChannelClasses</tp:member-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.99.UNRELEASED">(as part of Connection)</tp:added>

      <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 one of the channels 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:member-ref>RequestableChannelClasses</tp:member-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.UNRELEASED"/>

      <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>

    <tp:mapping name="Channel_Class" array-name="Channel_Class_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Mapping representing a class of channels that can be requested
          from a connection manager, can be handled by a user interface,
          are supported by a contact, etc.</p>

        <p>Classes of channel are identified by the fixed values of
          a subset of their properties.</p>

        <p>Channel classes SHOULD always include the keys
          <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>
          and
          <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.</p>
      </tp:docstring>

      <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
        <tp:docstring>
          A D-Bus interface name, followed by a dot and a D-Bus property name.
        </tp:docstring>
      </tp:member>

      <tp:member type="v" name="Value">
        <tp:docstring>
          The value of the property.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:struct name="Requestable_Channel_Class"
      array-name="Requestable_Channel_Class_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Structure representing a class of channels that can be requested,
          identified by a set of properties that identify that class of
          channel.</p>

        <tp:rationale>
          <p>This will often just be the channel type and the handle type,
            but can include other properties of the channel - for instance,
            encrypted channels might require properties that
            unencrypted channels do not, like an encryption key.</p>
        </tp:rationale>

        <p>In some cases, these classes of channel may overlap, in the sense
          that one class fixes all the properties that another class does,
          plus some more properties.</p>

        <tp:rationale>
          <p>For older clients to still be able to understand how to request
            channels in the presence of a hypothetical "encryption" interface,
            we'd need to represent it like this:</p>

          <ul>
            <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
            <li>class 2: Channel.ChannelType = Text,
              Channel.TargetHandleType = CONTACT,
              Encryption.Encrypted = TRUE</li>
          </ul>
        </tp:rationale>
      </tp:docstring>

      <tp:member name="Fixed_Properties" type="a{sv}"
        tp:type="Channel_Class">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The property values that identify this requestable channel class.
            These properties MUST be included in requests for a channel of this
            class, and MUST take these values.</p>

          <p>Clients that do not understand the semantics of all the
            Fixed_Properties MUST NOT request channels of this class, since
            they would be unable to avoid making an incorrect request.</p>

          <p>This implies that connection managers wishing to make channels
            available to old or minimal clients SHOULD have a channel class
            with the minimum number of Fixed_Properties, and MAY additionally
            have channel classes with extra Fixed_Properties.</p>

          <p>Interface designers SHOULD avoid introducing fixed properties
            whose types are not serializable in a <code>.manager</code>
            file.</p>

          <tp:rationale>
            <p>Connection managers with a fixed property that is not
              serializable cannot have a complete <code>.manager</code>
              file.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>

      <tp:member name="Allowed_Properties" type="as"
        tp:type="DBus_Qualified_Member[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties that MAY be set when requesting a channel of this
            channel type and handle type.</p>

          <p>This array MUST NOT include properties that are in the
            Fixed_Properties mapping.</p>

          <p>Properties in this array may either be required or optional,
            according to their documented semantics.</p>

          <tp:rationale>
            <p>For instance, if
              TargetHandleType takes a value that is not Handle_Type_None,
              one or the other of TargetHandle and TargetID is required.
              Clients are expected to understand the documented relationship
              between the properties, so we do not have separate arrays
              of required and optional properties.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="RequestableChannelClasses" access="read"
      type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
      tp:name-for-bindings="Requestable_Channel_Classes">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The classes of channel that are expected to be available on this
          connection, i.e. those for which
          <tp:member-ref>CreateChannel</tp:member-ref> can reasonably
          be expected to succeed. User interfaces can use this information
          to show or hide UI components.</p>

        <p>This property cannot change after the connection has gone to
          state Connection_Status_Connected, so there is no change
          notification (if the connection has context-dependent capabilities,
          it SHOULD advertise support for all classes of channel that it might
          support during its lifetime). Before this state has been reached,
          the value of this property is undefined.</p>

        <tp:rationale>
          <p>This is not on an optional interface, because connection
            managers can always offer some sort of clue about the channel
            classes they expect to support (at worst, they can announce
            support for everything for which they have code).</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This models a connection to a single user account on a communication
        service. Its basic capability is to provide the facility to request and
        receive channels of differing types (such as text channels or streaming
        media channels) which are used to carry out further communication.</p>

      <p>In order to allow Connection objects to be discovered by new clients,
        the object path and well-known bus name MUST be of the form
        <code>/im/telepathy/v1/Connection/cmname/proto/account</code>
        and
        <code>im.telepathy.v1.Connection.cmname.proto.account</code>
        where:</p>

      <ul>
        <li><em>cmname</em> is the same
          <tp:type>Connection_Manager_Name</tp:type> that appears
          in the connection manager's object path and well-known bus name</li>
        <li><em>proto</em> is the <tp:type>Protocol_Name</tp:type> as seen in
          <tp:dbus-ref namespace="imt1.ConnectionManager">Protocols</tp:dbus-ref>,
          but with "-" replaced with "_" to get a valid
          object path/bus name</li>
        <li><em>account</em> is some non-empty sequence of ASCII letters,
          digits and underscores not starting with a digit</li>
      </ul>

      <p><em>account</em> SHOULD be formed such that any valid distinct
        connection instance on this protocol has a distinct name. This
        might be formed by including the server name followed by the user
        name (escaped via some suitable mechanism like telepathy-glib's
        tp_escape_as_identifier() function to preserve uniqueness); on
        protocols where connecting multiple times is permissable, a
        per-connection identifier might be necessary to ensure
        uniqueness.</p>

      <p>Clients MAY parse the object path to determine the connection
        manager name and the protocol, but MUST NOT attempt to parse the
        <em>account</em> part. Connection managers MAY use any unique string
        for this part.</p>

    <p>As well as the methods and signatures below, arbitrary interfaces may be
    provided by the Connection object to represent extra connection-wide
    functionality, such as the Connection.Interface.Presence for
    receiving and
    reporting presence information, and Connection.Interface.Aliasing for
    connections where contacts may set and change an alias for themselves.
    These interfaces can be discovered using the
    <tp:member-ref>Interfaces</tp:member-ref> property.</p>

    <p>Contacts, rooms, and server-stored lists (such as subscribed contacts,
    block lists, or allow lists) on a service are all represented by
    immutable <em>handles</em>, which are unsigned non-zero integers which are
    valid only for the lifetime of the connection object, and are used
    throughout the protocol where these entities are represented, allowing
    simple testing of equality within clients.</p>

    <p>Zero as a handle value is sometimes used as a "null" value to mean
    the absence of a contact, room, etc.</p>

    <p>Handles have per-type uniqueness, meaning that every (handle
    type, handle number) tuple is guaranteed to be unique within a
    connection for the lifetime of the connection and that a handle
    alone (without its type) is meaningless or ambiguous.</p>
    </tp:docstring>

    <tp:changed version="0.17.10">Previously, the account part of
      Connection bus names/object paths was allowed to have more than one
      component (i.e. contain dots or slashes), resulting in Connection
      bus names and object paths with more than 7 components. We now restrict
      Connection bus names/object paths to have exactly 7
      components.</tp:changed>

    <tp:changed version="0.17.23">The Requests and Contacts interfaces
      are now mandatory. Their functionality will be merged into the main
      Connection interface at some point in future.</tp:changed>

    <tp:changed version="0.99.1">All deprecated types, methods,
      and signals have been removed from this interface including
      anything to do with handle reference counting.</tp:changed>

    <tp:changed version="0.99.6">The former Contacts interface
      is now part of Connection.</tp:changed>

    <tp:changed version="0.99.UNRELEASED">The Requests interface
      is now part of Connection.</tp:changed>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->