Interface Connection.Interface.CommunicationPolicy.DRAFT

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

Methods

SetPolicy (s: Channel_Type, u: Policy) → nothing

Signals

PolicyChanged (a{su}: Changed_Policies)

Properties

SupportedPolicies a(asau) (Supported_Policy_List) Read only
ActivePolicies a{su} (Active_Policies_Map) Read only

Types

Access_Control_Type Enum u
Active_Policies_Map Mapping a{su}
Supported_Policy Struct (asau)
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.

Description

This interface supports controlling which contacts are allowed to initiate text chats, incoming calls, and other forms of communication as supported by the underlying protocol. The policies supported for different communication methods on this connection are listed in the SupportedPolicies property. The current configuration is held in ActivePolicies; it can be modified using SetPolicy, and changes are signalled by PolicyChanged.

Methods

(Permalink)

SetPolicy (s: Channel_Type, u: Policy) → nothing

Parameters

Set a policy for a communication method (channel type). Depending on the server or protocol, more than one communication method could be bound to the same policy, if calling this method on one channel type changes the policy on another channel type, the PolicyChanged signal that would follow would include all the channel types that have an altered policy.

Signals

(Permalink)

PolicyChanged (a{su}: Changed_Policies)

Parameters

  • Changed_Policies — a{su} (Active_Policies_Map)
    • A subset of the active policies that have changed.
ActivePolicies has changed. This occurs when the server unilaterally changed the policy or SetPolicy has been called.

Properties

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

SupportedPolicies — a(asau) (Supported_Policy_List)

Read only
The communication policies supported by this connection.
(Permalink)

ActivePolicies — a{su} (Active_Policies_Map)

Read only

The active communication policies on this connection. Communication methods that are not in this mapping are considered open.

For example, to allow incoming calls only from contacts buddy list, and to allow text messages from anyone, the policy would look like this:

{
    'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open,
    'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List
}

Changes to this property are signalled by PolicyChanged.

Types

Enum (Permalink)

Access_Control_Type — u

A type for communication access control. These control policies are used in SupportedPolicies and ActivePolicies as well as most rich presence interfaces.
  • Whitelist (0)

    • Only allow contacts that are in a certain whitelist.

    This policy is relevant for presence interfaces, and should be associated with a list of contact handles that represent the whitelist of permited contacts.

  • Publish_List (1)
    • All contacts in the user's 'publish' contact list can communicate with us.
  • Group (2)

    • Only allow contacts that are in a certain group.

    This policy is relevant for presence interfaces, and should be associated with a group handle.

  • Open (3)
    • Anyone can initiate communication with the contact.
  • Subscribe_Or_Publish_List (5)
    • All contacts in the user's 'subscribe' or 'publish' contact list can communicate with us.
  • Closed (9)
    • Communication with the given channel type from any contact is blocked.
  • Not_Understood (10)

    • The access control rule is too complex to be represented in the current Telepathy API. The associated variant is meaningless. Setting this mode is never valid; the connection manager MUST raise an error if this is attempted.

    Rationale:
    XEP-0016 Privacy Lists can easily produce access control mechanisms that can't be expressed in a simpler API. We need to be able to at least indicate that fact.
Mapping (Permalink)

Active_Policies_Map — a{su}

A mapping of communication methods (channel types), and their associated policy.
Struct (Permalink)

Supported_Policy — (asau)

The communication methods (channel types), and the policies that can be applied to them. This is server and protocol dependant.

Grouped channel types will always have the same policy applied to them.

Rationale:
Different protocols have different limitations to the granularity of communication policies. One protocol might be able to set a different policy for VoIP calls and text chat, while another protocol might only be able to set one policy to both VoIP and text chat.