This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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 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:
Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.
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.
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.
Start a request to create a channel. This initially just creates a
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
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.
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
The User_Action_Time parameter of
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, and SHOULD remember the preferred handler
so it can try to dispatch subsequent channels in the same bundle
to the same handler.
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
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
Start a request to ensure that a channel exists, creating it if
necessary. This initially just creates a
If this method is called for an Account that is disabled, invalid
or otherwise unusable, no error is signalled until
The rationale is as for
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
The User_Action_Time parameter of
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 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
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, 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.
An address book application, for example, might call 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.
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid