Interface Connection.Interface.Capabilities

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

Methods

AdvertiseCapabilities (a(su): Add, as: Remove) → a(su): Self_Capabilities
GetCapabilities (au: Handles) → a(usuu): Contact_Capabilities

Signals

CapabilitiesChanged (a(usuuuu): Caps)

Contact Attributes

org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps a(usuu) (Contact_Capability_List)

Types

Connection_Capability_Flags Flags u
Capability_Pair Struct (su)
Contact_Capability Struct (usuu)
Capability_Change Struct (usuuuu)
Changed in 0.17.8. Previously, this interface also expressed capabilities of the connection itself, indicating what sorts of channels could be requested (for instance, the ability to open chatroom lists or chatrooms). However, this was never very well-defined or consistent, and as far as we know it was never implemented correctly. This usage is now deprecated.
Objects implementing this interface must also implement:

Description

An interface for connections where it is possible to know what channel types may be requested before the request is made to the connection object. Each capability represents a commitment by the connection manager that it will ordinarily be able to create a channel when given a request with the given type and handle.

Capabilities pertain to particular contact handles, and represent activities such as having a text chat or a voice call with the user. The activities are represented by the D-Bus interface name of the channel type for that activity.

The generic capability flags are defined by Connection_Capability_Flags.

In addition, channel types may have type specific capability flags of their own, which are described in the documentation for each channel type.

This interface also provides for user interfaces notifying the connection manager of what capabilities to advertise for the user. This is done by using the AdvertiseCapabilities method, and deals with the interface names of channel types and the type specific flags pertaining to them which are implemented by available client processes.

Methods

(Permalink)

AdvertiseCapabilities (a(su): Add, as: Remove) → a(su): Self_Capabilities

Parameters

  • Add — a(su) (Capability_Pair_List)
    • An array of structures containing:
    • a string channel type
    • a bitwise OR of type specific capability flags
  • Remove — as (DBus_Interface_List)
    • An array of D-Bus interface names of channel types to remove

Returns

  • Self_Capabilities — a(su) (Capability_Pair_List)
    • An array of structures describing the current capabilities containing:
    • a string channel type
    • a bitwise OR of type specific capability flags

Used by user interfaces to indicate which channel types they are able to handle on this connection. Because these may be provided by different client processes, this method accepts channel types to add and remove from the set already advertised on this connection. The type of advertised capabilities (create versus invite) is protocol-dependent and hence cannot be set by the this method. In the case of a client adding an already advertised channel type but with new channel type specific flags, the connection manager should simply add the new flags to the set of advertised capabilities.

Upon a successful invocation of this method, the CapabilitiesChanged signal will be emitted for the user's own handle ( Connection.GetSelfHandle) by the connection manager to indicate the changes that have been made. This signal should also be monitored to ensure that the set is kept accurate - for example, a client may remove capabilities or type specific capability flags when it exits which are still provided by another client.

On connections managed by the ChannelDispatcher, this method SHOULD NOT be used by clients other than the ChannelDispatcher itself.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • 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.
(Permalink)

GetCapabilities (au: Handles) → a(usuu): Contact_Capabilities

Parameters

  • Handles — au (Contact_Handle_List)

    • An array of contact handles for this connection.

    This may include zero, which originally meant a query for capabilities available on the connection itself. This usage is deprecated; clients SHOULD NOT do this, and connection managers SHOULD proceed as though zero had not been present in this list.

Returns

  • Contact_Capabilities — a(usuu) (Contact_Capability_List)
    • An array of structures containing:
    • an integer handle representing the contact
    • a string channel type
    • a bitwise OR of generic capability flags for the type
    • a bitwise OR of type specific capability flags for the type
Returns an array of capabilities for the given contact handles.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • 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 and is not zero
  • Permission Denied
    • The user is not permitted to perform the requested operation.

Signals

(Permalink)

CapabilitiesChanged (a(usuuuu): Caps)

Parameters

  • Caps — a(usuuuu) (Capability_Change_List)
    • An array of structures containing:
    • an integer handle representing the contact
    • a string channel type
    • a bitwise OR of the contact's old generic capability flags
    • a bitwise OR of the contact's new generic capability flags
    • a bitwise OR of the contact's old type specific capability flags
    • a bitwise OR of the contact's new type specific capability flags

Announce that there has been a change of capabilities on the given handle.

If the handle is zero, the capabilities refer to the connection itself, in some poorly defined way. This usage is deprecated and clients should ignore it.

Contact Attributes

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

org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps — a(usuu) (Contact_Capability_List)

The same structs that would be returned by GetCapabilities (all of them will redundantly have the contact's handle as the first member). 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

Flags (Permalink)

Connection_Capability_Flags — u

  • Create (1)
    • The given channel type and handle can be given to RequestChannel to create a new channel of this type.
  • Invite (2)
    • The given contact can be invited to an existing channel of this type.
Struct (Permalink)

Capability_Pair — (su)

A pair (channel type, type-specific flags) as passed to AdvertiseCapabilities on the Capabilities interface.
Struct (Permalink)

Contact_Capability — (usuu)

A struct (contact handle, channel type, generic flags, type-specific flags) representing a capability posessed by a contact, as returned by GetCapabilities on the Capabilities interface.
Struct (Permalink)

Capability_Change — (usuuuu)

A struct (contact handle, channel type, old generic flags, new generic flags, old type-specific flags, new type-specific flags) representing a change to one of a contact's capabilities, as seen in the CapabilitiesChanged signal on the Capabilities interface.