<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2009–2011 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.ContactBlocking">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
    <tp:added version='0.21.13'>Changes from the draft:
      methods and signals now return <tp:type>Handle_Identifier_Map</tp:type>
      (<code>a{us}</code>) rather than bare lists of contact handles
      (<code>au</code>)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An interface for connections where contacts can be blocked from
        communicating with this user and receiving this user's presence.
        Clients may retrieve a list of currently-blocked contacts using
        <tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for
        <tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified
        when contacts are blocked and unblocked. The
        <tp:member-ref>BlockContacts</tp:member-ref> and
        <tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say
        on the tin; depending on the value of the
        <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property,
        contacts may be reported for spam or other abuse when calling
        <tp:member-ref>BlockContacts</tp:member-ref>.</p>

      <p>This interface is intended for protocols where blocking contacts
        persists on the server between connections; connection managers for
        protocols with no server-side support for blocking contacts MAY choose
        to implement this interface using an on-disk file of blocked
        contacts or some other means to store blocked contacts between
        connections.</p>

      <p>This interface is intended to replace the
        <tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref>
        channel with <tp:dbus-ref
        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
        <code>List</code> and <tp:dbus-ref
        namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code>
        (along with the <tp:dbus-ref
        namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and
        <tp:dbus-ref
        namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref>
        interfaces replacing other channels with <tp:dbus-ref
        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
        <code>List</code> and <tp:dbus-ref
        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
        <code>Group</code>, respectively).</p>
    </tp:docstring>

    <method name="BlockContacts" tp:name-for-bindings="Block_Contacts">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Direct the server to block some contacts. The precise effect is
          protocol-dependent, but SHOULD include ignoring all current and
          subsequent communications from the given contacts, avoiding sending
          presence to them in future, and if they were already receiving the
          local user's presence, behaving as if the local user went
          offline.</p>
      </tp:docstring>

      <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
        <tp:docstring>Some contacts to block. If some of the contacts in this
          list are already blocked, the connection manager MUST act as if they
          were not specified in this list.</tp:docstring>
      </arg>

      <arg name="Report_Abusive" type="b" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>In addition to blocking, report these contacts as abusive to the
            server administrators.</p>

          <p>Clients can determine whether this capability is available by
            checking the
            <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
            property. If this argument is set to <code>True</code> by a client
            despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
            not containing the <code>Can_Report_Abusive</code> flag, the
            connection manager SHOULD act as if it were <code>False</code> and
            simply block the supplied contacts.</p>

          <tp:rationale>
            <p>A correct user interface shouldn't get this far without knowing
              that reporting abusive contacts is not supported. If it does,
              then the user has expressed their intention to block these
              contacts. Returning an error would leave the UI with three
              options:</p>

            <ul>
              <li>Ignore the error, leaving the contacts not actually blocked;</li>
              <li>Display an error to the user;</li>
              <li>Call this method again, passing <code>False</code> for this
              argument.</li>
            </ul>

            <p>None of these seem preferable to the CM just ignoring this flag
              if it doesn't support it: that way, the contacts will be blocked,
              as the user requested, and UIs have fewer ways to mess up
              entirely.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>
    </method>

    <method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Direct the server to unblock some contacts.</p>
      </tp:docstring>

      <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
        <tp:docstring>Some contacts to unblock. If some of the contacts in this
          list are not currently blocked, the connection manager MUST act as if
          they were not specified in this list.</tp:docstring>
      </arg>
    </method>

    <method name="RequestBlockedContacts"
      tp:name-for-bindings="Request_Blocked_Contacts">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>List the contacts that are blocked.</p>

        <p>Clients SHOULD allow a relatively long timeout for calls to this
          method, since on some protocols contact blocking is part of the
          contact list, which can take a significant time to retrieve.</p>
      </tp:docstring>

      <arg name="Contacts" type="a{us}" direction="out"
        tp:type="Handle_Identifier_Map">
        <tp:docstring>The blocked contacts’ handles, together with their
          identifiers.</tp:docstring>
      </arg>
    </method>

    <signal name="BlockedContactsChanged"
      tp:name-for-bindings="Blocked_Contacts_Changed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the list of blocked contacts is first retrieved
          (before returning from any pending calls to
          <tp:member-ref>RequestBlockedContacts</tp:member-ref>), and
          whenever the list of blocked contacts subsequently changes.</p>
      </tp:docstring>

      <arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map">
        <tp:docstring>Contacts added to the result of
          <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
      </arg>

      <arg name="Unblocked_Contacts" type="a{us}"
           tp:type="Handle_Identifier_Map">
        <tp:docstring>Contacts removed from the result of
          <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
      </arg>
    </signal>

    <tp:contact-attribute name="blocked" type="b">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p><code>True</code> if the contact would be in the result of
          <tp:member-ref>RequestBlockedContacts</tp:member-ref>;
          <code>False</code> or omitted if the contact is not blocked, or if it
          is unknown whether the contact is blocked.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <property name="ContactBlockingCapabilities"
              tp:name-for-bindings="Contact_Blocking_Capabilities"
              tp:type="Contact_Blocking_Capabilities" type="u" access="read"
              tp:immutable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Additional capabilities for contact blocking; currently, this is
          limited to whether contacts may be reported as abusive.</p>

        <p>Note that there is no capability for supporting blocking itself:
          the presence of this interface on a <tp:dbus-ref
          namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking
          contacts is supported.</p>
      </tp:docstring>
    </property>

    <tp:flags name="Contact_Blocking_Capabilities" type="u"
              value-prefix="Contact_Blocking_Capability">
      <tp:flag suffix="Can_Report_Abusive" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          When calling <tp:member-ref>BlockContacts</tp:member-ref>, the
          contacts may be reporting as abusive to the server administrators by
          setting <var>Report_Abusive</var> to <code>True</code>.
        </tp:docstring>
      </tp:flag>
    </tp:flags>

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