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) |
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
AdvertiseCapabilities (a(su): Add, as: Remove) → a(su): Self_Capabilities
Parameters
- Add — a(su) (Capability_Pair_List)
- a string channel type
- a bitwise OR of type specific capability flags
- Remove — as (DBus_Interface_List)
Returns
- Self_Capabilities — a(su) (Capability_Pair_List)
- 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
- Disconnected
Rationale:
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 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
Possible Errors
- Network Error
- Disconnected
- Invalid Handle
- Permission Denied
Rationale:
Signals
CapabilitiesChanged (a(usuuuu): Caps)
Parameters
- Caps — a(usuuuu) (Capability_Change_List)
- 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
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
Connection_Capability_Flags — u
- Create (1)
- Invite (2)
Capability_Pair — (su)
- Channel_Type — s (DBus_Interface)
- Type_Specific_Flags — u
Contact_Capability — (usuu)
- Handle — u (Contact_Handle)
- Channel_Type — s (DBus_Interface)
- Generic_Flags — u (Connection_Capability_Flags)
- Type_Specific_Flags — u
Capability_Change — (usuuuu)
- Handle — u (Contact_Handle)
- Channel_Type — s (DBus_Interface)
- Old_Generic_Flags — u (Connection_Capability_Flags)
- New_Generic_Flags — u (Connection_Capability_Flags)
- Old_Type_Specific_Flags — u
- New_Type_Specific_Flags — u