2
<node name="/Channel_Dispatch_Operation"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
5
<tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
6
<tp:copyright>Copyright (C) 2008 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,
21
MA 02110-1301, USA.</p>
24
<interface name="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT"
25
tp:causes-havoc="experimental">
27
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28
<p>A channel dispatch operation is an object in the ChannelDispatcher
29
representing a bundle of unrequested channels being announced to
31
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref>
34
<p>These objects can result from new incoming channels or channels
35
which are automatically created for some reason, but cannot result
36
from outgoing requests for channels.</p>
38
<p>More specifically, whenever the
39
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
40
signal contains channels whose
41
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
42
property is false, or whenever the
43
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
44
signal contains a channel with suppress_handler false,
45
one or more ChannelDispatchOperation objects are created for those
48
<p>(If some channels in a NewChannels signal are in different bundles,
49
this is an error. The channel dispatcher SHOULD recover by treating
50
the NewChannels signal as if it had been several NewChannels signals
51
each containing one channel.)</p>
53
<p>First, the channel dispatcher SHOULD construct a list of all the
55
namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>s
56
that could handle all the channels (based on their <tp:dbus-ref
57
namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref>
59
priority in some implementation-dependent way. If there are handlers
60
which could handle all the channels, one channel dispatch operation
61
SHOULD be created for all the channels. If there are not, one channel
62
dispatch operation SHOULD be created for each channel, each with
63
a list of channel handlers that could handle that channel.</p>
65
<p>When listing channel handlers, priority SHOULD be given to
66
channel handlers that are already handling channels from the same
69
<p>If a handler with <tp:dbus-ref
70
namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">BypassApproval</tp:dbus-ref>
71
<code>= True</code> could handle the channels in the dispatch
72
operation, then the channel dispatcher SHOULD call <tp:dbus-ref
73
namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
74
on that handler, and (assuming the call succeeds) emit
75
<tp:member-ref>Finished</tp:member-ref> and stop processing those
76
channels without involving any approvers.</p>
79
<p>Some channel types can be picked up "quietly" by an existing
80
channel handler. If a <tp:dbus-ref
81
namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
82
channel is added to an existing bundle containing a <tp:dbus-ref
83
namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
84
channel, there shouldn't be
85
any approvers, flashing icons or notification bubbles, if the
86
the UI for the StreamedMedia channel can just add a text box
87
and display the message.</p>
90
<p>Otherwise, the channel dispatcher SHOULD send the channel dispatch
91
operation to all relevant approvers (in parallel) and wait for an
92
approver to claim the channels or request that they are handled.
95
namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>
96
for more details on this.</p>
98
<p>Finally, if the approver requested it, the channel dispatcher SHOULD
99
send the channels to a handler.</p>
102
<property name="Interfaces" tp:name-for-bindings="Interfaces"
103
type="as" access="read" tp:type="DBus_Interface[]">
105
A list of the extra interfaces provided by this channel dispatch
106
operation. This property cannot change.
110
<property name="Connection" tp:name-for-bindings="Connection"
111
type="o" access="read">
114
namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
115
with which the <tp:member-ref>Channels</tp:member-ref> are
116
associated. The well-known bus name to use can be derived from
117
this object path by removing the leading '/' and replacing all
118
subsequent '/' by '.'. This property cannot change.
122
<property name="Account" tp:name-for-bindings="Account"
123
type="o" access="read">
126
namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
127
with which the <tp:member-ref>Connection</tp:member-ref>
128
and <tp:member-ref>Channels</tp:member-ref> are
129
associated. This property cannot change.
133
<property name="Channels" tp:name-for-bindings="Channels"
134
type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
137
namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
138
to be dispatched, and their properties. Change notification is via
139
the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
140
cannot be added to this property, only removed).
144
<signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
146
A channel has closed before it could be claimed or handled. If this
147
is emitted for the last remaining channel in a channel dispatch
148
operation, it MUST immediately be followed by
149
<tp:member-ref>Finished</tp:member-ref>.
152
<arg name="Channel" type="o">
155
namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>
160
<arg name="Error" type="s" tp:type="DBus_Error_Name">
161
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
162
<p>The name of a D-Bus error indicating why the channel closed. If
163
no better reason can be found,
164
<code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
165
be used as a fallback; this means that this error SHOULD NOT be
166
given any more specific meaning.</p>
168
<p>FIXME: or should we invent a new OtherError for that purpose?</p>
170
<p>FIXME: we need to specify errors for these situations:</p>
173
<li>kicked from a chatroom</li>
174
<li>outgoing call rejected</li>
175
<li>outgoing call timed out</li>
176
<li>incoming call terminated</li>
181
<arg name="Message" type="s">
183
A string associated with the D-Bus error.
188
<property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
189
type="as" access="read" tp:type="DBus_Well_Known_Name[]">
191
The well known bus names (starting with
192
<code>org.freedesktop.Telepathy.Client.</code>) of the possible
194
namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>s
195
for these channels. The channel dispatcher MUST place the most
196
preferred handlers first, according to some reasonable heuristic.
197
As a result, approvers SHOULD use the first handler by default.
201
<method name="HandleWith" tp:name-for-bindings="Handle_With">
202
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
203
<p>Called by an approver to accept a channel bundle and request that
204
the given handler be used to handle it.</p>
206
<p>If successful, this method will cause the ChannelDispatchOperation
207
object to disappear, emitting
208
<tp:member-ref>Finished</tp:member-ref>.</p>
210
<p>However, this method may fail because the dispatch has already been
211
completed and the object has already gone. If this occurs, it
212
indicates that another approver has asked for the bundle to be
213
handled by a particular handler. The approver MUST NOT attempt
214
to interact with the channels further in this case, unless it is
215
separately invoked as the handler.</p>
217
<p>Approvers which are also channel handlers SHOULD use
218
<tp:member-ref>Claim</tp:member-ref> instead
219
of HandleWith to request that they can handle a channel bundle
222
<p>(FIXME: list some possible errors)</p>
224
<p>If the channel handler raises an error from <tp:dbus-ref
225
namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>,
227
MAY respond by raising that same error, even if it is not
228
specifically documented here.</p>
231
<arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
232
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
233
<p>The well-known bus name (starting with
234
<code>org.freedesktop.Telepathy.Client.</code>) of the channel
235
handler that should handle the channel.</p>
240
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
241
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
242
The selected handler is not a syntactically correct
243
<tp:type>DBus_Bus_Name</tp:type> or does not start with
244
"<code>org.freedesktop.Telepathy.Client.</code>".
247
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
249
The selected handler is temporarily unable to handle these
253
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
255
The selected handler is syntactically correct, but will never
256
be able to handle these channels (for instance because the channels
257
do not match its HandlerChannelFilter, or because HandleChannels
258
raised NotImplemented).
261
<tp:error name="org.freedesktop.Telepathy.Error.NotYours">
263
At the time that HandleWith was called, this dispatch operation was
264
processing an earlier call to HandleWith. The earlier call has
265
now succeeded, so some Handler nominated by another approver is
266
now responsible for the channels. In this situation, the second
267
call to HandleWith MUST NOT return until the first one has
268
returned successfully or unsuccessfully, and if the first call
269
to HandleChannels fails, the channel dispatcher SHOULD try to obey
270
the choice of Handler made by the second call to HandleWith.
273
</tp:possible-errors>
276
<method name="Claim" tp:name-for-bindings="Claim">
277
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
278
<p>Called by an approver to claim channels for handling
279
internally. If this method is called successfully, the process
280
calling this method becomes the handler for the channel, but
281
<em>does not</em> have the HandleChannels method called on it.</p>
282
<!-- FIXME: tp:dbus-ref -->
284
<p>Clients that call Claim on channels but do not immediately
285
close them SHOULD implement the Handler interface and its
286
CurrentlyHandledChannels property.</p>
287
<!-- FIXME: tp:dbus-ref -->
289
<p>Approvers wishing to reject channels MUST call this method to
290
claim ownership of them, and MUST NOT call
291
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
292
on the channels unless/until this method returns successfully.</p>
295
<p>The channel dispatcher can't know how best to close arbitrary
296
channel types, so it leaves it up to the approver to do so.
297
For instance, for Text channels it is necessary
298
to acknowledge any messages that have already been displayed to
299
the user first - ideally, the approver would display and then
300
acknowledge the messages.</p>
303
<p>If successful, this method will cause the ChannelDispatchOperation
304
object to disappear, emitting
305
<tp:member-ref>Finished</tp:member-ref>, in the same way as for
306
<tp:member-ref>HandleWith</tp:member-ref>.</p>
308
<p>This method may fail because the dispatch operation has already
309
been completed. Again, see HandleWith for more details. The approver
310
MUST NOT attempt to interact with the channels further in this
313
<p>(FIXME: list some other possible errors)</p>
317
<tp:error name="org.freedesktop.Telepathy.Error.NotYours">
319
At the time that Claim was called, this dispatch operation was
320
processing a call to HandleWith which has now succeeded, so
321
some Handler nominated by another approver is now responsible for
325
</tp:possible-errors>
328
<signal name="Finished" tp:name-for-bindings="Finished">
329
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
330
<p>Emitted when this dispatch operation finishes. The dispatch
331
operation is no longer present and further methods must not be
334
<p>Its object path SHOULD NOT be reused for a subsequent dispatch
335
operation; the ChannelDispatcher MUST choose object paths
336
in a way that avoids immediate re-use.</p>
339
<p>Otherwise, clients might accidentally call
340
<tp:member-ref>HandleWith</tp:member-ref> or
341
<tp:member-ref>Claim</tp:member-ref> on a new dispatch operation
342
instead of the one they intended to handle.</p>
349
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Channel_Dispatch_Operation.xml
