ChannelDispatcher — Telepathy D-Bus Interface Specification

# Interface ChannelDispatcher

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

### Methods

CreateChannel | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler) | → | o: Request |
EnsureChannel | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler) | → | o: Request |
CreateChannelWithHints | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) | → | o: Request |
EnsureChannelWithHints | (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) | → | o: Request |
DelegateChannels | (ao: Channels, x: User_Action_Time, s: Preferred_Handler) | → | ao: Delegated, a{o(ss)}: Not_Delegated |
PresentChannel | (o: Channel, x: User_Action_Time) | → | nothing |

### Properties

Interfaces | as (DBus_Interface_List) | Read only |  |
SupportsRequestHints | b | Read only |  |

### Types

Not_Delegated_Map | Mapping | a{o(ss)} |
Not_Delegated_Error | Struct | (ss) |

Added in 0.17.26. (as a stable interface)

### Description

The channel dispatcher is responsible for responding to new channels and launching client processes to handle them. It also provides functionality for client processes to request that new channels are created.

If a channel dispatcher is running, it is responsible for dispatching new channels on all Connections created by the AccountManager. Connections not created by the AccountManager are outside the scope of the channel dispatcher.

##### Rationale:

Connections created by standalone Telepathy clients that do not intend to interact with the channel dispatcher should be ignored - otherwise, the channel dispatcher would try to launch handlers for channels that the standalone client was already handling internally.

The current channel dispatcher is defined to be the process that owns the well-known bus name `org.freedesktop.Telepathy.ChannelDispatcher` on the session bus. This process MUST export an object with this interface at the object path `/org/freedesktop/Telepathy/ChannelDispatcher`.

Until a mechanism exists for making a reasonable automatic choice of ChannelDispatcher implementation, implementations SHOULD NOT register as an activatable service for the ChannelDispatcher's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether channel request/dispatch functionality is available by checking whether the ChannelDispatcher's well-known name is in use at runtime.

There are three categories of client process defined by this specification:

Observer

  Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.

Approver

  Approvers notify the user that new channels have been created, and also select which channel handler will be used for the channel, either by asking the user or by choosing the most appropriate channel handler.

Handler

  Each new channel or set of channels is passed to exactly one handler as its final destination. A typical channel handler is a user interface process handling channels of a particular type.

# Methods

(Permalink)

## CreateChannel (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler) → o: Request

### Parameters

- Account — o
The Account for which the new channel is to be created.
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- Preferred_Handler — s (DBus_Well_Known_Name)
Changed in 0.19.0. Previously, the spec didn't say that this should disregard the handler's filter. This has been implemented since telepathy-mission-control 5.3.2.

Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

### Returns

- Request — o
A ChannelRequest object.

Equivalent to calling CreateChannelWithHints with an empty Hints parameter.

### Possible Errors

- Invalid Argument
The Preferred_Handler is syntactically invalid or does not start with `org.freedesktop.Telepathy.Client.`, the Account does not exist, or one of the Requested_Properties is invalid

(Permalink)

## EnsureChannel (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler) → o: Request

### Parameters

- Account — o
The Account for which the new channel is to be created.
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- Preferred_Handler — s (DBus_Well_Known_Name)

Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to EnsureChannelWithHints.

### Returns

- Request — o
A ChannelRequest object.

Equivalent to calling EnsureChannelWithHints with an empty Hints parameter.

### Possible Errors

- Invalid Argument
The Preferred_Handler is syntactically invalid or does not start with `org.freedesktop.Telepathy.Client.`, the Account does not exist, or one of the Requested_Properties is invalid

(Permalink)

## CreateChannelWithHints (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) → o: Request

Added in 0.21.5. Support for this method is indicated by the SupportsRequestHints property. Clients MUST recover from this method being unsupported by falling back to CreateChannel.

### Parameters

- Account — o
The Account for which the new channel is to be created.
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.CreateChannel.

Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. The UserActionTime property will be set to this value, and it will eventually be passed as the `User_Action_Time` parameter of HandleChannels.

- Preferred_Handler — s (DBus_Well_Known_Name)
Changed in 0.19.0. Previously, the spec didn't say that this should disregard the handler's filter. This has been implemented since telepathy-mission-control 5.3.2.

Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler—irrespective of whether that handler's HandlerChannelFilter matches the channel—and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler.

##### Rationale:

This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.

This is partly so the channel dispatcher can call HandleChannels on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.

The filter should be disregarded for ease of use of this interface: clients will usually use this argument to request channels be sent to themself, and this should trump the filter not matching. This also allows a client to become the handler for a channel produced by one of its own requests, while not being a candidate to handle other channels of that type.

If this is a well-known bus name and the handler has the Requests interface, the channel dispatcher SHOULD call AddRequest on that Handler after this method has returned.

##### Rationale:

This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.

This is copied to the ChannelRequest that is returned, as the PreferredHandler property.

- Hints — a{sv}

Additional information about the channel request, which will be used as the value for the resulting request's Hints property.

##### Rationale:

See the Hints property's documentation for rationale.

### Returns

- Request — o
A ChannelRequest object.

Start a request to create a channel. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.

##### Rationale:

The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.

This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.

##### Rationale:

This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".

It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.

### Possible Errors

- Invalid Argument
The Preferred_Handler is syntactically invalid or does not start with `org.freedesktop.Telepathy.Client.`, the Account does not exist, or one of the Requested_Properties is invalid

(Permalink)

## EnsureChannelWithHints (o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler, a{sv}: Hints) → o: Request

Added in 0.21.5. Support for this method is indicated by the SupportsRequestHints property. Clients MUST recover from this method being unsupported by falling back to EnsureChannel.

### Parameters

- Account — o
The Account for which the new channel is to be created.
- Requested_Properties — a{sv} (Qualified_Property_Value_Map)

A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.EnsureChannel.

Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- Preferred_Handler — s (DBus_Well_Known_Name)

Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to CreateChannelWithHints, except as noted here.

If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler, and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler. If the requested channel already exists (that is, Connection.Interface.Requests.EnsureChannel returns `Yours=False`) then the channel dispatcher SHOULD re-dispatch the channel to its existing handler, and MUST NOT dispatch it to this client (unless it is the existing handler); the request is still deemed to have succeeded in this case.

##### Rationale:

An address book application, for example, might call EnsureChannel to ensure that a text channel with a particular contact is displayed to the user; it does not care whether a new channel was made. An IM client might call EnsureChannel in response to the user double-clicking an entry in the contact list, with itself as the `Preferred_Handler`; if the user already has a conversation with that contact in another application, they would expect the existing window to be presented, rather than their double-click leading to an error message. So the request should succeed, even if its `Preferred_Handler` is not used.

- Hints — a{sv}
Additional information about the channel request, which will be used as the value for the resulting request's Hints property.

### Returns

- Request — o
A ChannelRequest object.

Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.

##### Rationale:

The rationale is as for CreateChannelWithHints.

### Possible Errors

- Invalid Argument
The Preferred_Handler is syntactically invalid or does not start with `org.freedesktop.Telepathy.Client.`, the Account does not exist, or one of the Requested_Properties is invalid

(Permalink)

## DelegateChannels (ao: Channels, x: User_Action_Time, s: Preferred_Handler) → ao: Delegated, a{o(ss)}: Not_Delegated

Added in 0.23.1. Implemented since telepathy-mission-control 5.7.12.
Changed in 0.23.2. This method now returns Delegated and Not_Delegated instead of nothing. HandleChannels is now called once per Channel in Channels.

### Parameters

- Channels — ao

The list of channels to redispatch. The caller has to be the current Handler of all of these channels

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channels delegation is for some reason not involving user action.

This parameter is used in the same way as the corresponding parameter to CreateChannelWithHints.

- Preferred_Handler — s (DBus_Well_Known_Name)

Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred new handler for these channels, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to CreateChannelWithHints.

### Returns

- Delegated — ao

The list of channels which have been delegated; the caller is no longer handling these channels.

The client should remove these channels from its HandledChannels property.

- Not_Delegated — a{o(ss)} (Not_Delegated_Map)

The list of channels which have NOT been delegated; the caller is still handling these channels.

Called by a Handler to redispatch a bunch of channels it is currently handling.

For each Channel in Channels, if another Handler can be found, HandleChannels will be called on it until a Handler accepts it.

This method returns once all the Channels have either been accepted or rejected by Handlers.

If this method fails, the original Handler is still handling the channels.

### Possible Errors

- Invalid Argument
The Preferred_Handler is syntactically invalid or does not start with `org.freedesktop.Telepathy.Client.`.
- Not Yours
At least one Channel in Channels is not currently handled by the caller. No Channel has been delegated.

(Permalink)

## PresentChannel (o: Channel, x: User_Action_Time) → nothing

Added in 0.23.1. Implemented since telepathy-mission-control 5.7.12.

### Parameters

- Channel — o

The channel to present.

- User_Action_Time — x (User_Action_Timestamp)

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

This parameter is used in the same way as the corresponding parameter to EnsureChannelWithHints.

Equivalent of calling EnsureChannel with a Requested_Properties which would result in ensuring Channel.

If Channel is handled, its handler will be asked to present it the user (e.g. bring it into the foreground).

### Possible Errors

- Invalid Argument
The Account does not exist, the Channel does not exist or it does not belong to the Account.

# Properties

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

## Interfaces — as (DBus_Interface_List)

Read only
A list of the extra interfaces provided by this channel dispatcher.
(Permalink)

## SupportsRequestHints — b

Read only
Added in 0.21.5.
If `True`, the channel dispatcher is new enough to support CreateChannelWithHints and EnsureChannelWithHints, in addition to the older CreateChannel and EnsureChannel methods, and also new enough to emit SucceededWithChannel before the older Succeeded signal. If `False` or missing, only the metadata-less variants are supported.

# Types

Mapping (Permalink)

## Not_Delegated_Map — a{o(ss)}

A mapping associating not delegated channel with an error.

- Channel — o
The path of the channel
- Error — (ss) (Not_Delegated_Error)
An error describing why the channel has not be delegated

Struct (Permalink)

## Not_Delegated_Error — (ss)

- Error_Name — s (DBus_Error_Name)
the name of a D-Bus error describing what went wrong.
- Error_Message — s
a human-readable informative error message.