Interface Connection.Interface.ContactBlocking1

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Contact Attributes | Types

Methods

BlockContacts (au: Contacts, b: Report_Abusive) → nothing
UnblockContacts (au: Contacts) → nothing
RequestBlockedContacts () → a{us}: Contacts

Signals

BlockedContactsChanged (a{us}: Blocked_Contacts, a{us}: Unblocked_Contacts)

Properties

ContactBlockingCapabilities u (Contact_Blocking_Capabilities) Read only Immutable

Contact Attributes

im.telepathy1.Connection.Interface.ContactBlocking1/blocked b

Types

Contact_Blocking_Capabilities Flags u
Added in 0.21.13. Changes from the draft: methods and signals now return Handle_Identifier_Map (a{us}) rather than bare lists of contact handles (au)
Objects implementing this interface must also implement:

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.

Methods

(Permalink)

BlockContacts (au: Contacts, b: Report_Abusive) → nothing

Parameters

  • Contacts — au (Contact_Handle_List)
    • 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.
  • Report_Abusive — b

    • 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.

    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:

    • 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 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.

(Permalink)

UnblockContacts (au: Contacts) → nothing

Parameters

  • Contacts — au (Contact_Handle_List)
    • 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.

Direct the server to unblock some contacts.

(Permalink)

RequestBlockedContacts () → a{us}: Contacts

Returns

  • Contacts — a{us} (Handle_Identifier_Map)
    • The blocked contacts’ handles, together with their identifiers.

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

(Permalink)

BlockedContactsChanged (a{us}: Blocked_Contacts, a{us}: Unblocked_Contacts)

Parameters

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

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

ContactBlockingCapabilities — u (Contact_Blocking_Capabilities)

Read only
This property is immutable which means that it can never change.

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

Attributes that a contact can have, accessed with the im.telepathy1.Connection.Interface.Contacts interface.
(Permalink)

im.telepathy1.Connection.Interface.ContactBlocking1/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

Flags (Permalink)

Contact_Blocking_Capabilities — u

  • Can_Report_Abusive (1)
    • When calling BlockContacts, the contacts may be reporting as abusive to the server administrators by setting Report_Abusive to True.