Methods
| BlockContacts | (au: Contacts, b: Report_Abusive) | → | nothing | |
| UnblockContacts | (au: Contacts) | → | nothing | |
| RequestBlockedContacts | () | → | au: Contacts |
Signals
| BlockedContactsChanged | (au: Blocked_Contacts, au: Unblocked_Contacts) |
Properties
| ContactBlockingCapabilities | u (Contact_Blocking_Capabilities) | Read only | Immutable |
Contact Attributes
| org.freedesktop.Telepathy.Connection.Interface.ContactBlocking.DRAFT/blocked | b |
Types
| Contact_Blocking_Capabilities | Flags | u |
Description
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.
When this interface becomes stable, it will replace the ContactList channel with TargetHandleType Handle_Type_List and TargetID 'deny'.
Methods
BlockContacts (au: Contacts, b: Report_Abusive) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
- Report_Abusive — b
- Ignore the error, leaving the contacts not actually blocked;
- Display an error to the user;
- Call this method again, passing
Falsefor this argument.
In addition to blocking, report these contacts as abusive to the server administrators.
Rationale:
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.
Rationale:
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:
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 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.
UnblockContacts (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
Direct the server to unblock some contacts.
RequestBlockedContacts () → au: Contacts
Returns
- Contacts — au (Contact_Handle_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.
Signals
BlockedContactsChanged (au: Blocked_Contacts, au: Unblocked_Contacts)
Parameters
- Blocked_Contacts — au (Contact_Handle_List)
- Unblocked_Contacts — au (Contact_Handle_List)
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.
Properties
ContactBlockingCapabilities — u (Contact_Blocking_Capabilities)
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.
Contact Attributes
org.freedesktop.Telepathy.Connection.Interface.ContactBlocking.DRAFT/blocked — b
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.
Types
Contact_Blocking_Capabilities — u
- Can_Report_Abusive (1)
True.