2
<node name="/Channel_Dispatcher"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
5
<tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
6
<tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
7
<tp:license xmlns="http://www.w3.org/1999/xhtml">
8
<p>This library is free software; you can redistribute it and/or
9
modify it under the terms of the GNU Lesser General Public
10
License as published by the Free Software Foundation; either
11
version 2.1 of the License, or (at your option) any later version.</p>
13
<p>This library is distributed in the hope that it will be useful,
14
but WITHOUT ANY WARRANTY; without even the implied warranty of
15
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16
Lesser General Public License for more details.</p>
18
<p>You should have received a copy of the GNU Lesser General Public
19
License along with this library; if not, write to the Free Software
20
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
24
<interface name="org.freedesktop.Telepathy.ChannelDispatcher"
25
tp:causes-havoc="not yet final">
27
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28
<p>The channel dispatcher is responsible for responding to new
29
channels and launching client processes to handle them. It also
30
provides functionality for client processes to request that new
31
channels are created.</p>
33
<p>If a channel dispatcher is running, it is responsible for dispatching
35
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s
37
<tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
38
Connections not created by the AccountManager are outside the scope
39
of the channel dispatcher.</p>
42
<p>Connections created by standalone Telepathy clients
43
that do not intend to interact with the channel dispatcher
44
should be ignored - otherwise, the channel dispatcher would try
45
to launch handlers for channels that the standalone client
46
was already handling internally.</p>
49
<p>The current channel dispatcher is defined to be the process that
50
owns the well-known bus name
51
<code>org.freedesktop.Telepathy.ChannelDispatcher</code> on
52
the session bus. This process MUST export an object with this
53
interface at the object path
54
<code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p>
56
<p>Until a mechanism exists for making a reasonable automatic choice
57
of ChannelDispatcher implementation, implementations SHOULD NOT
58
register as an activatable service for the ChannelDispatcher's
59
well-known bus name. Instead, it is RECOMMENDED that some component
60
of the user's session will select and activate a particular
61
implementation, and that other Telepathy-enabled programs
62
can detect whether channel request/dispatch functionality is available
63
by checking whether the ChannelDispatcher's well-known name is in use
66
<p>There are three categories of client process defined by this
71
namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt>
72
<dd><p>Observers monitor the creation of new channels. This
73
functionality can be used for things like message logging.
74
All observers are notified simultaneously.</p></dd>
77
namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>p
79
<p>Approvers notify the user that new channels have been created,
80
and also select which channel handler will be used for the channel,
81
either by asking the user or by choosing the most appropriate
86
namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt>
88
<p>Each new channel or set of channels is passed to exactly one
89
handler as its final destination. A typical channel handler is a
90
user interface process handling channels of a particular type.</p>
95
<property name="Interfaces" tp:name-for-bindings="Interfaces"
96
type="as" access="read" tp:type="DBus_Interface[]">
98
A list of the extra interfaces provided by this channel dispatcher.
102
<method name="CreateChannel" tp:name-for-bindings="Create_Channel">
103
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
104
<p>Start a request to create a channel. This initially just creates a
105
<tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
106
object, which can be used to continue the request and track its
107
success or failure.</p>
110
<p>The request can take a long time - in the worst case, the
111
channel dispatcher has to ask the account manager to put the
112
account online, the account manager has to ask the operating
113
system to obtain an Internet connection, and the operating
114
system has to ask the user whether to activate an Internet
115
connection using an on-demand mechanism like dialup.</p>
117
<p>This means that using a single D-Bus method call and response
118
to represent the whole request will tend to lead to that call
119
timing out, which is not the behaviour we want.</p>
122
<p>If this method is called for an Account that is disabled, invalid
123
or otherwise unusable, no error is signalled until
125
namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
126
is called, at which point
128
namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
129
is emitted with an appropriate error.</p>
132
<p>This means there's only one code path for errors, apart from
133
InvalidArgument for "that request makes no sense".</p>
135
<p>It also means that the request will proceed if the account is
136
enabled after calling CreateChannel, but before calling
141
<arg direction="in" name="Account" type="o">
144
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
145
for which the new channel is to be created.
149
<arg direction="in" name="Requested_Properties" type="a{sv}"
150
tp:type="Qualified_Property_Value_Map">
151
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
152
<p>A dictionary containing desirable properties. This has the same
153
semantics as the corresponding parameter to
154
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
157
<p>Certain properties will not necessarily make sense in this
158
dictionary: for instance,
159
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
160
can only be given if the requester is able to interact with a
161
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
162
to the desired account.</p>
166
<arg direction="in" name="User_Action_Time" type="x"
167
tp:type="Unix_Timestamp64">
168
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
169
<p>The time at which user action occurred, or 0 if this channel
170
request is for some reason not involving user action.
172
namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
173
property will be set to this value, and it will eventually be
174
passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
175
namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
179
<arg direction="in" name="Preferred_Handler" type="s"
180
tp:type="DBus_Well_Known_Name">
181
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
182
<p>Either the well-known bus name (starting with
183
<code>org.freedesktop.Telepathy.Client.</code>)
184
of the preferred handler for this
185
channel, or an empty string to indicate that any handler would be
186
acceptable. The channel dispatcher SHOULD dispatch as many as
187
possible of the resulting channels (ideally, all of them)
188
to that handler, and SHOULD remember the preferred handler
189
so it can try to dispatch subsequent channels in the same bundle
190
to the same handler.</p>
193
<p>This must be the well-known bus name, not the unique name,
194
to ensure that all handlers do indeed have the Client API,
195
and the Client object on the handler can be located easily.</p>
197
<p>This is partly so the channel dispatcher can call
199
namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
200
on it, and partly so the channel dispatcher
201
can recover state if it crashes and is restarted.</p>
204
<p>If this is a well-known bus name and the handler has the
205
Requests interface, the channel dispatcher SHOULD
207
namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
208
on that Handler after this method has returned.</p>
211
<p>This ordering allows a Handler which calls CreateChannel with
212
itself as the preferred handler to associate the call to
213
AddRequest with that call.</p>
216
<p>This is copied to the ChannelRequest that is returned,
218
namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
223
<arg direction="out" name="Request" type="o">
226
<tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
232
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
234
The Preferred_Handler is syntactically invalid or does
235
not start with <code>org.freedesktop.Telepathy.Client.</code>,
236
the Account does not exist, or one of the Requested_Properties
240
</tp:possible-errors>
244
<method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
245
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
246
<p>Start a request to ensure that a channel exists, creating it if
247
necessary. This initially just creates a <tp:dbus-ref
248
namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
249
object, which can be used to continue the request and track its
250
success or failure.</p>
252
<p>If this method is called for an Account that is disabled, invalid
253
or otherwise unusable, no error is signalled until
255
namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
256
is called, at which point
258
namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
259
is emitted with an appropriate error.</p>
262
<p>The rationale is as for <tp:dbus-ref
263
namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p>
267
<arg direction="in" name="Account" type="o">
270
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
271
for which the new channel is to be created.
275
<arg direction="in" name="Requested_Properties" type="a{sv}"
276
tp:type="Qualified_Property_Value_Map">
277
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
278
<p>A dictionary containing desirable properties. This has the same
279
semantics as the corresponding parameter to
280
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
283
<p>Certain properties will not necessarily make sense in this
284
dictionary: for instance,
285
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
286
can only be given if the requester is able to interact with a
287
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
288
to the desired account.</p>
292
<arg direction="in" name="User_Action_Time" type="x"
293
tp:type="Unix_Timestamp64">
294
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
295
<p>The time at which user action occurred, or 0 if this channel
296
request is for some reason not involving user action.</p>
298
<p>This parameter is used in the same way as the corresponding
299
parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>
303
<arg direction="in" name="Preferred_Handler" type="s"
304
tp:type="DBus_Well_Known_Name">
305
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
306
<p>Either the well-known bus name (starting with
307
<code>org.freedesktop.Telepathy.Client.</code>)
308
of the preferred handler for this
309
channel, or an empty string to indicate that any handler would be
310
acceptable. The behaviour and rationale are the same as for the
311
corresponding parameter to
312
<tp:member-ref>CreateChannel</tp:member-ref>, except as noted
315
<p>If any new channels are created in response to this
316
request, the channel dispatcher SHOULD dispatch as many as
317
possible of the resulting channels (ideally, all of them)
318
to that handler, and SHOULD remember the preferred handler
319
so it can try to dispatch subsequent channels in the same bundle
320
to the same handler. If the requested channel already exists (that
322
namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
323
returns <code>Yours=False</code>) then the channel dispatcher
324
SHOULD re-dispatch the channel to its existing handler, and MUST
325
NOT dispatch it to this client (unless it is the existing handler);
326
the request is still deemed to have succeeded in this case.</p>
329
<p>An address book application, for example, might call <tp:dbus-ref
330
namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
331
to ensure that a text channel with a particular contact is
332
displayed to the user; it does not care whether a new channel was
333
made. An IM client might call <tp:dbus-ref
334
namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
335
in response to the user double-clicking an entry in the contact
336
list, with itself as the <code>Preferred_Handler</code>; if the
337
user already has a conversation with that contact in another
338
application, they would expect the existing window to be
339
presented, rather than their double-click leading to an error
340
message. So the request should succeed, even if its
341
<code>Preferred_Handler</code> is not used.</p>
347
<arg direction="out" name="Request" type="o">
350
<tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
356
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
358
The Preferred_Handler is syntactically invalid or does
359
not start with <code>org.freedesktop.Telepathy.Client.</code>,
360
the Account does not exist, or one of the Requested_Properties
364
</tp:possible-errors>
370
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
xml/Channel_Dispatcher.xml
