path: root/spec/Connection_Interface_Contact_List1.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_List1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
      modify it under the terms of the GNU Lesser General Public
      License as published by the Free Software Foundation; either
      version 2.1 of the License, or (at your option) any later version.</p>

    <p>This library is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Lesser General Public License for more details.</p>

    <p>You should have received a copy of the GNU Lesser General Public
      License along with this library; if not, write to the Free Software
      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
      USA.</p>
  </tp:license>
  <interface name="im.telepathy.v1.Connection.Interface.ContactList1">
    <tp:requires interface="im.telepathy.v1.Connection"/>
    <tp:added version="0.21.0">(as stable API)</tp:added>
    <tp:changed version="0.99.1">The deprecated ContactsChanged
      signal has been replaced with the ContactsChangedWithID
      version.</tp:changed>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An interface for connections that have any concept of a list of
        known contacts (roster, buddy list, friends list etc.)</p>

      <tp:rationale>
        <p>On many protocols, there's a server-side roster (as in XMPP),
          or a set of server-side lists that can be combined to form a
          roster (as in MSN).</p>

        <p>In some protocols (like link-local XMPP), while there might not be
          any server or roster, it's possible to list "nearby" contacts.</p>

        <p>In Telepathy 0.20 and older, we represented contact lists as a
          collection of ContactList channels. This is remarkably difficult to
          work with in practice - every client that cares about contact lists
          has to take the union of some hard-to-define set of these
          channels - and conflicts with the idea that channels that cannot
          be dispatched to a handler should be closed.</p>
      </tp:rationale>

      <p>The list of contacts is not exposed as a D-Bus property; it can be
        fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>.
      </p>

      <tp:rationale>
        <p>In some protocols, such as XMPP, the contact list may not be
          available immediately. The
          <tp:member-ref>GetContactListAttributes</tp:member-ref> method
          will fail until the contact list is available.
          Using a method also allows extra attributes to be retrieved at
          the same time.</p>
      </tp:rationale>
    </tp:docstring>

    <tp:enum name="Contact_List_State" type="u">
      <tp:docstring>
        The progress made in retrieving the contact list.
      </tp:docstring>

      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>The connection has not started to retrieve the contact
          list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is
          called in this state, it will raise NotYet.</tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Waiting" value="1">
        <tp:docstring>The connection has started to retrieve the contact
          list, but has not yet succeeded or failed.
          If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called
          in this state, it will raise NotYet.</tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Failure" value="2">
        <tp:docstring>
          <p>The connection has tried and failed to retrieve the contact
            list. If <tp:member-ref>GetContactListAttributes</tp:member-ref>
            is called in this state, it will immediately raise an error
            indicating the reason for failure.</p>

          <p>The connection manager SHOULD try again to obtain the contact
            list, if appropriate for the protocol. If it succeeds later,
            the <tp:member-ref>ContactListState</tp:member-ref> MUST advance
            to Success.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Success" value="3">
        <tp:docstring>The connection has successfully retrieved the contact
          list. If <tp:member-ref>GetContactListAttributes</tp:member-ref>
          is called in this state, it will return successfully.</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <property name="ContactListState" tp:name-for-bindings="Contact_List_State"
      type="u" tp:type="Contact_List_State" access="read">
      <tp:docstring>
        The progress made in retrieving the contact list.
        Change notification is via
        <tp:member-ref>ContactListStateChanged</tp:member-ref>.
      </tp:docstring>
    </property>

    <signal name="ContactListStateChanged"
      tp:name-for-bindings="Contact_List_State_Changed">
      <tp:docstring>
        Emitted when <tp:member-ref>ContactListState</tp:member-ref>
        changes.
      </tp:docstring>

      <arg name="Contact_List_State" type="u" tp:type="Contact_List_State">
        <tp:docstring>
          The new value of <tp:member-ref>ContactListState</tp:member-ref>.
        </tp:docstring>
      </arg>
    </signal>

    <method name="GetContactListAttributes"
      tp:name-for-bindings="Get_Contact_List_Attributes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Return some contact attributes for a list of contacts
          associated with the user. This list MUST include at least:</p>

        <ul>
          <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref>
            attribute is not No</li>
          <li>all contacts whose <tp:token-ref>publish</tp:token-ref>
            attribute is not No</li>
        </ul>

        <p>but MAY contain other contacts.</p>

        <tp:rationale>
          <p>For instance, on XMPP, all contacts on the roster would appear
            here even if they have subscription="none", unless there's
            reason to believe the user does not want to see them (such as
            having been blocked).</p>
        </tp:rationale>

        <p>This list does not need to contain every visible contact: for
          instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
          here. Blocked contacts SHOULD NOT appear here, unless they still
          have a non-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or
          <tp:token-ref>publish</tp:token-ref> attribute
          for some reason.</p>

        <tp:rationale>
          <p>It's reasonable to assume that blocked contacts should not be
            visible to the user unless they specifically go looking for them,
            at least in protocols like XMPP where blocking a contact
            suppresses presence.</p>
        </tp:rationale>
      </tp:docstring>

      <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. Equivalent to the corresponding argument
            to <tp:dbus-ref
              namespace="im.telepathy.v1.Connection"
              >GetContactAttributes</tp:dbus-ref>,
            except that if this list does not contain the ContactList
            interface itself, it is treated as though that interface was also
            requested.</p>
        </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,
            equivalent to the result of <tp:dbus-ref
              namespace="im.telepathy.v1.Connection"
              >GetContactAttributes</tp:dbus-ref>.</p>

        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented"/>
        <tp:error name="im.telepathy.v1.Error.NotAvailable"/>
        <tp:error name="im.telepathy.v1.Error.ServiceBusy"/>
        <tp:error name="im.telepathy.v1.Error.NotYet">
          <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
            <p>The <tp:member-ref>ContactListState</tp:member-ref> is
              None or Waiting. In particular, this error is raised if the
              <tp:dbus-ref namespace="imt1.Connection">Status</tp:dbus-ref>
              is not yet Connection_Status_Connected.</p>
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <tp:enum name="Subscription_State" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>An enumeration indicating whether presence subscription is denied,
          denied but pending permission, or allowed. The exact semantics
          vary according to where this type is used: see the
          <tp:token-ref>subscribe</tp:token-ref> and
          <tp:token-ref>publish</tp:token-ref> contact attributes for
          details.</p>
      </tp:docstring>

      <tp:enumvalue suffix="Unknown" value="0">
        <tp:docstring>The presence subscription state is
          unknown.</tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="No" value="1">
        <tp:docstring>Presence information cannot be seen, and either the
          subscription state Removed_Remotely does not apply, or it is
          not known whether that state applies.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Removed_Remotely" value="2">
        <tp:docstring>Presence information cannot be seen because the
          remote contact took action: either the local user's request to
          see the remote contact's presence was denied, or the remote
          contact requested to see the local user's presence but then
          cancelled their request.</tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Ask" value="3">
        <tp:docstring>Presence information cannot be seen. Permission
          to see presence information has been requested, and the request
          has not yet been declined or accepted.</tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Yes" value="4">
        <tp:docstring>Presence information can be seen.</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:contact-attribute name="subscribe"
      type="u" tp:type="Subscription_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If this attribute on a contact is Yes, this connection can
          expect to receive their presence, along with any other information
          that has the same access control.</p>

        <tp:rationale>
          <p>This is subscription="from" or subscription="both" in XMPP,
            the "forward list" on MSN, or the contact being "added to
            the local user's buddy list" in ICQ, for example.</p>
        </tp:rationale>

        <p>If this attribute is not Yes, the local user cannot generally
          expect to receive presence from this contact. Their <tp:token-ref
            namespace="im.telepathy.v1.Connection.Interface.Presence1">presence</tp:token-ref>
          contact attribute is likely to be (Unknown, "unknown", ""), unless the
          local user can temporarily see their presence for some other reason
          (for instance, on XMPP, contacts seen in chatrooms will temporarily
          have available presence).</p>

        <p>If this attribute is Ask, this indicates that the local user has
          asked to receive the contact's presence at some time. It is
          implementation-dependent whether contacts' subscribe attributes
          can remain set to Ask, or are reset to No, when the connection
          disconnects.</p>

        <tp:rationale>
          <p>Some protocols store the fact that we wishes to see a contact's
            presence; on these protocols, this attribute can remain Ask
            indefinitely. On other protocols, only contacts who have been
            asked during the current session will ever have Ask status.</p>
        </tp:rationale>

        <p>If this attribute is Removed_Remotely, this indicates that the
          local user has asked to receive the contact's presence at some time,
          but the remote contact has rejected that request, and a local
          user interface has not yet acknowledged this. It is
          implementation-dependent whether contacts' subscribe attributes can
          remain set to Removed_Remotely, or are reset to No, when the
          connection disconnects.</p>

        <p>After notifying the user, user interfaces MAY acknowledge a change
          to <tt>subscribe</tt>=Removed_Remotely by calling either
          <tp:member-ref>Unsubscribe</tp:member-ref> or
          <tp:member-ref>RemoveContacts</tp:member-ref>, which will set
          <tt>subscribe</tt> to No (and perhaps remove the contact). This
          allows user interfaces to detect that the user has been notified
          about the rejected request.</p>

        <p>This attribute's value will be Unknown or omitted until the
          <tp:member-ref>ContactListState</tp:member-ref> has changed to
          Success.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <tp:contact-attribute name="publish"
      type="u" tp:type="Subscription_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If this attribute on a contact is Yes, the local user's presence
          is published to that contact, along with any other information that
          shares an access-control mechanism with presence (depending on
          protocol, server configuration and/or user configuration, this may
          include avatars, "rich presence" such as location, etc.).</p>

        <tp:rationale>
          <p>This is subscription="to" or subscription="both" in XMPP,
            the "reverse list" on MSN, or the state of "being added to
            the contact's buddy list" in ICQ, for example.</p>
        </tp:rationale>

        <p>If this attribute is not Yes, the
          local user's presence is not published to that contact; however,
          if it is Ask, the contact has requested that the local user's
          presence is made available to them.</p>

        <p>It is implementation-dependent whether contacts' <tt>publish</tt>
          attributes can remain set to Ask, or are reset to No, when the
          connection disconnects.</p>

        <tp:rationale>
          <p>Some protocols store the fact that a contact wishes to see our
            presence; on these protocols, this attribute can remain Ask
            indefinitely. On other protocols, only contacts who have asked
            during the current session will ever have Ask status.</p>
        </tp:rationale>

        <p>If this attribute is Removed_Remotely, this indicates that the
          remote contact has asked to receive the user's presence at some time,
          but has then cancelled that request before a response was given by
          the local user. User interfaces MAY reset <tt>publish</tt> from
          Removed_Remotely to No, by calling either
          <tp:member-ref>Unpublish</tp:member-ref> or
          <tp:member-ref>RemoveContacts</tp:member-ref>.</p>

        <p>If multiple factors affect whether a contact can receive the local
          user's presence, this attribute SHOULD reflect the overall
          result. For instance, an XMPP contact with subscription="to" or
          subscription="both", but who has been blocked via
          <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy
            Lists</a>, SHOULD have publish=No.</p>

        <p>This attribute's value will be Unknown or omitted until the
          <tp:member-ref>ContactListState</tp:member-ref> has changed to
          Success.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <tp:contact-attribute name="publish-request" type="s">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If the <tp:token-ref>publish</tp:token-ref> attribute is Ask, an
          optional message that was sent by the contact asking to receive the
          local user's presence; omitted if none was given.</p>

        <tp:rationale>
          <p>If the contact asking to receive our presence is also using
            Telepathy, this is the message they supplied as the Message
            argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p>
        </tp:rationale>

        <p>Otherwise, this SHOULD be omitted.</p>

        <p>This attribute will also be omitted until the
          <tp:member-ref>ContactListState</tp:member-ref> has changed to
          Success.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <property name="ContactListPersists"
      tp:name-for-bindings="Contact_List_Persists" type="b" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, presence subscriptions (in both directions) on this
          connection are stored by the server or other infrastructure.</p>

        <tp:rationale>
          <p>XMPP, MSN, ICQ, etc. all behave like this.</p>
        </tp:rationale>

        <p>If false, presence subscriptions on this connection are not
          stored.</p>

        <tp:rationale>
          <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record
            of subscriptions, as described below. In link-local XMPP,
            subscriptions are implicit (everyone on the local network receives
            presence from everyone else) so nothing is ever stored.</p>
        </tp:rationale>

        <p>If <tp:member-ref>CanChangeContactList</tp:member-ref>
          is true, Telepathy clients (e.g. user interfaces or address books)
          MAY keep a record of permission to publish and requests to subscribe
          locally, and attempt to restore it for each Connection. If
          ContactListPersists is false, clients MAY do this for all contacts;
          if ContactListPersists is true, clients SHOULD NOT change the state
          of contacts that were not changed locally.</p>

        <tp:rationale>
          <p>In SIMPLE (SIP), ContactListPersists is false, but
            CanChangeContactList is true. Presence will not be received
            unless clients renew any subscriptions they have for each
            connection, in the way described. There is no server-side storage,
            so clients have no alternative but to maintain independent contact
            lists.</p>

          <p>In protocols like XMPP and MSN, it may be useful for clients to
            queue up subscription requests or removals made while offline and
            process them next time the connection is online. However, clients
            should only replay the changes, rather than resetting the contact
            list to match a stored copy, to avoid overwriting changes that
            were made on the server.</p>
        </tp:rationale>

        <p>Clients that replay requests like this SHOULD do so by calling
          AuthorizePublication to pre-approve publication of presence to the
          appropriate contacts, followed by RequestSubscription to request the
          appropriate contacts' presences.</p>

        <p>This property cannot change after the connection has moved to the
          Connected state. Until then, its value is undefined, and it may
          change at any time, without notification.</p>
      </tp:docstring>
    </property>

    <tp:enum name="Contact_Metadata_Storage_Type" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Values of this enumeration indicate the extent to which metadata
          such as aliases and group memberships can be stored for the contacts
          on a particular connection.</p>

        <p>On some protocols, certain metadata (for instance, contact aliases)
          can only be stored for contacts on the contact list, or contacts
          with a particular contact list state.</p>

        <p>To make it easier to deal with such protocols, if clients set
          metadata on a contact who is not in the required state, the
          Connection MUST cache the metadata for the duration of the session.
          If clients request the attributes of that contact after the
          appropriate "set" method has returned successfully, the Connection
          MUST return the new (cached) value.</p>

        <p>If the contact is later placed in the required state to store
          metadata (for instance, if subscription to the contact's presence
          is requested, on a protocol like MSN where the alias has storage type
          Subscribed_Or_Pending), the connection MUST store the cached
          metadata at that time.</p>

        <tp:rationale>
          <p>If the Connection didn't cache changes in this way, a client
            intending to change the alias on MSN would have to wait until
            the server acknowledged the subscription request; in the meantime,
            other clients would still display the old alias.</p>
        </tp:rationale>

        <p>The only exception to that general rule is that if the Connection
          cannot store particular metadata at all (i.e. the
          storage type is None), it MUST reject attempts to set it.</p>

        <tp:rationale>
          <p>If the implementation knows that metadata can't be stored at
            all, it's useful to report that, which can be done
            synchronously. In general, user interfaces should detect
            storage type None and not display editing controls at all.</p>
        </tp:rationale>
      </tp:docstring>

      <tp:enumvalue suffix="None" value="0">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>This connection cannot store this type of metadata at all, and
            attempting to do so will fail with NotImplemented.</p>

          <tp:rationale>
            <p>Link-local XMPP can't store aliases or group memberships at
              all, and subscription and presence states are implicit (all
              contacts on the local network have subscribe = publish = Yes
              and no other contacts exist).</p>

            <p>As of April 2010, the XMPP server for Facebook Chat provides a
              read-only view of the user's Facebook contacts, so it could also
              usefully have this storage type.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Subscribed_Or_Pending" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>This type of metadata can only be stored permanently for contacts
            whose subscribe attribute is Ask or Yes.</p>

          <tp:rationale>
            <p>Contact aliases and groups on MSN have this behaviour.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Subscribed" value="2">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>This type of metadata can only be stored permanently for contacts
            whose subscribe attribute is Yes.</p>

          <tp:rationale>
            <p>No service with this behaviour is currently known, but it's a
              stricter form of Subscribed_Or_Pending.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Anyone" value="3">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The user can set this metadata for any valid contact identifier,
            whether or not they have any presence subscription relationship
            to it, and it will be stored on their contact list.</p>

          <tp:rationale>
            <p>Contact aliases and groups on XMPP have this behaviour; it
              is possible to put a contact in a group, or assign an alias
              to them, without requesting that presence be shared.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:struct name="Contact_Subscriptions" array-name="">
      <tp:docstring>
        A single contact's subscribe, publish and publish-request attributes.
      </tp:docstring>

      <tp:member name="Subscribe" type="u" tp:type="Subscription_State">
        <tp:docstring>
          The new value of the contact's "subscribe" attribute.
        </tp:docstring>
      </tp:member>

      <tp:member name="Publish" type="u" tp:type="Subscription_State">
        <tp:docstring>
          The new value of the contact's "publish" attribute.
        </tp:docstring>
      </tp:member>

      <tp:member name="Publish_Request" type="s">
        <tp:docstring>
          The new value of the contact's "publish-request" attribute,
          or the empty string if that attribute would be omitted.
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <tp:mapping name="Contact_Subscription_Map" array-name="">
      <tp:docstring>
        A map from contacts to their subscribe, publish and publish-request
        attributes.
      </tp:docstring>

      <tp:member name="Contact" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The contact's handle.
        </tp:docstring>
      </tp:member>

      <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions">
        <tp:docstring>
          The contact's subscribe, publish and publish-request attributes.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <signal name="ContactsChanged"
      tp:name-for-bindings="Contacts_Changed">
      <tp:added version="0.21.8"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the contact list becomes available, when contacts'
          basic stored properties change, when new contacts are added to the
          list that would be returned by
          <tp:member-ref>GetContactListAttributes</tp:member-ref>,
          or when contacts are removed from that list.</p>

        <tp:rationale>
          <p>This provides change notification for that list, and for
            contacts' <tp:token-ref>subscribe</tp:token-ref>,
            <tp:token-ref>publish</tp:token-ref> and
            <tp:token-ref>publish-request</tp:token-ref> attributes.</p>
        </tp:rationale>

        <p>Connection managers SHOULD also emit this signal when a contact
          requests that the user's presence is published to them, even if
          that contact's <tp:token>publish</tp:token> attribute is already
          Ask and the <tp:token>publish-request</tp:token> has not changed.</p>

        <tp:rationale>
          <p>If the same contact sends 10 identical requests, 10 identical
            signals should be emitted.</p>
        </tp:rationale>
      </tp:docstring>

      <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
        <tp:docstring>
          The new <tp:token-ref>subscribe</tp:token-ref>,
            <tp:token-ref>publish</tp:token-ref> and
            <tp:token-ref>publish-request</tp:token-ref> attributes of all the
          contacts that have been added, and all the contacts for which those
          attributes have changed.
        </tp:docstring>
      </arg>

      <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The identifiers of the contacts in the <var>Changes</var> map.
        </tp:docstring>
      </arg>

      <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The contacts that have been removed from the list that would be
          returned by
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.
          This also implies that they have subscribe = No and publish = No;
          contacts MUST NOT be listed both here and in <var>Changes</var>.
        </tp:docstring>
      </arg>
    </signal>

    <property name="CanChangeContactList" type="b" access="read"
      tp:name-for-bindings="Can_Change_Contact_List">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, presence subscription and publication can be changed
          using the
          <tp:member-ref>RequestSubscription</tp:member-ref>,
          <tp:member-ref>AuthorizePublication</tp:member-ref> and
          <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p>

        <p>If false, all of those methods will always fail; they SHOULD raise
          the error im.telepathy.v1.Error.NotImplemented.</p>

        <tp:rationale>
          <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is
            implicitly published to everyone in the local subnet, so the user
            cannot control their presence publication.</p>
        </tp:rationale>

        <p>This property cannot change after the connection has moved to the
          Connected state. Until then, its value is undefined, and it may
          change at any time, without notification.</p>
      </tp:docstring>
    </property>

    <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that the given contacts allow the local user to
          subscribe to their presence, i.e. that their subscribe attribute
          becomes Yes.</p>

        <p>Connection managers SHOULD NOT attempt to enforce a
          mutual-subscription policy (i.e. when this method is called, they
          should not automatically allow the contacts to see the local user's
          presence). User interfaces that require mutual subscription
          MAY call <tp:member-ref>AuthorizePublication</tp:member-ref>
          at the same time as this method.</p>

        <tp:rationale>
          <p>Whether to enforce mutual subscription is a matter of policy,
            so it is left to the user interface and/or the server.</p>
        </tp:rationale>

        <p>Before calling this method on a connection where <tp:dbus-ref
            namespace="im.telepathy.v1.Connection.Interface.Aliasing1"
            >AliasFlags</tp:dbus-ref> property has the <code>User_Set</code>
          flag, user interfaces SHOULD obtain, from the user, an alias to
          identify the contact in future, and store it using <tp:dbus-ref
            namespace="im.telepathy.v1.Connection.Interface.Aliasing1"
            >SetAliases</tp:dbus-ref>.</p>

        <p>The user MAY be
          prompted using the contact's current self-assigned nickname, or
          something derived from the contact's (presumably self-assigned)
          identifier, as a default, but these names chosen by the contact
          SHOULD NOT be used without user approval.</p>

        <tp:rationale>
          <p>This is a generalization of
            <a href="http://xmpp.org/extensions/xep-0165.html"
              >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>)
            to protocols other than XMPP. A reasonable user interface for
            this, as used in many XMPP clients, is to have a text entry
            for the alias adjacent to the text entry for the identifier
            to add.</p>
        </tp:rationale>

        <p>For contacts with subscribe=Yes, this method has no effect.
          It MUST return successfully if all contacts are in this state.</p>

        <p>For contacts with subscribe=Ask, this method SHOULD send a new
          request, with the given message, if allowed by the underlying
          protocol.</p>

        <p>For contacts with subscribe=No or subscribe=Rejected, this method
          SHOULD request that the contact allows the local user to subscribe
          to their presence; in general, this will change their publish
          attribute to Ask (although it could change directly to Yes in some
          situations).</p>

        <p>Any state changes that immediately result from this request MUST
          be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
          before this method returns.</p>

        <tp:rationale>
          <p>This makes it easy for user interfaces to see what practical
            effect this method had.</p>
        </tp:rationale>

        <p>If the remote contact accepts the request, their subscribe
          attribute will later change from Ask to Yes.</p>

        <p>If the remote contact explicitly rejects the request (in protocols
          that allow this), their subscribe attribute will later change from
          Ask to Rejected.</p>

        <p>If the subscription request is cancelled by the local user, the
          contact's subscribe attribute will change from Ask to No.</p>

        <p>This method SHOULD NOT be called until the
          <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
          If the <tp:member-ref>ContactListState</tp:member-ref> changes to
          Failure, this method SHOULD raise the same error as
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
      </tp:docstring>

      <arg name="Contacts" direction="in"
        type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>One or more contacts to whom requests are to be sent.</p>
        </tp:docstring>
      </arg>

      <arg name="Message" type="s" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>An optional plain-text message from the user, to send to those
            contacts with the subscription request. The
            <tp:member-ref>RequestUsesMessage</tp:member-ref> property
            indicates whether this message will be used or ignored.</p>

          <p>Clients SHOULD NOT send a non-empty message without first giving
            the user an opportunity to edit it.</p>

          <tp:rationale>
            <p>These messages are typically presented to the remote contact
              as if the user had typed them, so as a minimum, the user should be
              allowed to see what the UI will be saying on their behalf.</p>
          </tp:rationale>

          <p>Connections where this message is not useful MUST still allow it to
            be non-empty.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotYet">
          <tp:docstring>
            The <tp:member-ref>ContactListState</tp:member-ref> is None
            or Waiting.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action, because
            <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <property name="RequestUsesMessage" type="b" access="read"
      tp:name-for-bindings="Request_Uses_Message">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, the Message parameter to
          <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be
          significant, and user interfaces SHOULD prompt the user for a
          message to send with the request; a message such as "I would like
          to add you to my contact list", translated into the local user's
          language, might make a suitable default.</p>

        <tp:rationale>
          <p>This matches user expectations in XMPP and ICQ, for instance.</p>
        </tp:rationale>

        <p>If false, the parameter is ignored; user interfaces SHOULD avoid
          prompting the user, and SHOULD pass an empty string to
          RequestSubscription.</p>

        <tp:rationale>
          <p><em>FIXME: is there any such protocol?</em></p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="DownloadAtConnection" type="b" access="read"
      tp:name-for-bindings="Download_At_Connection"
      tp:is-connection-parameter='yes'>
      <tp:added version="0.25.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, the contact list is automatically downloaded at
          connection. If false, the contact list is only downloaded
          when requested explicitely with
          <tp:member-ref>Download</tp:member-ref>.</p>

        <tp:rationale>
          <p>Downloading the contact list uses bandwidth and is not always
            necessary or desired. For example, a client could cache the
            contact list from previous connections and accept less regular
            updates, it could get the contact list from an out-of-band
            protocol-specific way, or it could not need the contact list at
            all.</p>
        </tp:rationale>

        <p>Connection managers MUST default to true.</p>

        <tp:rationale>
          <p>If a connection manager starts supporting this property but
            defaults to false, it would break all existing clients that don't
            call <tp:member-ref>Download</tp:member-ref>.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <method name="AuthorizePublication"
      tp:name-for-bindings="Authorize_Publication">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>For each of the given contacts, request that the local user's
          presence is sent to that contact, i.e. that their publish attribute
          becomes Yes.</p>

        <p>Connection managers SHOULD NOT attempt to enforce a
          mutual-subscription policy (i.e. when this method is called, they
          should not automatically request that the contacts allow the user to
          subscribe to their presence). User interfaces that require mutual
          subscription MAY call
          <tp:member-ref>RequestSubscription</tp:member-ref> at the same time
          as this method.</p>

        <tp:rationale>
          <p>Whether to enforce mutual subscription is a matter of policy,
            so it is left to the user interface and/or the server.</p>
        </tp:rationale>

        <p>For contacts with publish=Yes, this method has no effect; it
          MUST return successfully if all contacts given have this state.</p>

        <p>For contacts with publish=Ask, this method accepts the
          contact's request to see the local user's presence, changing
          their publish attribute from Ask to Yes.</p>

        <p>For contacts with publish=No, if the protocol allows it, this
          method allows the contacts to see the local user's presence even
          though they have not requested it, changing their publish attribute
          from No to Yes. Otherwise, it merely records the fact that
          presence publication to those contacts is allowed; if any of
          those contacts ask to receive the local user's presence
          later in the lifetime of the connection, the connection SHOULD
          immediately allow them to do so, changing their publish
          attribute directly from No to Yes.</p>

        <tp:rationale>
          <p>This makes it easy to implement the common UI policy that if
            the user attempts to subscribe to a contact's presence, requests
            for reciprocal subscription are automatically approved.</p>
        </tp:rationale>

        <p>Any state changes that immediately result from this request MUST
          be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
          before this method returns.</p>

        <tp:rationale>
          <p>This makes it easy for user interfaces to see what practical
            effect this method had.</p>
        </tp:rationale>

        <p>This method SHOULD NOT be called until the
          <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
          If the <tp:member-ref>ContactListState</tp:member-ref> changes to
          Failure, this method SHOULD raise the same error as
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
      </tp:docstring>

      <arg name="Contacts" direction="in"
        type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>One or more contacts to authorize.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action, because
            <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotYet">
          <tp:docstring>
            The <tp:member-ref>ContactListState</tp:member-ref> is None
            or Waiting.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Remove the given contacts from the contact list entirely. It is
          protocol-dependent whether this works, and under which
          circumstances.</p>

        <p>If possible, this method SHOULD set the contacts' subscribe and
          publish attributes to No, remove any stored aliases for those
          contacts, and remove the contacts from the result of
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>

        <p>This method SHOULD succeed even if it was not possible to carry out
          the request entirely or for all contacts (for instance, if there is an
          outstanding request to subscribe to the contact's presence, and it's
          not possible to cancel such requests). However, all signals that
          immediately result from this method call MUST be emitted before it
          returns, so that clients can interpret the result.</p>

        <tp:rationale>
          <p>User interfaces removing a contact from the contact list are
            unlikely to want spurious failure notifications resulting from
            limitations of a particular protocol. However, emitting the
            signals first means that if a client does want to check exactly
            what happened, it can wait for the method to return (while
            applying change-notification signals to its local cache of the
            contact list's state), then consult its local cache of the
            contact list's state to see whether the contact is still there.</p>
        </tp:rationale>

        <p>This method SHOULD NOT be called until the
          <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
          If the <tp:member-ref>ContactListState</tp:member-ref> changes to
          Failure, this method SHOULD raise the same error as
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
      </tp:docstring>

      <arg name="Contacts" direction="in"
        type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>One or more contacts to remove.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotYet">
          <tp:docstring>
            The <tp:member-ref>ContactListState</tp:member-ref> is None
            or Waiting.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Attempt to set the given contacts' subscribe attribute to No,
          i.e. stop receiving their presence.</p>

        <p>For contacts with subscribe=Ask, this attempts to cancel
          an earlier request to subscribe to the contact's presence; for
          contacts with subscribe=Yes, this attempts to
          unsubscribe from the contact's presence.</p>

        <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
          SHOULD succeed even if it was not possible to carry out the request
          entirely or for all contacts; however, all signals that
          immediately result from this method call MUST be emitted before it
          returns.</p>

        <p>This method SHOULD NOT be called until the
          <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
          If the <tp:member-ref>ContactListState</tp:member-ref> changes to
          Failure, this method SHOULD raise the same error as
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
      </tp:docstring>

      <arg name="Contacts" direction="in"
        type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>One or more contacts to remove.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Unpublish" tp:name-for-bindings="Unpublish">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Attempt to set the given contacts' publish attribute to No,
          i.e. stop sending presence to them.</p>

        <p>For contacts with publish=Ask, this method explicitly rejects the
          contact's request to subscribe to the user's presence; for
          contacts with publish=Yes, this method attempts to prevent the
          user's presence from being received by the contact.</p>

        <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
          SHOULD succeed even if it was not possible to carry out the request
          entirely or for all contacts; however, all signals that
          immediately result from this method call MUST be emitted before it
          returns.</p>

        <p>This method SHOULD NOT be called until the
          <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
          If the <tp:member-ref>ContactListState</tp:member-ref> changes to
          Failure, this method SHOULD raise the same error as
          <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
      </tp:docstring>

      <arg name="Contacts" direction="in"
        type="au" tp:type="Contact_Handle[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>One or more contacts to remove.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.NotYet">
          <tp:docstring>
            The <tp:member-ref>ContactListState</tp:member-ref> is None
            or Waiting.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Download" tp:name-for-bindings="Download">
      <tp:added version="0.25.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Download the contact list from the server. If
          <tp:member-ref>DownloadAtConnection</tp:member-ref> is true,
          Download does nothing.</p>
      </tp:docstring>

      <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:possible-errors>
    </method>

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