2
<node name="/Connection_Interface_Requests"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
5
<tp:copyright>Copyright (C) 2008 Collabora Limited</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, MA 02110-1301,
24
<interface name="org.freedesktop.Telepathy.Connection.Interface.Requests">
25
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
26
<tp:added version="0.17.11">(as stable API)</tp:added>
28
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
29
<p>An enhanced version of the Telepathy connection interface, which can
30
represent bundles of channels that should be dispatched together, and
31
does not assume any particular properties by which channels are
32
uniquely identifiable.</p>
35
<tp:struct name="Channel_Details" array-name="Channel_Details_List">
36
<tp:added version="0.17.11">(as stable API)</tp:added>
39
Enough details of a channel that clients can work out how to dispatch
43
<tp:member name="Channel" type="o">
45
The object path of the channel.
49
<tp:member name="Properties" type="a{sv}"
50
tp:type="Qualified_Property_Value_Map">
51
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
52
<p>Properties of the channel.</p>
54
<p>Connection managers MUST NOT include properties in this mapping
55
if their values can change. Clients MUST ignore properties
56
that appear in this mapping if their values can change.</p>
59
<p>If properties that could change were included, the following
60
race condition would be likely to exist in some cases:</p>
63
<li>NewChannels or Get("Channels") includes a property P with
65
<li>Client creates a proxy object for the channel</li>
66
<li>The value of P changes to V2</li>
67
<li>Client connects to PChanged signal</li>
68
<li>Client should call Get("P") or GetAll here, to avoid the
69
race, but client's author has forgotten to do so</li>
70
<li>Proxy object thinks P == V1, but actually P == V2</li>
73
<p>We've taken the opportunity to make the API encourage the
74
client author to get it right. Where possible, we intend that
75
properties whose value will be used in channel dispatching
76
or other "early" processing will be defined so that they are
77
immutable (can never change).</p>
80
<p>Each dictionary MUST contain the keys
81
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
82
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
83
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>,
84
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>
86
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>.
90
<p>We expect these to be crucial to the channel-dispatching
97
<method name="CreateChannel" tp:name-for-bindings="Create_Channel">
98
<tp:added version="0.17.11">(as stable API)</tp:added>
99
<tp:changed version="0.17.14">It is now guaranteed that
100
CreateChannel returns the channel before NewChannels announces it
101
(the reverse was previously guaranteed).</tp:changed>
103
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
104
<p>Request that an entirely new channel is created.</p>
107
<p>There is deliberately no flag corresponding to the
108
suppress_handler argument to
109
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>,
110
because passing a FALSE value for that argument is deprecated.
111
Requests made using this interface always behave as though
112
suppress_handler was TRUE.</p>
117
<arg direction="in" name="Request" type="a{sv}"
118
tp:type="Qualified_Property_Value_Map">
119
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
120
<p>A dictionary containing desirable properties, which MUST include
122
namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>.
124
are defined such that only an exact match makes sense, and
125
connection managers MUST NOT satisfy a request with a channel
126
where that property does not match; some properties are defined
127
such that the connection manager MAY treat the request as merely
128
a hint, and make a best-effort attempt to satisfy it. This is
129
documented separately for each property.</p>
131
<p>If this dictionary contains a property whose semantics
132
are not known to the connection manager, this method MUST fail
133
without side-effects (in particular it must not create a new
137
<p>This is necessary if we want to be able to invent properties
138
in future that, when used in a request, are hard requirements
139
rather than just hints. A connection manager that did not know
140
the semantics of those properties could incorrectly return a
141
new channel that did not satisfy the requirements.</p>
144
<p>The connection manager MUST NOT respond successfully,
145
and SHOULD NOT create a new channel or cause any other
146
side-effects, unless it can create a new channel that satisfies
147
the client's requirements.</p>
149
<p>Properties that will be set by this argument need not have write
150
access after the channel has been created - indeed, it is
151
expected that most will be read-only.</p>
155
<arg name="Channel" direction="out" type="o">
156
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
157
<p>The Channel object, which MUST NOT be signalled with
158
<tp:member-ref>NewChannels</tp:member-ref> until after this method
162
<p>This allows the requester to alter its handling of
163
NewChannels by knowing whether one of the channels satisfied
164
a request it made.</p>
169
<arg name="Properties" direction="out" type="a{sv}"
170
tp:type="Qualified_Property_Value_Map">
171
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
172
<p>Properties of the channel that was produced, equivalent to
173
the properties in <tp:type>Channel_Details</tp:type>.
174
Connection managers MUST NOT include properties here whose
175
values can change, for the same reasons as in
176
<tp:type>Channel_Details</tp:type>.</p>
181
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
182
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
183
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
185
The channel request was one that can never succeed,
186
such as requesting an unsupported channel type, or requesting
187
a channel type which this connection manager does not support with
188
the given target handle type.
191
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
193
An invalid handle was requested as the value of a property whose
194
value is a handle (like
195
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
196
or a syntactically invalid identifier was requested as the value
197
of a property whose value is the string corresponding to a handle
199
namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
202
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
204
The request matched the fixed properties of a
205
<tp:type>Requestable_Channel_Class</tp:type> in
206
<tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
207
allowed arguments did not make sense; for example, a <tp:dbus-ref
208
namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
209
was requested, but the <tp:dbus-ref
210
namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
211
property provided was not a valid DNS name.
214
<tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
216
The requested channel cannot be created because the requested
217
contact is using a client that lacks a particular feature.
220
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
221
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
222
<p>The requested channel cannot be created, but in
223
principle, a similar request might succeed in future.
224
For instance, this might be because:</p>
227
<li>a channel matching the request already exists and the
228
protocol requires that only one such channel can exist at a
230
<li>a channel matching the request has already been requested
231
(by a previous call to CreateChannel,
232
<tp:member-ref>EnsureChannel</tp:member-ref>,
234
namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
235
or similar) and the protocol requires that only one such
236
channel can exist at a time</li>
240
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
241
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
242
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
243
</tp:possible-errors>
246
<method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
247
<tp:added version="0.17.12"/>
248
<tp:changed version="0.17.14">It is now guaranteed that if
249
the channel was created by this call to EnsureChannel, it's returned
250
before NewChannels announces it (the reverse was previously
251
guaranteed).</tp:changed>
253
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
254
<p>Request that channels are ensured to exist.</p>
257
<p>The connection manager is in the best position to determine which
258
existing channels could satisfy which requests.</p>
263
<arg direction="in" name="Request" type="a{sv}"
264
tp:type="Qualified_Property_Value_Map">
265
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
266
<p>A dictionary containing desirable properties, with the same
267
semantics as the corresponding parameter to
268
<tp:member-ref>CreateChannel</tp:member-ref>.</p>
272
<arg name="Yours" direction="out" type="b">
273
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
274
<p>If false, the caller of EnsureChannel MUST assume that some
275
other process is handling this channel; if true, the caller of
276
EnsureChannel SHOULD handle it themselves or delegate it to another
279
<p>If the creation of a channel makes several calls to EnsureChannel
280
(and no other requests) successful, exactly one of those calls MUST
281
return a true value for this argument.</p>
283
<p>If the creation of a channel makes other requests successful,
284
the value returned for this argument MUST be such that exactly
285
one of the clients making requests ends up responsible for the
286
channel. In particular, if
287
<tp:member-ref>CreateChannel</tp:member-ref> returns a channel
288
<em>C</em>, any EnsureChannel calls that also return <em>C</em>
289
MUST return a false value for this argument.</p>
293
<arg name="Channel" direction="out" type="o">
295
The Channel object. If it was created as a result of this method
296
call, it MUST NOT be signalled by
297
<tp:member-ref>NewChannels</tp:member-ref> until after this method
301
<p>This allows the requester to alter its handling of
302
NewChannels by knowing whether one of the channels satisfied
303
a request it made.</p>
308
<arg name="Properties" direction="out" type="a{sv}"
309
tp:type="Qualified_Property_Value_Map">
310
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
311
<p>Properties of the channel that was produced, equivalent to
312
the properties in <tp:type>Channel_Details</tp:type>.
313
Connection managers MUST NOT include properties here whose
314
values can change, for the same reasons as in
315
<tp:type>Channel_Details</tp:type>.</p>
320
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
321
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
322
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
324
The channel request was one that can never succeed,
325
such as requesting an unsupported channel type, or requesting
326
a channel type which this connection manager does not support with
327
the given target handle type.
330
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
332
An invalid handle was requested as the value of a property whose
333
value is a handle (like
334
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
335
or a syntactically invalid identifier was requested as the value
336
of a property whose value is the string corresponding to a handle
338
namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
341
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
343
The request matched the fixed properties of a
344
<tp:type>Requestable_Channel_Class</tp:type> in
345
<tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
346
allowed arguments did not make sense; for example, a <tp:dbus-ref
347
namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
348
was requested, but the <tp:dbus-ref
349
namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
350
property provided was not a valid DNS name.
353
<tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
355
The requested channel cannot be created because the requested
356
contact is using a client that lacks a particular feature.
359
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
361
The requested channel cannot be created, but in
362
principle, a similar request might succeed in future.
365
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
366
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
367
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
368
</tp:possible-errors>
371
<signal name="NewChannels" tp:name-for-bindings="New_Channels">
372
<tp:added version="0.17.11">(as stable API)</tp:added>
373
<tp:changed version="0.17.14">Added a guarantee of ordering
374
relative to NewChannel</tp:changed>
376
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
377
<p>New channels have been created. The connection manager SHOULD emit
378
a single signal for any group of closely related channels that are
379
created at the same time, so that the channel dispatcher can try to
380
dispatch them to a handler as a unit.</p>
382
<p>In particular, if additional channels are created as a side-effect
383
of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
384
these channels SHOULD appear in the same NewChannels signal as
385
the channel that satisfies the request.</p>
388
<p>Joining a MUC Tube in XMPP requires joining the corresponding
389
MUC (chatroom), so a <tp:dbus-ref
390
namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
391
channel can be created as a side-effect.</p>
394
<p>Every time NewChannels is emitted, it MUST be followed by
396
namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
397
signal for each channel.</p>
400
<p>The double signal emission is for the benefit of older Telepathy
401
clients, which won't be listening for NewChannels.</p>
403
<p>The more informative NewChannels signal comes first so that
404
clients that did not examine the connection to find
405
out whether Requests is supported will see the more informative
406
signal for each channel first, and then ignore the less
407
informative signal because it announces a new channel of which
408
they are already aware.</p>
412
<arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
414
The channels and their details. All channels that are signalled
415
together like this MUST have the same
416
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
418
either refer to an existing bundle, or establish a new bundle.
423
<property name="Channels" tp:name-for-bindings="Channels"
424
type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
425
<tp:added version="0.17.11">(as stable API)</tp:added>
427
A list of all the channels which currently exist on this connection.
428
Change notification is via the
429
<tp:member-ref>NewChannels</tp:member-ref> and
430
<tp:member-ref>ChannelClosed</tp:member-ref> signals.
434
<signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed">
435
<tp:added version="0.17.11">(as stable API)</tp:added>
437
Emitted when a channel is closed and hence disappears from the
438
<tp:member-ref>Channels</tp:member-ref> property.
441
This is redundant with the <tp:dbus-ref
442
namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>
443
signal on the channel itself, but it does provide full change
444
notification for the Channels property.
448
<arg name="Removed" type="o">
450
The channel which has been removed from the Channels property
455
<tp:mapping name="Channel_Class" array-name="Channel_Class_List">
456
<tp:added version="0.17.11">(as stable API)</tp:added>
457
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
458
<p>Mapping representing a class of channels that can be requested
459
from a connection manager, can be handled by a user interface,
460
are supported by a contact, etc.</p>
462
<p>Classes of channel are identified by the fixed values of
463
a subset of their properties.</p>
465
<p>Channel classes SHOULD always include the keys
466
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
468
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
472
<tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
474
A D-Bus interface name, followed by a dot and a D-Bus property name.
478
<tp:member type="v" name="Value">
480
The value of the property.
485
<tp:struct name="Requestable_Channel_Class"
486
array-name="Requestable_Channel_Class_List">
487
<tp:added version="0.17.11">(as stable API)</tp:added>
488
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
489
<p>Structure representing a class of channels that can be requested,
490
identified by a set of properties that identify that class of
494
<p>This will often just be the channel type and the handle type,
495
but can include other properties of the channel - for instance,
496
encrypted channels might require properties that
497
unencrypted channels do not, like an encryption key.</p>
500
<p>In some cases, these classes of channel may overlap, in the sense
501
that one class fixes all the properties that another class does,
502
plus some more properties.</p>
505
<p>For older clients to still be able to understand how to request
506
channels in the presence of a hypothetical "encryption" interface,
507
we'd need to represent it like this:</p>
510
<li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
511
<li>class 2: Channel.ChannelType = Text,
512
Channel.TargetHandleType = CONTACT,
513
Encryption.Encrypted = TRUE</li>
518
<tp:member name="Fixed_Properties" type="a{sv}"
519
tp:type="Channel_Class">
520
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
521
<p>The property values that identify this requestable channel class.
522
These properties MUST be included in requests for a channel of this
523
class, and MUST take these values.</p>
525
<p>Clients that do not understand the semantics of all the
526
Fixed_Properties MUST NOT request channels of this class, since
527
they would be unable to avoid making an incorrect request.</p>
529
<p>This implies that connection managers wishing to make channels
530
available to old or minimal clients SHOULD have a channel class
531
with the minimum number of Fixed_Properties, and MAY additionally
532
have channel classes with extra Fixed_Properties.</p>
536
<tp:member name="Allowed_Properties" type="as"
537
tp:type="DBus_Qualified_Member[]">
538
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
539
<p>Properties that MAY be set when requesting a channel of this
540
channel type and handle type.</p>
542
<p>This array MUST NOT include properties that are in the
543
Fixed_Properties mapping.</p>
545
<p>Properties in this array may either be required or optional,
546
according to their documented semantics.</p>
550
TargetHandleType takes a value that is not Handle_Type_None,
551
one or the other of TargetHandle and TargetID is required.
552
Clients are expected to understand the documented relationship
553
between the properties, so we do not have separate arrays
554
of required and optional properties.</p>
557
<p>If this array contains the
558
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
559
property, then this class of channel can be combined with other
560
channels with that property in a request, or added to an existing
561
bundle. If not, this signifies that the connection manager is
562
unable to mark channels of this class as part of a bundle - this
563
means that to the remote contact they are likely to be
564
indistinguishable from channels requested separately.</p>
569
<property name="RequestableChannelClasses" access="read"
570
type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
571
tp:name-for-bindings="Requestable_Channel_Classes">
572
<tp:added version="0.17.11">(as stable API)</tp:added>
573
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
574
<p>The classes of channel that are expected to be available on this
575
connection, i.e. those for which
576
<tp:member-ref>CreateChannel</tp:member-ref> can reasonably
577
be expected to succeed. User interfaces can use this information
578
to show or hide UI components.</p>
580
<p>This property cannot change after the connection has gone to
581
state Connection_Status_Connected, so there is no change
582
notification (if the connection has context-dependent capabilities,
583
it SHOULD advertise support for all classes of channel that it might
584
support during its lifetime). Before this state has been reached,
585
the value of this property is undefined.</p>
588
<p>This is not on an optional interface, because connection
589
managers can always offer some sort of clue about the channel
590
classes they expect to support (at worst, they can announce
591
support for everything for which they have code).</p>
598
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Connection_Interface_Requests.xml
