path: root/spec/Connection_Interface_Contact_List.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_List" 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="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"
    tp:causes-havoc="experimental">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:added version="0.19.6">(draft 1)</tp:added>

    <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.18 and older, we represented contact lists as a
          collection of <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type"
            >ContactList</tp:dbus-ref> 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 wait until the contact list is available before returning.
          Using a method also allows extra attributes to be retrieved at
          the same time.</p>
      </tp:rationale>
    </tp:docstring>

    <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 somehow
          associated with the user.</p>

        <p>This definition is deliberately vague: in practice, most user
          interfaces should display some subset of this list, by filtering it
          by some contact attributes (for instance, displaying all contacts
          whose "subscribe" attribute is Yes is expected to be a common case).
          This list MAY contain any contacts whatsoever, but MUST contain
          at least the following:</p>

        <ul>
          <li>all contacts whose "subscribe" attribute is Ask or Yes</li>
          <li>all contacts whose "publish" attribute is Ask or Yes</li>
          <li>all contacts with a persistently-stored stored alias, if
            supported</li>
          <li>all contacts in user-defined contact groups, if supported</li>
        </ul>

        <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 either, unless they
          are still stored in a persistent roster/contact list as well as
          being blocked.</p>

        <tp:rationale>
          <p>This is basically the union of the historical <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type"
              >ContactList</tp:dbus-ref> subscribe, publish and stored
            channels.</p>

          <p>For example, XMPP, it's the roster; on link-local XMPP, it's the
            set of visible users on the local network; on MSN, it's the union
            of the forward and reverse buddy lists.</p>

          <p>An easy way for an application to display a contact list is to
            call this method with at least this interface in the Interfaces
            argument, then check which subset of contacts should be displayed
            (perhaps based on their subscribe attribute, for instance) and display
            them. Any additional information required to display the contact
            list, like aliases or presence, can be retrieved at the same
            time.</p>

          <p>In practice, most user interfaces for the contact list will
            usually display a large proportion of this list
            (for instance, most contacts on the contact list will usually
            have subscribe=Yes in practice, so contact lists that display
            subscribe=Yes contacts need to display almost the entire list),
            so the overhead of returning information about too many contacts
            is small.</p>
        </tp:rationale>

        <p>This method SHOULD NOT return before the contact list has been
          retrieved, on protocols where this is possible. As a result,
          clients SHOULD use a longer-than-default timeout for this method
          call, since retrieving the contact list can take a significant
          time on some servers.</p>

        <tp:rationale>
          <p>This makes it possible for clients to wait for the contact list.
            For instance, on XMPP this method shouldn't return until the
            roster has been retrieved, which is an asynchronous process.
            However, on link-local XMPP you can't know when you have the
            complete list, so this method would have to return immediately.</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="org.freedesktop.Telepathy.Connection.Interface.Contacts"
              >GetContactAttributes</tp:dbus-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="Hold" type="b">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Whether to hold the handles on behalf of the calling process.
            Equivalent to the corresponding argument to <tp:dbus-ref 
              namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
              >GetContactAttributes</tp:dbus-ref>.</p>

          <p><em>FIXME: if we do distributed refcounting, we should probably
              rename this to 'Reference' and implement handle-refcounting
              semantics first? On the other hand, if we make handles persist
              for the lifetime of the connection, we can just remove this
              parameter.</em></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="org.freedesktop.Telepathy.Connection.Interface.Contacts"
              >GetContactAttributes</tp:dbus-ref>.</p>

        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
      </tp:possible-errors>
    </method>

    <tp:enum name="Presence_State" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A tristate indicating whether presence subscription is denied,
          denied but pending permission, or allowed. The exact semantics
          vary according to where this type is used.</p>
      </tp:docstring>

      <tp:enumvalue suffix="No" value="0">
        <tp:docstring>Presence information cannot be seen.</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Ask" value="1">
        <tp:docstring>Presence information cannot be seen, but permission
          to see presence information has been requested.</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Yes" value="2">
        <tp:docstring>Presence information can be seen.</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:contact-attribute name="subscribe"
      type="u" tp:type="Presence_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 No or Ask, the local user cannot generally
          expect to receive presence from this contact. Their presence status
          as returned by <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
          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>
      </tp:docstring>
    </tp:contact-attribute>

    <tp:contact-attribute name="publish"
      type="u" tp:type="Presence_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 No or Ask, 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' publish
          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>
      </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 "publish" 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>
      </tp:docstring>
    </tp:contact-attribute>

    <property name="SubscriptionsPersist"
      tp:name-for-bindings="Subscriptions_Persist" 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>CanChangeSubscriptions</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
          SubscriptionsPersist is false, clients MAY do this for all contacts;
          if SubscriptionsPersist is true, clients SHOULD NOT change the state
          of contacts that were not changed locally.</p>

        <tp:rationale>
          <p>In SIMPLE (SIP), SubscriptionsPersist is false, but
            CanChangeSubscriptions 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>
        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.
      </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>

          <p>If this type of metadata is set on a contact with subscribe=No,
            the Connection MUST cache it until disconnected, and return it
            if requested. If subscription to the contact's presence is
            subsequently requested, making it possible to store this metadata,
            the Connection MUST store the cached value at that time.</p>

          <tp:rationale>
            <p>This supports the recommended calling pattern for adding a
              new contact, in which alias and groups are set (without
              necessarily waiting for a reply) before requesting the
              contact's presence. Until the subscription request is
              processed by the server, the alias and groups will be cached
              in memory; when the subscription request has been processed,
              the connection manager will store the metadata on the server.</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>

          <p>If this type of metadata is set on a contact with subscribe != Yes,
            the Connection MUST cache it until disconnected, and return it
            if requested. If subscription to the contact's presence is
            subsequently allowed, making it possible to store this metadata,
            the Connection MUST store the cached value at that time.</p>

          <tp:rationale>
            <p>The same rationale applies as for Subscribed_Or_Pending,
              except that metadata must be stored until the subscription
              request is not only processed by the server, but also allowed
              by the remote user.</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="Presence_State">
        <tp:docstring>
          The new value of the contact's "subscribe" attribute.
        </tp:docstring>
      </tp:member>

      <tp:member name="Publish" type="u" tp:type="Presence_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: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 contact are removed from that list.</p>

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

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

      <arg name="Removals" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          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 Changes.
        </tp:docstring>
      </arg>
    </signal>

    <property name="CanChangeSubscriptions" type="b" access="read"
      tp:name-for-bindings="Can_Change_Subscriptions">
      <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 org.freedesktop.Telepathy.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>Before calling this method on a connection where <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
            >GetAliasFlags</tp:dbus-ref> returns 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="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
            >SetAliases</tp:dbus-ref>.
          
          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, this method SHOULD request that
          the contact allows the local user to subscribe to their presence;
          in general, this will change their publish attribute from No
          to Ask (although it could change directly from No 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; if they explicitly
          reject the request (in protocols that allow this), their subscribe
          attribute will later change from Ask to No.</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="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action, because
            <tp:member-ref>CanChangeSubscriptions</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>

    <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>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>
      </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="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action, because
            <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
          </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>
      </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="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
          </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>
      </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="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeSubscriptions</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>
      </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="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            It was not possible to perform the requested action because
            <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

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