Conn.I.Requests — Telepathy D-Bus Interface Specification

# Interface Connection.Interface.Requests

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

### Methods

CreateChannel | (a{sv}: Request) | → | o: Channel, a{sv}: Properties |
EnsureChannel | (a{sv}: Request) | → | b: Yours, o: Channel, a{sv}: Properties |

### Signals

NewChannels | (a(oa{sv}): Channels) |
ChannelClosed | (o: Removed) |

### Properties

Channels | a(oa{sv}) (Channel_Details_List) | Read only |  |
RequestableChannelClasses | a(a{sv}as) (Requestable_Channel_Class_List) | Read only |  |

### Types

Channel_Class | Mapping | a{sv} |
Channel_Details | Struct | (oa{sv}) |
Requestable_Channel_Class | Struct | (a{sv}as) |

Added in 0.17.11. (as stable API)
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Connection

### Description

An enhanced version of the Telepathy connection interface, which can represent bundles of channels that should be dispatched together, and does not assume any particular properties by which channels are uniquely identifiable.

If this interface is implemented on a connection, then NewChannels MUST be emitted for all new channels, even those created with RequestChannel.

# Methods

(Permalink)

## CreateChannel (a{sv}: Request) → o: Channel, a{sv}: Properties

Added in 0.17.11. (as stable API)
Changed in 0.17.14. It is now guaranteed that CreateChannel returns the channel before NewChannels announces it (the reverse was previously guaranteed).

### Parameters

- Request — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties, which MUST include ChannelType. Some properties are defined such that only an exact match makes sense, and connection managers MUST NOT satisfy a request with a channel where that property does not match; some properties are defined such that the connection manager MAY treat the request as merely a hint, and make a best-effort attempt to satisfy it. This is documented separately for each property.

If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).

##### Rationale:

This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements.

The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.

Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.

### Returns

- Channel — o

The Channel object, which MUST NOT be signalled with NewChannels until after this method returns.

##### Rationale:

This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.

- Properties — a{sv} (Qualified_Property_Value_Map)

Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.

Request that an entirely new channel is created.

##### Rationale:

There is deliberately no flag corresponding to the suppress_handler argument to Connection.RequestChannel, because passing a FALSE value for that argument is deprecated. Requests made using this interface always behave as though suppress_handler was TRUE.

### 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.
- Network Error
Raised when there is an error reading from or writing to the network.
- Not Implemented
The channel request was one that can never succeed, such as requesting an unsupported channel type, or requesting a channel type which this connection manager does not support with the given target handle type.
- Invalid Handle
An invalid handle was requested as the value of a property whose value is a handle (like Channel.TargetHandle), or a syntactically invalid identifier was requested as the value of a property whose value is the string corresponding to a handle (like Channel.TargetID).
- Invalid Argument
The request matched the fixed properties of a Requestable_Channel_Class in RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList was requested, but the Server property provided was not a valid DNS name.
- Not Capable
The requested channel cannot be created because the requested contact is using a client that lacks a particular feature.
- Offline
The requested channel cannot be created because the target is offline.
- Not Available

The requested channel cannot be created, but in principle, a similar request might succeed in future. For instance, this might be because:

- a channel matching the request already exists and the protocol requires that only one such channel can exist at a time
- a channel matching the request has already been requested (by a previous call to CreateChannel, EnsureChannel, Connection.RequestChannel or similar) and the protocol requires that only one such channel can exist at a time

- Channel.Banned
You are banned from the channel.
- Channel.Full
The channel is full.
- Channel.Invite Only
The requested channel is invite-only.
- Permission Denied
The user is not permitted to perform the requested operation.

(Permalink)

## EnsureChannel (a{sv}: Request) → b: Yours, o: Channel, a{sv}: Properties

Added in 0.17.12.
Changed in 0.17.14. It is now guaranteed that if the channel was created by this call to EnsureChannel, it's returned before NewChannels announces it (the reverse was previously guaranteed).

### Parameters

- Request — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties, with the same semantics as the corresponding parameter to CreateChannel.

### Returns

- Yours — b

If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.

If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.

If the creation of a channel makes other requests successful, the value returned for this argument MUST be such that exactly one of the clients making requests ends up responsible for the channel. In particular, if CreateChannel returns a channel C, any EnsureChannel calls that also return C MUST return a false value for this argument.

- Channel — o
The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by NewChannels until after this method returns.

##### Rationale:

This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.

- Properties — a{sv} (Qualified_Property_Value_Map)

Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.

Request that channels are ensured to exist.

##### Rationale:

The connection manager is in the best position to determine which existing channels could satisfy which requests.

### 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.
- Network Error
Raised when there is an error reading from or writing to the network.
- Not Implemented
The channel request was one that can never succeed, such as requesting an unsupported channel type, or requesting a channel type which this connection manager does not support with the given target handle type.
- Invalid Handle
An invalid handle was requested as the value of a property whose value is a handle (like Channel.TargetHandle), or a syntactically invalid identifier was requested as the value of a property whose value is the string corresponding to a handle (like Channel.TargetID).
- Invalid Argument
The request matched the fixed properties of a Requestable_Channel_Class in RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList was requested, but the Server property provided was not a valid DNS name.
- Not Capable
The requested channel cannot be created because the requested contact is using a client that lacks a particular feature.
- Offline
The requested channel cannot be created because the target is offline.
- Not Available
The requested channel cannot be created, but in principle, a similar request might succeed in future.
- Channel.Banned
You are banned from the channel.
- Channel.Full
The channel is full.
- Channel.Invite Only
The requested channel is invite-only.
- Permission Denied
The user is not permitted to perform the requested operation.

# Signals

(Permalink)

## NewChannels (a(oa{sv}): Channels)

Added in 0.17.11. (as stable API)
Changed in 0.17.14. Added a guarantee of ordering relative to NewChannel

### Parameters

- Channels — a(oa{sv}) (Channel_Details_List)
The channels and their details. All channels that are signalled together like this MUST have the same Bundle property, which may either refer to an existing bundle, or establish a new bundle.

New channels have been created. The connection manager SHOULD emit a single signal for any group of closely related channels that are created at the same time, so that the channel dispatcher can try to dispatch them to a handler as a unit.

In particular, if additional channels are created as a side-effect of a call to CreateChannel, these channels SHOULD appear in the same NewChannels signal as the channel that satisfies the request.

##### Rationale:

Joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom), so a Text channel can be created as a side-effect.

Every time NewChannels is emitted, it MUST be followed by a Connection.NewChannel signal for each channel.

##### Rationale:

The double signal emission is for the benefit of older Telepathy clients, which won't be listening for NewChannels.

The more informative NewChannels signal comes first so that clients that did not examine the connection to find out whether Requests is supported will see the more informative signal for each channel first, and then ignore the less informative signal because it announces a new channel of which they are already aware.

(Permalink)

## ChannelClosed (o: Removed)

Added in 0.17.11. (as stable API)

### Parameters

- Removed — o
The channel which has been removed from the Channels property

Emitted when a channel is closed and hence disappears from the Channels property.

##### Rationale:

This is redundant with the Closed signal on the channel itself, but it does provide full change notification for the Channels property.

# Properties

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

## Channels — a(oa{sv}) (Channel_Details_List)

Read only
Added in 0.17.11. (as stable API)
A list of all the channels which currently exist on this connection. Change notification is via the NewChannels and ChannelClosed signals.
(Permalink)

## RequestableChannelClasses — a(a{sv}as) (Requestable_Channel_Class_List)

Read only
Added in 0.17.11. (as stable API)

The classes of channel that are expected to be available on this connection, i.e. those for which CreateChannel can reasonably be expected to succeed. User interfaces can use this information to show or hide UI components.

This property cannot change after the connection has gone to state Connection_Status_Connected, so there is no change notification (if the connection has context-dependent capabilities, it SHOULD advertise support for all classes of channel that it might support during its lifetime). Before this state has been reached, the value of this property is undefined.

##### Rationale:

This is not on an optional interface, because connection managers can always offer some sort of clue about the channel classes they expect to support (at worst, they can announce support for everything for which they have code).

# Types

Mapping (Permalink)

## Channel_Class — a{sv}

Added in 0.17.11. (as stable API)

Mapping representing a class of channels that can be requested from a connection manager, can be handled by a user interface, are supported by a contact, etc.

Classes of channel are identified by the fixed values of a subset of their properties.

Channel classes SHOULD always include the keys org.freedesktop.Telepathy.Channel.ChannelType and org.freedesktop.Telepathy.Channel.TargetHandleType. (One exception is that ContactSearch channels do not have TargetHandleType `None` in their requestable channel classes, for historical reasons.)

- Key — s (DBus_Qualified_Member)
A D-Bus interface name, followed by a dot and a D-Bus property name.
- Value — v
The value of the property.

Struct (Permalink)

## Channel_Details — (oa{sv})

Added in 0.17.11. (as stable API)
Enough details of a channel that clients can work out how to dispatch or handle it.

- Channel — o
The object path of the channel.
- Properties — a{sv} (Qualified_Property_Value_Map)

Properties of the channel.

Connection managers MUST NOT include properties in this mapping if their values can change. Clients MUST ignore properties that appear in this mapping if their values can change.

##### Rationale:

If properties that could change were included, the following race condition would be likely to exist in some cases:

- NewChannels or Get("Channels") includes a property P with value V1
- Client creates a proxy object for the channel
- The value of P changes to V2
- Client connects to PChanged signal
- Client should call Get("P") or GetAll here, to avoid the race, but client's author has forgotten to do so
- Proxy object thinks P == V1, but actually P == V2

We've taken the opportunity to make the API encourage the client author to get it right. Where possible, we intend that properties whose value will be used in channel dispatching or other "early" processing will be defined so that they are immutable (can never change).

Each dictionary MUST contain the keys org.freedesktop.Telepathy.Channel.ChannelType, org.freedesktop.Telepathy.Channel.TargetHandleType, org.freedesktop.Telepathy.Channel.TargetHandle, org.freedesktop.Telepathy.Channel.TargetID and org.freedesktop.Telepathy.Channel.Requested.

##### Rationale:

We expect these to be crucial to the channel-dispatching process.

Struct (Permalink)

## Requestable_Channel_Class — (a{sv}as)

Added in 0.17.11. (as stable API)

Structure representing a class of channels that can be requested, identified by a set of properties that identify that class of channel.

##### Rationale:

This will often just be the channel type and the handle type, but can include other properties of the channel - for instance, encrypted channels might require properties that unencrypted channels do not, like an encryption key.

In some cases, these classes of channel may overlap, in the sense that one class fixes all the properties that another class does, plus some more properties.

##### Rationale:

For older clients to still be able to understand how to request channels in the presence of a hypothetical "encryption" interface, we'd need to represent it like this:

- class 1: ChannelType = Text, TargetHandleType = CONTACT
- class 2: Channel.ChannelType = Text, Channel.TargetHandleType = CONTACT, Encryption.Encrypted = TRUE

- Fixed_Properties — a{sv} (Channel_Class)

The property values that identify this requestable channel class. These properties MUST be included in requests for a channel of this class, and MUST take these values.

Clients that do not understand the semantics of all the Fixed_Properties MUST NOT request channels of this class, since they would be unable to avoid making an incorrect request.

This implies that connection managers wishing to make channels available to old or minimal clients SHOULD have a channel class with the minimum number of Fixed_Properties, and MAY additionally have channel classes with extra Fixed_Properties.

Interface designers SHOULD avoid introducing fixed properties whose types are not serializable in a `.manager` file.

##### Rationale:

Connection managers with a fixed property that is not serializable cannot have a complete `.manager` file.

- Allowed_Properties — as (DBus_Qualified_Member_List)

Properties that MAY be set when requesting a channel of this channel type and handle type.

This array MUST NOT include properties that are in the Fixed_Properties mapping.

Properties in this array may either be required or optional, according to their documented semantics.

##### Rationale:

For instance, if TargetHandleType takes a value that is not Handle_Type_None, one or the other of TargetHandle and TargetID is required. Clients are expected to understand the documented relationship between the properties, so we do not have separate arrays of required and optional properties.

If this array contains the Bundle property, then this class of channel can be combined with other channels with that property in a request, or added to an existing bundle. If not, this signifies that the connection manager is unable to mark channels of this class as part of a bundle - this means that to the remote contact they are likely to be indistinguishable from channels requested separately.