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.

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.

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.

Changes from the draft: methods and signals now return Handle_Identifier_Map (a{us}) rather than bare lists of contact handles (au)

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 RequestBlockedContacts, and listen for BlockedContactsChanged to be notified when contacts are blocked and unblocked. The BlockContacts and UnblockContacts methods do what they say on the tin; depending on the value of the ContactBlockingCapabilities property, contacts may be reported for spam or other abuse when calling BlockContacts.

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.

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.

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.

In addition to blocking, report these contacts as abusive to the server administrators.

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

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:

Ignore the error, leaving the contacts not actually blocked;
Display an error to the user;
Call this method again, passing False for this argument.

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.

Direct the server to unblock some contacts.

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.

List the contacts that are blocked.

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.

The blocked contacts’ handles, together with their identifiers.

Emitted when the list of blocked contacts is first retrieved (before returning from any pending calls to RequestBlockedContacts), and whenever the list of blocked contacts subsequently changes.

Contacts added to the result of RequestBlockedContacts. Contacts removed from the result of RequestBlockedContacts.

True if the contact would be in the result of RequestBlockedContacts; False or omitted if the contact is not blocked, or if it is unknown whether the contact is blocked.

Additional capabilities for contact blocking; currently, this is limited to whether contacts may be reported as abusive.

Note that there is no capability for supporting blocking itself: the presence of this interface on a Connection indicates that blocking contacts is supported.

When calling BlockContacts, the contacts may be reporting as abusive to the server administrators by setting Report_Abusive to True.