Interface Connection.Interface.ContactCapabilities

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

Methods

UpdateCapabilities (a(saa{sv}as): Handler_Capabilities) → nothing
GetContactCapabilities (au: Handles) → a{ua(a{sv}as)}: Contact_Capabilities

Signals

ContactCapabilitiesChanged (a{ua(a{sv}as)}: caps)

Contact Attributes

org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities/capabilities a(a{sv}as) (Requestable_Channel_Class_List)

Types

Contact_Capabilities_Map Mapping a{ua(a{sv}as)}
Handler_Capabilities Struct (saa{sv}as)
Added in 0.17.28. (as stable API)
Objects implementing this interface must also implement:

Description

Contact capabilities describe the channel classes which may be created with a given contact in advance of attempting to create a channel. Each capability represents a commitment by the connection manager that it will ordinarily be able to create a channel with a contact when given a request with the properties defined by the channel class.

Capabilities pertain to particular contact handles, and represent activities such as having a text chat, a voice call with the user or a stream tube of a defined type.

This interface also enables user interfaces to notify the connection manager what capabilities to advertise for the user to other contacts. This is done by using the UpdateCapabilities method.

Rationale:

XMPP is a major user of this interface: XMPP contacts will not, in general, be callable using VoIP unless they advertise suitable Jingle capabilities.

Many other protocols also have some concept of capability flags, which this interface exposes in a protocol-independent way.

Methods

(Permalink)

UpdateCapabilities (a(saa{sv}as): Handler_Capabilities) → nothing

Parameters

  • Handler_Capabilities — a(saa{sv}as) (Handler_Capabilities_List)

    • The capabilities of one or more clients.

    For each client in the given list, any capabilities previously advertised for the same client name are discarded, then replaced by the capabilities indicated.

    As a result, if a client becomes unavailable, this method SHOULD be called with a Handler_Capabilities structure containing its name, an empty list of channel classes, and an empty list of capabilities. When this is done, the connection manager SHOULD free all memory associated with that client name.

    Rationale:

    This method takes a list of clients so that when the channel dispatcher first calls it (with a list of all the Handlers that are initially available), the changes can be made atomically, with only one transmission of updated capabilities to the network. Afterwards, the channel dispatcher will call this method with a single-element list every time a Handler becomes available or unavailable.

    The connection manager MUST ignore any channel classes and client capabilities for which there is no representation in the protocol or no support in the connection manager.

Alter the connection's advertised capabilities to include the intersection of the given clients' capabilities with what the connection manager is able to implement.

On connections managed by the ChannelDispatcher, processes other than the ChannelDispatcher SHOULD NOT call this method, and the ChannelDispatcher SHOULD use this method to advertise the capabilities of all the registered Client.Handler implementations.On connections not managed by the ChannelDispatcher, clients MAY use this method directly, to indicate the channels they will handle and the extra capabilities they have.

Upon a successful invocation of this method, the connection manager will only emit the ContactCapabilitiesChanged signal for the user's SelfHandle if, in the underlying protocol, the new capabilities are distinct from the previous state.

Rationale:

The connection manager will essentially intersect the provided capabilities and the channel classes it implements. Therefore, certain properties which are never fixed for a channel class (such as the target handle, or the Parameters property of a tube channel) will almost certainly not be advertised.

This method MAY be called on a newly-created connection while it is still in the DISCONNECTED state, to request that when the connection connects, it will do so with the appropriate capabilities. Doing so MUST NOT fail.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
(Permalink)

GetContactCapabilities (au: Handles) → a{ua(a{sv}as)}: Contact_Capabilities

Parameters

  • Handles — au (Contact_Handle_List)

    • An array of contact handles for this connection.

    The handle zero MUST NOT be included in the request.

Returns

  • Contact_Capabilities — a{ua(a{sv}as)} (Contact_Capabilities_Map)

    • A map from contact handles to lists of requestable channel classes, representing the channel requests that are expected to succeed for that contact.

    Contacts listed among Handles whose capabilities are unknown SHOULD be omitted from this map; contacts known to have an empty set of capabilities SHOULD be included in the keys of this map, with an empty array as the corresponding value.

Returns an array of requestable channel classes for the given contact handles, representing the channel requests that are expected to succeed.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle does not represent a contact. Zero is always invalid.

Signals

(Permalink)

ContactCapabilitiesChanged (a{ua(a{sv}as)}: caps)

Parameters

Announce that there has been a change of capabilities on the given handles. A single signal can be emitted for several contacts.

Rationale:

The underlying protocol can get several contacts' capabilities at the same time.

Contact Attributes

Attributes that a contact can have, accessed with the org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
(Permalink)

org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities/capabilities — a(a{sv}as) (Requestable_Channel_Class_List)

The same structs that would be returned by GetContactCapabilities. Omitted from the result if the contact's capabilities are not known; present in the result as an empty array if the contact is known to have no capabilities at all.

Types

Mapping (Permalink)

Contact_Capabilities_Map — a{ua(a{sv}as)}

A mapping from contact handle to their capabilities.
  • Key — u (Contact_Handle)
    • A contact handle.
  • Value — a(a{sv}as) (Requestable_Channel_Class_List)

    • The contact's capabilities. These should be represented in the same way as in RequestableChannelClasses, except that they may have more fixed properties or fewer allowed properties, to represent contacts who do not have all the capabilities of the connection.

    In particular, requestable channel classes for channels with target handle type Contact MUST list TargetHandleType among their fixed properties when they appear here, and clients MAY assume that this will be the case.

    Rationale:

    This matches the initial implementations - service-side in telepathy-gabble, and client-side in telepathy-qt4 - and means that clients can use exactly the same code to interpret RequestableChannelClasses and contact capabilities.

    Channel classes with target handle type Handle_Type_Contact indicate that a request that matches the channel class, and also either has the contact's handle as TargetHandle or the contact's identifier as TargetID, can be expected to succeed. Connection managers SHOULD NOT include the TargetHandle or TargetID as a fixed property in contact capabilities.

    Rationale:

    This makes one channel class sufficient to describe requests via TargetHandle or TargetID, and is necessary in order to allow clients to interpret RequestableChannelClasses and contact capabilities with the same code.

    Channel classes with target handle type Handle_Type_Room or Handle_Type_None indicate that if a channel matching the channel class is created, then inviting the contact to that channel can be expected to succeed.

    Rationale:

    To support room-based XMPP protocols like Muji and MUC Tubes, it's necessary to be able to discover who can be invited to a given room channel; most XMPP contacts won't support being invited into a Muji conference call, at least in the short to medium term.

    No interpretation is defined for channel classes with any other target handle type, or for channel classes that do not fix a target handle type, in this version of the Telepathy specification.

Struct (Permalink)

Handler_Capabilities — (saa{sv}as)

A structure representing the capabilities of a single client.
  • Well_Known_Name — s (DBus_Well_Known_Name)
    • For implementations of the Client interface, the well-known bus name name of the client; for any other process, any other reversed domain name that uniquely identifies it.
  • Channel_Classes — aa{sv} (String_Variant_Map_List)
    • An array of channel classes that can be handled by this client. This will usually be a copy of the client's HandlerChannelFilter property.
  • Capabilities — as (Handler_Capability_Token_List)
    • An array of client capabilities supported by this client, to be used by the connection manager to determine what capabilities to advertise. This will usually be a copy of the client's Capabilities property.