« back to all changes in this revision
Viewing changes to spec/Channel.xml
- browse files at revision 9
- compare with another revision
- download diff
- download tarball
- view history from revision 9
- Committer: Bazaar Package Importer
- Author(s): Jonny Lamb
- Date: 2009-02-16 10:47:31 UTC
- mfrom: (7.1.14 jaunty)
- Revision ID: james.westby@ubuntu.com-20090216104731-3l467x71wygwok32
Tags: 0.15.6-2
debian/control: Added myself to Uploaders.
- files added:
- debian/README.source
- files modified:
- MANIFEST.in
added
removed
spec/Channel.xml
1
1
<?xml version="1.0" ?>
2
2
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
<tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
4
<tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
3
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
4
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
5
5
<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
6
6
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
7
<p>This library is free software; you can redistribute it and/or
19
19
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
20
20
</tp:license>
21
21
<interface name="org.freedesktop.Telepathy.Channel">
22
<method name="Close">
22
23
<property name="ChannelType" type="s" tp:type="DBus_Interface"
24
access="read" tp:name-for-bindings="Channel_Type">
25
<tp:added version="0.17.7"/>
26
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
27
<p>The channel's type. This cannot change once the channel has
28
been created.</p>
29
30
<p>For compatibility between older connection managers and newer
31
clients, if this is unavailable or is an empty string,
32
clients MUST use the result of calling
33
<tp:member-ref>GetChannelType</tp:member-ref>.</p>
34
35
<tp:rationale>
36
The GetAll method lets clients retrieve all properties in one
37
round-trip, which is desirable.
38
</tp:rationale>
39
40
<p>When requesting a channel, the request MUST specify a channel
41
type, and the request MUST fail if the specified channel type
42
cannot be supplied.</p>
43
44
<tp:rationale>
45
Common sense.
46
</tp:rationale>
47
</tp:docstring>
48
</property>
49
50
<property name="Interfaces" tp:name-for-bindings="Interfaces"
51
type="as" tp:type="DBus_Interface[]" access="read">
52
<tp:added version="0.17.7"/>
53
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
54
<p>Extra interfaces provided by this channel. This SHOULD NOT include
55
the channel type and the Channel interface itself, and cannot
56
change once the channel has been created.</p>
57
58
<p>For compatibility between older connection managers and newer
59
clients, if this is unavailable, or if this is an empty list and
60
<tp:member-ref>ChannelType</tp:member-ref> is an empty string,
61
clients MUST use the result of calling
62
<tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an
63
empty list but ChannelType is non-empty, clients SHOULD NOT call
64
GetInterfaces; this implies that connection managers that implement
65
the ChannelType property MUST also implement the Interfaces property
66
correctly.</p>
67
68
<tp:rationale>
69
The GetAll method lets clients retrieve all properties in one
70
round-trip, which is desirable.
71
</tp:rationale>
72
73
<p>When requesting a channel with a particular value for this
74
property, the request must fail without side-effects unless the
75
connection manager expects to be able to provide a channel whose
76
interfaces include at least the interfaces requested.</p>
77
</tp:docstring>
78
</property>
79
80
<property name="TargetHandle" type="u" access="read" tp:type="Handle"
81
tp:name-for-bindings="Target_Handle">
82
<tp:added version="0.17.7"/>
83
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
84
<p>The handle (a representation for the identifier) of the contact,
85
chatroom, etc. with which this handle communicates. Its type
86
is given by the <tp:member-ref>TargetHandleType</tp:member-ref>
87
property.</p>
88
89
<p>This is fixed for the lifetime of the channel, so channels which
90
could potentially be used to communicate with multiple contacts
91
(such as streamed media calls defined by their members, or ad-hoc
92
chatrooms like MSN switchboards) must have TargetHandleType set
93
to Handle_Type_None and TargetHandle set to 0.</p>
94
95
<p>Unlike in the telepathy-spec 0.16 API, there is no particular
96
uniqueness guarantee - there can be many channels with the same
97
(channel type, handle type, handle) tuple. This is necessary
98
to support conversation threads in XMPP and SIP, for example.</p>
99
100
<p>If this is present in a channel request, it must be nonzero,
101
<tp:member-ref>TargetHandleType</tp:member-ref>
102
MUST be present and not Handle_Type_None, and
103
<tp:member-ref>TargetID</tp:member-ref> MUST NOT be
104
present.</p>
105
106
<p>The channel that satisfies the request MUST either:</p>
107
108
<ul>
109
<li>have the specified TargetHandle property; or</li>
110
<li>have <tp:member-ref>TargetHandleType</tp:member-ref> =
111
Handle_Type_None, TargetHandle = 0, and be configured such that
112
it could communicate with the specified handle in some other way
113
(e.g. have the requested contact handle in its Group
114
interface)</li>
115
</ul>
116
</tp:docstring>
117
</property>
118
119
<property name="TargetID" tp:name-for-bindings="Target_ID"
120
type="s" access="read">
121
<tp:added version="0.17.9"/>
122
123
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
124
<p>The string that would result from inspecting the
125
<tp:member-ref>TargetHandle</tp:member-ref>
126
property (i.e. the identifier in the IM protocol of the contact,
127
room, etc. with which this channel communicates), or the empty
128
string if the TargetHandle is 0.</p>
129
130
<tp:rationale>
131
<p>The presence of this property avoids the following race
132
condition:</p>
133
134
<ul>
135
<li>New channel C is signalled with target handle T</li>
136
<li>Client calls <tp:dbus-ref
137
namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
138
[T])</li>
139
<li>Channel C closes, removing the last reference to handle T</li>
140
<li><tp:dbus-ref
141
namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
142
[T]) returns an error</li>
143
</ul>
144
</tp:rationale>
145
146
<p>If this is present in a channel request,
147
<tp:member-ref>TargetHandleType</tp:member-ref>
148
MUST be present and not Handle_Type_None, and
149
<tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be
150
present. The request MUST fail with error InvalidHandle, without
151
side-effects, if the requested TargetID would not be accepted by
152
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>
153
154
<p>The returned channel must be related to the handle corresponding
155
to the given identifier, in the same way as if TargetHandle
156
had been part of the request instead.</p>
157
158
<tp:rationale>
159
<p>Requesting channels with a string identifier saves a round-trip
160
(the call to RequestHandles). It also allows the channel
161
dispatcher to accept a channel request for an account that is not
162
yet connected (and thus has no valid handles), bring the account
163
online, and pass on the same parameters to the new connection's
164
CreateChannel method.</p>
165
</tp:rationale>
166
</tp:docstring>
167
</property>
168
169
<property name="TargetHandleType" type="u" access="read"
170
tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type">
171
<tp:added version="0.17.7"/>
172
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
173
<p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p>
174
175
<p>If this is omitted from a channel request, connection managers
176
SHOULD treat this as equivalent to Handle_Type_None.</p>
177
178
<p>If this is omitted or is Handle_Type_None,
179
<tp:member-ref>TargetHandle</tp:member-ref> and
180
<tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the
181
request.</p>
182
</tp:docstring>
183
</property>
184
185
<method name="Close" tp:name-for-bindings="Close">
23
186
<tp:docstring>
24
187
Request that the channel be closed. This is not the case until
25
the Closed signal has been emitted, and depending on the connection
188
the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and
189
depending on the connection
26
190
manager this may simply remove you from the channel on the server,
27
191
rather than causing it to stop existing entirely. Some channels
28
192
such as contact list channels may not be closed.
43
207
</tp:error>
44
208
</tp:possible-errors>
45
209
</method>
46
<signal name="Closed">
210
211
<signal name="Closed" tp:name-for-bindings="Closed">
47
212
<tp:docstring>
48
213
Emitted when the channel has been closed. Method calls on the
49
214
channel are no longer valid after this signal has been emitted,
51
216
at any point.
52
217
</tp:docstring>
53
218
</signal>
54
<method name="GetChannelType">
219
220
<method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type">
221
<tp:deprecated version="0.17.7">Use the ChannelType
222
property if possible.</tp:deprecated>
55
223
<arg direction="out" type="s" tp:type="DBus_Interface">
56
224
<tp:docstring>The interface name</tp:docstring>
57
225
</arg>
58
226
<tp:docstring>
59
Returns the interface name for the type of this channel.
227
Returns the interface name for the type of this channel. Clients
228
SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property
229
instead, falling back to this method only if necessary.
230
231
<tp:rationale>
232
The GetAll method lets clients retrieve all properties in one
233
round-trip.
234
</tp:rationale>
60
235
</tp:docstring>
61
236
</method>
62
<method name="GetHandle">
237
238
<method name="GetHandle" tp:name-for-bindings="Get_Handle">
239
<tp:deprecated version="0.17.7">Use the TargetHandleType
240
and TargetHandle properties if possible.</tp:deprecated>
63
241
<arg direction="out" type="u" tp:type="Handle_Type">
64
242
<tp:docstring>
65
The handle type, or zero if this channel does not correspond to any
66
particular handle
243
The same as TargetHandleType.
67
244
</tp:docstring>
68
245
</arg>
69
246
<arg direction="out" type="u" tp:type="Handle">
70
247
<tp:docstring>
71
The handle, or zero if this channel does not correspond to any
72
particular handle
248
The same as TargetHandle.
73
249
</tp:docstring>
74
250
</arg>
75
251
<tp:docstring>
76
252
Returns the handle type and number if this channel represents a
77
253
communication with a particular contact, room or server-stored list, or
78
zero if it is transient and defined only by its contents.
254
zero if it is transient and defined only by its contents. Clients
255
SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and
256
<tp:member-ref>TargetHandleType</tp:member-ref> properties instead,
257
falling back to this method only if necessary.
258
259
<tp:rationale>
260
The GetAll method lets clients retrieve all properties in one
261
round-trip.
262
</tp:rationale>
79
263
</tp:docstring>
80
264
</method>
81
<method name="GetInterfaces">
265
266
<method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
267
<tp:deprecated version="0.17.7">Use the Interfaces
268
property if possible.</tp:deprecated>
82
269
<arg direction="out" type="as" tp:type="DBus_Interface[]">
83
270
<tp:docstring>
84
271
An array of the D-Bus interface names
86
273
</arg>
87
274
<tp:docstring>
88
275
Get the optional interfaces implemented by the channel.
276
Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref>
277
property instead, falling back to this method only if necessary.
278
279
<tp:rationale>
280
The GetAll method lets clients retrieve all properties in one
281
round-trip.
282
</tp:rationale>
89
283
</tp:docstring>
90
284
</method>
285
286
<property name="Requested" tp:name-for-bindings="Requested"
287
type="b" access="read">
288
<tp:added version="0.17.13">(as stable API)</tp:added>
289
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
290
<p>True if this channel was created in response to a local request,
291
such as a call to
292
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
293
or
294
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>
295
296
<tp:rationale>
297
<p>The idea of this property is to distinguish between "incoming"
298
and "outgoing" channels, in a way that doesn't break down when
299
considering special cases like contact lists that are automatically
300
created on connection to the server, or chatrooms that an
301
IRC proxy/bouncer like irssi-proxy or bip was already in.</p>
302
303
<p>The reason we want to make that distinction is that UIs for
304
things that the user explicitly requested should start up
305
automatically, whereas for incoming messages and VoIP calls we
306
should first ask the user whether they want to open the messaging
307
UI or accept the call.</p>
308
</tp:rationale>
309
310
<p>If the channel was not explicitly requested (even if it was
311
created as a side-effect of a call to one of those functions,
312
e.g. because joining a Tube in a MUC context on XMPP implies
313
joining that MUC), then this property is false.</p>
314
315
<p>For compatibility with older connection managers, clients SHOULD
316
assume that this property is true if they see a channel announced
317
by the
318
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
319
signal with the suppress_handler parameter set to true.</p>
320
321
<tp:rationale>
322
<p>In a correct connection manager, the only way to get such a
323
channel is to request it.</p>
324
</tp:rationale>
325
326
<p>Clients MAY additionally assume that this property is false
327
if they see a channel announced by the NewChannel signal with the
328
suppress_handler parameter set to false.</p>
329
330
<tp:rationale>
331
<p>This is more controversial, since it's possible to get that
332
parameter set to false by requesting a channel. However, there's
333
no good reason to do so, and we've deprecated this practice.</p>
334
335
<p>In the particular case of the channel dispatcher, the only
336
side-effect of wrongly thinking a channel is unrequested
337
is likely to be that the user has to confirm that they want to
338
use it, so it seems fairly harmless to assume in the channel
339
dispatcher that channels with suppress_handler false are
340
indeed unrequested.</p>
341
</tp:rationale>
342
</tp:docstring>
343
</property>
344
345
<property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
346
access="read" tp:name-for-bindings="Initiator_Handle">
347
<tp:added version="0.17.13">(as stable API)</tp:added>
348
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
349
<p>The contact who initiated the channel. For channels requested by the
350
local user, this MUST be the value of
351
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
352
at the time the channel was created (i.e. not a channel-specific
353
handle).</p>
354
355
<tp:rationale>
356
<p>The careful wording about the self-handle is because the Renaming
357
interface can cause the return from Connection.GetSelfHandle to
358
change. It's something of a specification bug that we don't signal
359
this in the Connection interface yet.</p>
360
</tp:rationale>
361
362
<p>For channels requested by a remote user, this MUST be their handle.
363
If unavailable or not applicable, this MUST be 0 (for instance,
364
contact lists are not really initiated by anyone in particular, and
365
it's easy to imagine a protocol where chatroom invitations can be
366
anonymous).</p>
367
368
<p>For channels with the <tp:dbus-ref
369
namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
370
interface, this SHOULD be the same
371
contact who is signalled as the "Actor" causing the self-handle
372
to be placed in the local-pending set.</p>
373
374
<p>This SHOULD NOT be a channel-specific handle, if possible.</p>
375
376
<p>It does not make sense for this property to be in channel
377
requests - the initiator will always be the local user - so it
378
MUST NOT be accepted.</p>
379
</tp:docstring>
380
</property>
381
382
<property name="InitiatorID" type="s" access="read"
383
tp:name-for-bindings="Initiator_ID">
384
<tp:added version="0.17.13">(as stable API)</tp:added>
385
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
386
<p>The string that would result from inspecting the
387
<tp:member-ref>InitiatorHandle</tp:member-ref>
388
property (i.e. the initiator's identifier in the IM protocol).</p>
389
390
<tp:rationale>
391
<p>The presence of this property avoids the following race
392
condition:</p>
393
394
<ul>
395
<li>New StreamedMedia channel C is signalled with initiator
396
handle I</li>
397
<li>Client calls <tp:dbus-ref
398
namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
399
[I])</li>
400
<li>Channel C closes, removing the last reference to handle I</li>
401
<li><tp:dbus-ref
402
namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
403
[I]) returns an error</li>
404
<li>Client can indicate that a call was missed, but not who
405
called!</li>
406
</ul>
407
</tp:rationale>
408
409
<p>It does not make sense for this property to be in channel
410
requests - the initiator will always be the local user - so it
411
MUST NOT be accepted.</p>
412
</tp:docstring>
413
</property>
414
91
415
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
92
416
<p>All communication in the Telepathy framework is carried out via channel
93
417
objects which are created and managed by connections. This interface must
94
418
be implemented by all channel objects, along with one single channel type,
95
such as Channel.Type.ContactList which represents a list of people (such
96
as a buddy list) or a Channel.Type.Text which represents a channel over
97
which textual messages are sent and received.</p>
419
such as <tp:dbus-ref
420
namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref>
421
which represents a list of people (such as a buddy list) or a <tp:dbus-ref
422
namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which
423
represents a channel over which textual messages are sent and received.</p>
424
425
<p>Each Channel's object path MUST start with the object path of
426
its associated <tp:dbus-ref
427
namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed
428
by '/'. There MAY be any number of additional object-path components,
429
which clients MUST NOT attempt to parse.</p>
430
431
<tp:rationale>
432
<p>This ensures that Channel object paths are unique, even between
433
Connections and CMs, because Connection object paths are
434
guaranteed-unique via their link to the well-known bus name.</p>
435
436
<p>If all connection managers in use are known to comply with at least
437
spec version 0.17.10, then the Connection's object path can
438
even be determined from the Channel's without any additional
439
information, by taking the first 7 components.</p>
440
</tp:rationale>
98
441
99
442
<p>Each channel may have an immutable handle associated with it, which
100
443
may be any handle type, such as a contact, room or list handle,
101
indicating that the channel is for communicating with that handle.
102
There can be at most one channel for each combination of
103
(channel type, handle type, handle) with nonzero handle type.</p>
104
105
<p>If a channel does not have a handle (an "anonymous channel"), it
444
indicating that the channel is for communicating with that handle.</p>
445
446
<p>If a channel does not have a handle (an "anonymous channel" with
447
Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it
106
448
means that the channel is defined by some other terms, such as it
107
449
may be a transient group defined only by its members as visible
108
through the Channel.Interface.Group interface. There can be any number
109
of anonymous channels of the same channel type.</p>
450
through the <tp:dbus-ref
451
namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
452
interface.</p>
110
453
111
454
<p>Other optional interfaces can be implemented to indicate other available
112
functionality, such as Channel.Interface.Group if the channel contains
113
a number of contacts, Channel.Interface.Password to indicate
114
that a channel may have a password set to require entry, and
115
Properties for extra data about channels which represent chat
116
rooms or voice calls. The interfaces implemented may not vary after the
117
channel's creation has been signalled to the bus (with the connection's
118
NewChannel signal).</p>
455
functionality, such as <tp:dbus-ref
456
namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
457
if the channel contains a number of contacts, <tp:dbus-ref
458
namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
459
to indicate that a channel may have a password set to require entry, and
460
<tp:dbus-ref
461
namespace="org.freedesktop.Telepathy">Properties</tp:dbus-ref> for
462
extra data about channels which represent chat rooms or voice calls. The
463
interfaces implemented may not vary after the channel's creation has been
464
signalled to the bus (with the connection's <tp:dbus-ref
465
namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref>
466
signal).</p>
119
467
120
468
<p>Specific connection manager implementations may implement channel types and
121
469
interfaces which are not contained within this specification in order to
126
474
methods or signals with conflicting names, the D-Bus interface names should
127
475
always be used to invoke methods and bind signals.</p>
128
476
</tp:docstring>
477
478
<tp:changed version="0.17.7">Previously we guaranteed that, for
479
any handle type other than Handle_Type_None, and for any channel type
480
and any handle, there would be no more than one channel with that
481
combination of channel type, handle type and handle. This guarantee
482
has now been removed in order to accommodate features like message
483
threads.
484
</tp:changed>
485
486
<tp:changed version="0.17.10">Previously we did not explicitly
487
guarantee that Channels' object paths had the Connection's object path
488
as a prefix.
489
</tp:changed>
129
490
</interface>
130
491
</node>
131
492
<!-- vim:set sw=2 sts=2 et ft=xml: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.1