2
<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
<tp:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright>
4
<tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
6
This library is free software; you can redistribute it and/or
7
modify it under the terms of the GNU Lesser General Public
8
License as published by the Free Software Foundation; either
9
version 2.1 of the License, or (at your option) any later version.
11
This library is distributed in the hope that it will be useful,
12
but WITHOUT ANY WARRANTY; without even the implied warranty of
13
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
Lesser General Public License for more details.
16
You should have received a copy of the GNU Lesser General Public
17
License along with this library; if not, write to the Free Software
18
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20
<interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"
21
tp:causes-havoc="experimental">
22
<tp:added version="0.19.0">(draft 1)</tp:added>
24
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
25
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26
<p>A channel type for making audio and video calls. Call
27
channels supersede the old <tp:dbus-ref
28
namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref>
29
channel type. Call channels are much more flexible than its
30
predecessor and allow more than two participants.</p>
32
<p>Handlers are advised against executing all the media
33
signalling, codec and candidate negotiation themselves but
34
instead use a helper library such as <a
35
href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a>
36
which when given a new Call channel will set up the
37
transports and codecs and create GStreamer pads which
38
can be added to the handler UI. This is useful as it means
39
the handler does not have to worry how exactly the
40
connection between the call participants is being made.</p>
43
namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and
44
<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
45
properties in a Call channel refer to the contact that the
46
user initially called, or which contact initially called the
47
user. Even in a conference call, where there are multiple
48
contacts in the call, these properties refer to the
49
initial contact, who might have left the conference since
50
then. As a result, handlers should not rely on these
56
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects
57
represent the actual media that forms the Call (for example an
58
audio content and a video content). Calls always have one or
59
more Content objects associated with them.</p>
62
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have
63
one or more stream associated with them. More information on
64
these streams and how to maniuplate them can be found on the
65
<tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>
68
<h4>Outgoing calls</h4>
70
<p>To make an audio-only call to a contact <tt>foo@example.com</tt>
71
handlers should call:</p>
75
<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
76
...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
77
namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
78
...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
79
...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
80
...<tp:member-ref>InitialAudio</tp:member-ref>: True,
83
<p>As always, <tp:dbus-ref
84
namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used
86
<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
87
if the contact's handle is already known. To make an audio
88
and video call, the handler should also specify
89
<tp:member-ref>InitialVideo</tp:member-ref> The
90
connection manager SHOULD return a channel whose immutable
91
properties contain the local user as the <tp:dbus-ref
92
namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the
93
remote contact as the <tp:dbus-ref
94
namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>,
95
<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> =
96
<code>True</code> (indicating the call is outgoing).</p>
98
<p>After a new Call channel is requested, the
99
<tp:member-ref>CallState</tp:member-ref> property will be
100
<tp:type>Call_State</tp:type>_Pending_Initiator. As the local
101
user is the initiator, the call must be accepted by the handler
102
by calling the <tp:member-ref>Accept</tp:member-ref> method.
103
At this point, <tp:member-ref>CallState</tp:member-ref> changes
104
to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies
105
that the call is ringing, waiting for the remote contact to
106
accept the call. All changes to
107
<tp:member-ref>CallState</tp:member-ref> property are signalled
108
using the <tp:member-ref>CallStateChanged</tp:member-ref>
111
<p>When the call is accepted by the remote contact, the
112
<tp:member-ref>CallStateChanged</tp:member-ref> signal fires
113
again to show that <tp:member-ref>CallState</tp:member-ref> =
114
<tp:type>Call_State</tp:type>_Accepted.</p>
117
href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a>
118
will signal that a pad is available for the handler to show
119
in the user interface.</p>
121
<h5>Missed calls</h5>
123
<p>If the remote contact does not accept the call in time, then
124
the call can be terminated by the server. Note that this only
125
happens in some protocols. Most XMPP clients, for example, do
126
not do this and rely on the call initiator terminating the call.
127
A missed call is shown in a Call channel by the
128
<tp:member-ref>CallState</tp:member-ref> property changing to
129
<tp:type>Call_State</tp:type>_Ended, and the
130
<tp:member-ref>CallStateReason</tp:member-ref> property changing
132
<tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p>
134
<h5>Rejected calls</h5>
136
<p>If the remote contact decides he or she does not feel like
137
talking to the local user, he or she can reject his or her
138
incoming call. This will be shown in the Call channel by
139
<tp:member-ref>CallState</tp:member-ref> changing to
140
<tp:type>Call_State</tp:type>_Ended and the
141
<tp:member-ref>CallStateReason</tp:member-ref> property
142
changing to (remote contact,
143
<tp:type>Call_State</tp:type>_Change_Reason_User_Requested,
144
"org.freedesktop.Telepathy.Error.Rejected").</p>
146
<h4>Incoming calls</h4>
148
<p>When an incoming call occurs, something like the following
150
namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
151
signal will occur:</p>
155
<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([
156
/org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
158
...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
159
namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
160
...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
161
...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
162
...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42,
163
...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False,
164
...<tp:member-ref>InitialAudio</tp:member-ref>: True,
165
...<tp:member-ref>InitialVideo</tp:member-ref>: True,
166
...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio",
167
...<tp:member-ref>InitialVideoName</tp:member-ref>: "video",
168
...<tp:member-ref>MutableContents</tp:member-ref>: True,
169
}])</pre></blockquote>
171
<p>The <tp:member-ref>InitialAudio</tp:member-ref> and
172
<tp:member-ref>InitialVideo</tp:member-ref> properties show that
173
the call has been started with two contents: one for audio
174
streaming and one for video streaming. The
175
<tp:member-ref>InitialAudioName</tp:member-ref> and
176
<tp:member-ref>InitialVideoName</tp:member-ref> properties also
177
show that the aforementioned audio and video contents have names
178
"audio" and "video".</p>
180
<p>Once the handler has notified the local user that there is an
181
incoming call waiting for acceptance, the handler should call
182
<tp:member-ref>SetRinging</tp:member-ref> to let the CM know.
183
The new channel should also be given to telepathy-farsight to
184
work out how the two participants will connect together.
185
telepathy-farsight will call the appropriate methods on the call's
186
<tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s
187
to negotiate codecs and transports.</p>
189
<p>To pick up the call, the handler should call
190
<tp:member-ref>Accept</tp:member-ref>. The
191
<tp:member-ref>CallState</tp:member-ref> property changes to
192
<tp:type>Call_State</tp:type>_Accepted and once media is
193
being transferred, telepathy-farsight will notify the
194
handler of a new pad to be shown to the local user in the
197
<p>To reject the call, the handler should call the
198
<tp:member-ref>Hangup</tp:member-ref> method. The
199
<tp:member-ref>CallState</tp:member-ref> property will change to
200
<tp:type>Call_State</tp:type>_Ended and the
201
<tp:member-ref>CallStateReason</tp:member-ref> property will
202
change to (self handle,
203
<tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
204
"org.freedesktop.Telepathy.Error.Rejected").</p>
206
<h4>Ongoing calls</h4>
208
<h5>Adding and removing contents</h5>
210
<p>When a call is open, new contents can be added as long as the
212
<tp:member-ref>MutableContents</tp:member-ref> property will let
213
the handler know whether further contents can be added or
214
existing contents removed. An example of this is starting a
215
voice call between a contact and then adding a video content.
216
To do this, the should call
217
<tp:member-ref>AddContent</tp:member-ref> like this:</p>
220
<pre><tp:member-ref>AddContent</tp:member-ref>("video",
221
<tp:type>Media_Stream_Type</tp:type>_Video)</pre>
224
<p>Assuming no errors, the new video content will be added to
225
the call. telepathy-farsight will pick up the new content and
226
perform the transport and codec negotiation automatically.
227
telpathy-farsight will signal when the video is ready to
228
show in the handler's user interface.</p>
230
<p>A similar method is used for removing contents from a call,
231
except that the <tp:dbus-ref
232
namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method
233
is on the <tp:dbus-ref
234
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p>
236
<h5>Ending the call</h5>
238
<p>To end the call, the handler should call the
239
<tp:member-ref>Hangup</tp:member-ref> method. The
240
<tp:member-ref>CallState</tp:member-ref> property will change to
241
<tp:type>Call_State</tp:type>_Ended and
242
<tp:member-ref>CallStateReason</tp:member-ref> will change
244
<tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
245
"org.freedesktop.Telepathy.Error.Cancelled").</p>
247
<p>If the other participant hangs up first then the
248
<tp:member-ref>CallState</tp:member-ref> property will change to
249
<tp:type>Call_State</tp:type>_Ended and
250
<tp:member-ref>CallStateReason</tp:member-ref> will change
252
<tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
253
"org.freedesktop.Telepathy.Error.Terminated").</p>
255
<h4>Multi-party calls</h4>
261
<p>There are many combinations of the
262
<tp:member-ref>CallState</tp:member-ref> and
263
<tp:member-ref>CallStateReason</tp:member-ref> properties which
264
mean different things. Here is a table to try to make these
265
meanings clearer:</p>
269
<th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th>
270
<th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th>
271
<th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th>
272
<th rowspan="2">Meaning</th>
279
<!-- Pending_Initiator -->
282
<td><tp:type>Call_State</tp:type>_Pending_Initiator</td>
284
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
286
<td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td>
288
<!-- Pending_Receiver -->
291
<td><tp:type>Call_State</tp:type>_Pending_Receiver</td>
293
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
295
<td>The outgoing call is waiting for the remote contact to pick up the call.</td>
299
<td><tp:type>Call_State</tp:type>_Pending_Receiver</td>
301
<td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td>
303
<td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td>
308
<td><tp:type>Call_State</tp:type>_Accepted</td>
309
<td>Remote contact handle</td>
310
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
312
<td>The remote contact accepted the outgoing call.</td>
316
<td><tp:type>Call_State</tp:type>_Accepted</td>
318
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
320
<td>The local user accepted the incoming call.</td>
324
<td>True or False</td>
325
<td><tp:type>Call_State</tp:type>_Ended</td>
327
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
328
<td><tp:error-ref>Cancelled</tp:error-ref></td>
329
<td>The local user hung up the incoming or outgoing call.</td>
332
<td>True or False</td>
333
<td><tp:type>Call_State</tp:type>_Ended</td>
334
<td>Remote contact handle</td>
335
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
336
<td><tp:error-ref>Terminated</tp:error-ref></td>
337
<td>The remote contact hung up the incoming or outgoing call.</td>
341
<td><tp:type>Call_State</tp:type>_Ended</td>
342
<td>Remote contact handle</td>
343
<td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td>
345
<td>The outgoing call was not picked up and the call ended.</td>
349
<td><tp:type>Call_State</tp:type>_Ended</td>
350
<td>Remote contact handle</td>
351
<td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
352
<td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td>
353
<td>The incoming call was ended because it was picked up elsewhere.</td>
357
<h4>Requestable channel classes</h4>
360
namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
362
namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels
367
[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
368
...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
369
...<tp:member-ref>InitialVideo</tp:member-ref>: True
371
Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>,
372
...<tp:member-ref>InitialAudio</tp:member-ref>,
373
...<tp:member-ref>InitialAudioName</tp:member-ref>
376
( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
377
...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
378
...<tp:member-ref>InitialAudio</tp:member-ref>: True
380
Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>,
381
...<tp:member-ref>InitialVideo</tp:member-ref>,
382
...<tp:member-ref>InitialVideoName</tp:member-ref>
384
)]</pre></blockquote>
386
<p>Clients aren't allowed to make outgoing calls that have
387
neither initial audio nor initial video. Clearly, CMs
388
which don't support video should leave out the first class and
389
omit <tp:member-ref>InitialVideo</tp:member-ref> from the second
390
class, and vice versa for CMs without audio support.</p>
392
<p>Handlers should not close <tp:dbus-ref
393
namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels
394
without first calling <tp:member-ref>Hangup</tp:member-ref> on
395
the channel. If a Call handler crashes, the <tp:dbus-ref
396
namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call
397
<tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the
398
channel which SHOULD also imply a call to
399
<tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
400
"org.freedesktop.Telepathy.Error.Terminated", "") before
401
actually closing the channel.</p>
405
<method name="SetRinging" tp:name-for-bindings="Set_Ringing">
406
<tp:changed version="0.21.2">renamed from Ringing</tp:changed>
407
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
408
<p>Indicate that the local user has been alerted about the incoming
411
<p>This method is only useful if the
412
channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>
413
property is False, and
414
the <tp:member-ref>CallState</tp:member-ref> is
415
<tp:type>Call_State</tp:type>_Pending_Receiver (an incoming
416
call waiting on the local user to pick up). While this is
417
the case, this method SHOULD change the
418
<tp:member-ref>CallFlags</tp:member-ref> to include
419
<tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the
420
remote contact that the local user has been alerted (if the
421
protocol implements this); repeated calls to this method
422
SHOULD succeed, but have no further effect.</p>
424
<p>In all other states, this method SHOULD fail with the error
429
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
431
The call was <tp:dbus-ref namespace="ofdT.Channel"
432
>Requested</tp:dbus-ref>, so ringing does not make sense.
435
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
437
The call is no longer in state
438
<tp:type>Call_State</tp:type>_Pending_Receiver.
441
</tp:possible-errors>
444
<method name="Accept" tp:name-for-bindings="Accept">
445
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
446
<p>For incoming calls in state
447
<tp:type>Call_State</tp:type>_Pending_Receiver, accept the
448
incoming call; this changes the
449
<tp:member-ref>CallState</tp:member-ref> to
450
<tp:type>Call_State</tp:type>_Accepted.</p>
452
<p>For outgoing calls in state
453
<tp:type>Call_State</tp:type>_Pending_Initiator, actually
454
call the remote contact; this changes the
455
<tp:member-ref>CallState</tp:member-ref> to
456
<tp:type>Call_State</tp:type>_Pending_Receiver.</p>
458
<p>Otherwise, this method SHOULD fail with the error NotAvailable.</p>
460
<p>This method should be called exactly once per Call, by whatever
461
client (user interface) is handling the channel.</p>
463
<p>When this method is called, for each <tp:dbus-ref
464
namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose
465
<tp:dbus-ref namespace="ofdT.Call.Content.DRAFT"
466
>Disposition</tp:dbus-ref> is
467
<tp:type>Call_Content_Disposition</tp:type>_Initial, any
468
streams where the <tp:dbus-ref
469
namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref>
470
is <tp:type>Sending_State</tp:type>_Pending_Send will be
471
moved to <tp:type>Sending_State</tp:type>_Sending as if
472
<tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT"
473
>SetSending</tp:dbus-ref>(True) had been called.</p>
477
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
479
The call is not in one of the states where this method makes sense.
482
</tp:possible-errors>
485
<method name="Hangup" tp:name-for-bindings="Hangup">
487
Request that the call is ended. All contents will be removed
488
from the Call so that the
489
<tp:member-ref>Contents</tp:member-ref> property will be the
493
<arg direction="in" name="Reason"
494
type="u" tp:type="Call_State_Change_Reason">
496
A generic hangup reason.
500
<arg direction="in" name="Detailed_Hangup_Reason"
501
type="s" tp:type="DBus_Error_Name">
503
A more specific reason for the call hangup, if one is available, or
504
an empty string otherwise.
508
<arg direction="in" name="Message" type="s">
510
A human-readable message to be sent to the remote contact(s).
513
XMPP Jingle allows calls to be terminated with a human-readable
520
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
522
The call has already been ended.
525
</tp:possible-errors>
528
<method name="AddContent" tp:name-for-bindings="Add_Content">
530
Request that a new <tp:dbus-ref
531
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type
532
Content_Type is added to the Call. Handlers should check the
533
value of the <tp:member-ref>MutableContents</tp:member-ref>
534
property before trying to add another content as it might not
537
<arg direction="in" name="Content_Name" type="s">
539
<p>The suggested name of the content to add.</p>
542
The content name property should be meaningful, so should
543
be given a name which is significant to the user. The name
544
could be a localized "audio", "video" or perhaps include
545
some string identifying the source, such as a webcam
549
<p>If there is already a content with the same name as this
550
property then a sensible suffix should be added. For example,
551
if this argument is "audio" but a content of the same name
552
already exists, a sensible suffix such as " (1)" is appended
553
to name the new content "audio (1)". A further content with the
554
name "audio" would then be named "audio (2)".</p>
558
<arg direction="in" name="Content_Type" type="u"
559
tp:type="Media_Stream_Type">
561
The media stream type of the content to be added to the
565
<arg direction="out" name="Content" type="o">
567
Path to the newly-created <tp:dbus-ref
568
namespace="org.freedesktop.Telepathy"
569
>Call.Content.DRAFT</tp:dbus-ref> object.
574
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
576
The media stream type given is invalid.
579
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
581
The media stream type requested is not implemented by the
585
<tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
587
The content type requested cannot be added to this
588
call. Examples of why this might be the case include
589
because a second video stream cannot be added, or a
590
content cannot be added when the content set isn't
594
</tp:possible-errors>
597
<signal name="ContentAdded"
598
tp:name-for-bindings="Content_Added">
599
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
600
<p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call"
601
>Content.DRAFT</tp:dbus-ref> is added to the call.</p>
603
<arg name="Content" type="o">
605
Path to the newly-created <tp:dbus-ref namespace="ofdT.Call"
606
>Content.DRAFT</tp:dbus-ref> object.
611
<signal name="ContentRemoved" tp:name-for-bindings="Content_Removed">
612
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
613
<p>Emitted when a <tp:dbus-ref namespace="ofdT.Call"
614
>Content.DRAFT</tp:dbus-ref> is removed from the call.</p>
616
<arg name="Content" type="o">
618
The <tp:dbus-ref namespace="ofdT.Call"
619
>Content.DRAFT</tp:dbus-ref> which was removed.
624
<property name="Contents" type="ao" access="read"
625
tp:name-for-bindings="Contents">
626
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
627
<p>The list of <tp:dbus-ref
628
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that
629
are part of this call. Change notification is via the
630
<tp:member-ref>ContentAdded</tp:member-ref> and
631
<tp:member-ref>ContentRemoved</tp:member-ref> signals.
636
<tp:enum type="u" name="Call_State">
637
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
638
<p>The state of a call, as a whole.</p>
640
<p>The allowed transitions are:</p>
643
<li>Pending_Initiator → Pending_Receiver (for outgoing calls,
644
when <tp:member-ref>Accept</tp:member-ref> is called)</li>
645
<li>Pending_Receiver → Accepted (for incoming calls, when
646
<tp:member-ref>Accept</tp:member-ref> is called; for outgoing
647
calls to a contact, when the remote contact accepts the call;
648
for joining a conference call, when the local user successfully
649
joins the conference)</li>
650
<li>Accepted → Pending_Receiver (when transferred to another
652
<li>any state → Ended (when the call is terminated normally, or
653
when an error occurs)</li>
656
<p>Clients MAY consider unknown values from this enum to be an
657
error - additional values will not be defined after the Call
658
specification is declared to be stable.</p>
661
<tp:enumvalue suffix="Unknown" value = "0">
663
The call state is not known. This call state MUST NOT appear as a
664
value of the <tp:member-ref>CallState</tp:member-ref> property, but
665
MAY be used by client code to represent calls whose state is as yet
669
<tp:enumvalue suffix="Pending_Initiator" value = "1">
671
The initiator of the call hasn't accepted the call yet. This state
672
only makes sense for outgoing calls, where it means that the local
673
user has not yet sent any signalling messages to the remote user(s),
674
and will not do so until <tp:member-ref>Accept</tp:member-ref> is
678
<tp:enumvalue suffix="Pending_Receiver" value = "2">
680
The receiver (the contact being called) hasn't accepted the call yet.
683
<tp:enumvalue suffix="Accepted" value = "3">
685
The contact being called has accepted the call.
688
<tp:enumvalue suffix="Ended" value = "4">
690
The call has ended, either via normal termination or an error.
695
<tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u">
697
A set of flags representing the status of the call as a whole,
698
providing more specific information than the
699
<tp:member-ref>CallState</tp:member-ref>. Many of these flags only make
700
sense in a particular state.
703
<tp:flag suffix="Locally_Ringing" value="1">
705
The local contact has been alerted about the call but has not
706
responded; if possible, the remote contact(s) have been informed of
707
this fact. This flag only makes sense on incoming calls in
708
state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD
709
be set when <tp:member-ref>SetRinging</tp:member-ref> is
710
called successfully, and unset when the state changes.
714
<tp:flag suffix="Queued" value="2">
716
The contact is temporarily unavailable, and the call has been placed
717
in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).
718
This flag only makes sense on outgoing 1-1 calls in
719
state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be
720
set or unset according to informational messages from other
725
<tp:flag suffix="Locally_Held" value="4">
727
The call has been put on hold by the local user, e.g. using
728
the <tp:dbus-ref namespace="ofdT.Channel.Interface"
729
>Hold</tp:dbus-ref> interface. This flag SHOULD only be set
730
if there is at least one Content, and all Contents are
731
locally held; it makes sense on calls in state
732
<tp:type>Call_State</tp:type>_Pending_Receiver
733
or <tp:type>Call_State</tp:type>_Accepted.
736
Otherwise, in transient situations where some but not all contents
737
are on hold, UIs would falsely indicate that the call as a whole
738
is on hold, which could lead to the user saying something they'll
739
regret, while under the impression that the other contacts can't
745
<tp:flag suffix="Forwarded" value="8">
747
The initiator of the call originally called a contact other than the
748
current recipient of the call, but the call was then forwarded or
749
diverted. This flag only makes sense on outgoing calls, in state
750
<tp:type>Call_State</tp:type>_Pending_Receiver or
751
<tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset
752
according to informational messages from other contacts.
756
<tp:flag suffix="In_Progress" value="16">
758
Progress has been made in placing the outgoing call, but the
759
contact may not have been made aware of the call yet
760
(so the Ringing state is not appropriate). This corresponds to SIP's
761
status code 183 Session Progress, and could be used when the
762
outgoing call has reached a gateway, for instance.
763
This flag only makes sense on outgoing calls in state
764
<tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set
765
or unset according to informational messages from servers, gateways
766
and other infrastructure.
770
<tp:flag suffix="Clearing" value="32">
772
This flag only occurs when the CallState is Ended. The call with
773
this flag set has ended, but not all resources corresponding to the
774
call have been freed yet.
776
Depending on the protocol there might be some audible feedback while
777
the clearing flag is set.
780
In calls following the ITU-T Q.931 standard there is a period of
781
time between the call ending and the underlying channel being
782
completely free for re-use.
787
<tp:flag suffix="Muted" value="64">
789
The call has been muted by the local user, e.g. using the
790
<tp:dbus-ref namespace="ofdT.Call.Content.Interface"
791
>Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only
792
be set if there is at least one Content, and all Contents
793
are locally muted; it makes sense on calls in state
794
<tp:type>Call_State</tp:type>_Pending_Receiver or
795
<tp:type>Call_State</tp:type>_Accepted.
800
<property name="CallStateDetails"
801
tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read">
802
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
803
<p>A map used to provide optional extensible details for the
804
<tp:member-ref>CallState</tp:member-ref>,
805
<tp:member-ref>CallFlags</tp:member-ref> and/or
806
<tp:member-ref>CallStateReason</tp:member-ref>.</p>
808
<p>Well-known keys and their corresponding value types include:</p>
811
<dt>hangup-message - s</dt>
812
<dd>An optional human-readable message sent when the call was ended,
813
corresponding to the Message argument to the
814
<tp:member-ref>Hangup</tp:member-ref> method. This is only
815
applicable when the call state is <tp:type>Call_State</tp:type>_Ended.
817
XMPP Jingle can send such messages.
821
<dt>queue-message - s</dt>
822
<dd>An optional human-readable message sent when the local contact
823
is being held in a queue. This is only applicable when
824
<tp:type>Call_Flags</tp:type>_Queued is in the call flags.
826
SIP 182 notifications can have human-readable messages attached.
830
<dt>debug-message - s</dt>
831
<dd>A message giving further details of any error indicated by the
832
<tp:member-ref>CallStateReason</tp:member-ref>. This will not
833
normally be localized or suitable for display to users, and is only
834
applicable when the call state is
835
<tp:type>Call_State</tp:type>_Ended.</dd>
840
<property name="CallState" type="u" access="read"
841
tp:name-for-bindings="Call_State" tp:type="Call_State">
842
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
843
<p>The current high-level state of this call. The
844
<tp:member-ref>CallFlags</tp:member-ref> provide additional
845
information, and the <tp:member-ref>CallStateReason</tp:member-ref>
846
and <tp:member-ref>CallStateDetails</tp:member-ref> explain the
847
reason for the current values for those properties.</p>
849
<p>Note that when in a conference call, this property is
850
purely to show your state in joining the call. The receiver
851
(or remote contact) in this context is the conference server
852
itself. The property does not change when other call members'
855
<p>Clients MAY consider unknown values in this property to be an
860
<property name="CallFlags" type="u" access="read"
861
tp:name-for-bindings="Call_Flags" tp:type="Call_Flags">
862
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
863
<p>Flags representing the status of the call as a whole,
864
providing more specific information than the
865
<tp:member-ref>CallState</tp:member-ref>.</p>
867
<p>Clients are expected to ignore unknown flags in this property,
870
<p>When an ongoing call is active and not on hold or has any
871
other problems, this property will be 0.</p>
875
<tp:enum name="Call_State_Change_Reason" type="u">
877
A simple representation of the reason for a change in the call's
878
state, which may be used by simple clients, or used as a fallback
879
when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type>
880
struct is not understood.
883
<tp:enumvalue suffix="Unknown" value="0">
884
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
885
We just don't know. Unknown values of this enum SHOULD also be
890
<tp:enumvalue suffix="User_Requested" value="1">
891
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
892
<p>The change was requested by the contact indicated by the Actor
893
member of a <tp:type>Call_State_Reason</tp:type> struct.</p>
895
<p>If the Actor is the local user, the DBus_Reason SHOULD be the
898
<p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty
899
string if the call was terminated normally, but MAY be a non-empty
900
error name to indicate error-like call termination reasons (call
901
rejected as busy, kicked from a conference by a moderator, etc.).</p>
905
<tp:enumvalue suffix="Forwarded" value="2">
906
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
907
<p>The call was forwarded. If known, the handle of the contact
908
the call was forwarded to will be indicated by the Actor member
909
of a <tp:type>Call_State_Reason</tp:type> struct.</p>
913
<tp:enumvalue suffix="No_Answer" value="3">
914
<tp:added version="0.21.2"/>
915
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
916
<p>The <tp:member-ref>CallState</tp:member-ref> changed from
917
<tp:type>Call_State</tp:type>_Pending_Receiver to
918
<tp:type>Call_State</tp:type>_Ended because the initiator
919
ended the call before the receiver accepted it. With an
920
incoming call this state change reason signifies a missed
926
<tp:struct name="Call_State_Reason">
927
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
928
<p>A description of the reason for a change to the
929
<tp:member-ref>CallState</tp:member-ref> and/or
930
<tp:member-ref>CallFlags</tp:member-ref>.</p>
933
<tp:member type="u" tp:type="Contact_Handle" name="Actor">
935
The contact responsible for the change, or 0 if no contact was
940
<tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason">
942
The reason, chosen from a limited set of possibilities defined by
943
the Telepathy specification. If
944
<tp:type>Call_State_Change_Reason</tp:type>_User_Requested then
945
the Actor member will dictate whether it was the local user or
946
a remote contact responsible.
950
<tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason">
951
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
952
<p>A specific reason for the change, which may be a D-Bus error in
953
the Telepathy namespace, a D-Bus error in any other namespace
954
(for implementation-specific errors), or the empty string to
955
indicate that the state change was not an error.</p>
957
<p>This SHOULD be an empty string for changes to any state other
960
<p>The errors Cancelled and Terminated SHOULD NOT be used here;
961
an empty string SHOULD be used instead.</p>
964
<p>Those error names are used to indicate normal call
965
termination by the local user or another user, respectively,
966
in contexts where a D-Bus error name must appear.</p>
972
<property name="CallStateReason" tp:name-for-bindings="Call_State_Reason"
973
type="(uus)" access="read" tp:type="Call_State_Reason">
974
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
975
<p>The reason for the last change to the
976
<tp:member-ref>CallState</tp:member-ref> and/or
977
<tp:member-ref>CallFlags</tp:member-ref>. The
978
<tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional
983
<signal name="CallStateChanged"
984
tp:name-for-bindings="Call_State_Changed">
985
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
986
<p>Emitted when the state of the call as a whole changes.</p>
988
<p>This signal is emitted for any change in the properties
989
corresponding to its arguments, even if the other properties
990
referenced remain unchanged.</p>
993
<arg name="Call_State" type="u" tp:type="Call_State">
995
The new value of the <tp:member-ref>CallState</tp:member-ref>
1000
<arg name="Call_Flags" type="u" tp:type="Call_Flags">
1002
The new value of the <tp:member-ref>CallFlags</tp:member-ref>
1007
<arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason">
1009
The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
1014
<arg name="Call_State_Details" type="a{sv}">
1016
The new value of the <tp:member-ref>CallStateDetails</tp:member-ref>
1022
<property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
1023
type="b" access="read" tp:immutable="yes">
1024
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1025
<p>If this property is True, all of the media streaming is done by some
1026
mechanism outside the scope of Telepathy.</p>
1029
<p>A connection manager might be intended for a specialized hardware
1030
device, which will take care of the audio streaming (e.g.
1031
telepathy-yafono, which uses GSM hardware which does the actual
1032
audio streaming for the call).</p>
1035
<p>If this is False, the handler is responsible for doing the actual
1036
media streaming for at least some contents itself. Those contents
1037
will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface"
1038
>Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary
1039
information to a streaming implementation. Connection managers SHOULD
1040
operate like this, if possible.</p>
1043
<p>Many connection managers (such as telepathy-gabble) only do the
1044
call signalling, and expect the client to do the actual streaming
1045
using something like
1046
<a href="http://farsight.freedesktop.org/">Farsight</a>, to improve
1047
latency and allow better UI integration.</p>
1052
<tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag">
1053
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1054
<p>A set of flags representing the status of a remote contact in a
1057
<p>It is protocol- and client-specific whether a particular contact
1058
will ever have a particular flag set on them, and Telepathy clients
1059
SHOULD NOT assume that a flag will ever be set.</p>
1062
<p>180 Ringing in SIP, and its equivalent in XMPP, are optional
1063
informational messages, and implementations are not required
1064
to send them. The same applies to the messages used to indicate
1069
<tp:flag suffix="Ringing" value = "1">
1070
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1071
<p>The remote contact's client has told us that the contact has been
1072
alerted about the call but has not responded.</p>
1075
<p>This is a flag per member, not a flag for the call as a whole,
1076
because in Muji conference calls, you could invite someone and
1077
have their state be "ringing" for a while.</p>
1082
<tp:flag suffix="Held" value = "2">
1083
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1084
<p>The call member has put this call on hold.</p>
1087
<p>This is a flag per member, not a flag for the call as a whole,
1088
because in conference calls, any member could put the conference
1094
<tp:flag suffix="Conference_Host" value="4">
1095
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1096
This contact has merged this call into a conference. Note that GSM
1097
provides a notification when the remote party merges a call into a
1098
conference, but not when it is split out again; thus, this flag can
1099
only indicate that the call has been part of a conference at some
1100
point. If a GSM connection manager receives a notification that a
1101
call has been merged into a conference a second time, it SHOULD
1102
represent this by clearing and immediately re-setting this flag on
1108
<tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List">
1109
<tp:docstring>A mapping from handles to their current state in the call.
1111
<tp:member type="u" tp:type="Handle" name="key"/>
1112
<tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/>
1115
<signal name="CallMembersChanged"
1116
tp:name-for-bindings="Call_Members_Changed">
1118
Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property
1119
changes in any way, either because contacts have been added to the
1120
call, contacts have been removed from the call, or contacts' flags
1124
<arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map">
1126
A map from members of the call to their new call member flags,
1127
including at least the members who have been added to
1128
<tp:member-ref>CallMembers</tp:member-ref>, and the members whose
1132
<arg name="Removed" type="au" tp:type="Contact_Handle[]">
1134
A list of members who have left the call, i.e. keys to be removed
1135
from <tp:member-ref>CallMembers</tp:member-ref>.
1140
<property name="CallMembers" tp:name-for-bindings="Call_Members"
1141
type="a{uu}" access="read" tp:type="Call_Member_Map">
1142
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1143
<p>A mapping from the remote contacts that are part of this call to flags
1144
describing their status. This mapping never has the local user's handle
1147
<p>When the call ends, this property should be an empty list,
1149
<tp:member-ref>CallMembersChanged</tp:member-ref></p>
1151
<p>If the Call implements
1152
<tp:dbus-ref namespace="ofdT.Channel.Interface"
1153
>Group</tp:dbus-ref> and the Group members are
1154
channel-specific handles, then this call SHOULD also use
1155
channel-specific handles.</p>
1157
<p>Anonymous members are exposed as channel-specific handles
1162
<property name="InitialTransport" tp:name-for-bindings="Initial_Transport"
1163
type="s" access="read" tp:requestable="yes" tp:immutable="yes">
1164
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1165
<p>If set on a requested channel, this indicates the transport that
1166
should be used for this call. Where not applicable, this property
1167
is defined to be the empty string, in particular, on CMs with
1168
hardware streaming.</p>
1171
When implementing a voip gateway one wants the outgoing leg of the
1172
gatewayed to have the same transport as the incoming leg. This
1173
property allows the gateway to request a Call with the right
1174
transport from the CM.
1179
<property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
1180
type="b" access="read" tp:immutable="yes" tp:requestable="yes">
1181
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1182
<p>If set to True in a channel request that will create a new channel,
1183
the connection manager should immediately attempt to establish an
1184
audio stream to the remote contact, making it unnecessary for the
1185
client to call <tp:dbus-ref
1186
namespace="ofdT.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.</p>
1188
<p>If this property, or InitialVideo, is passed to EnsureChannel
1189
(as opposed to CreateChannel), the connection manager SHOULD ignore
1190
these properties when checking whether it can return an existing
1191
channel as suitable; these properties only become significant when
1192
the connection manager has decided to create a new channel.</p>
1194
<p>If True on a requested channel, this indicates that the audio
1195
stream has already been requested and the client does not need to
1196
call RequestStreams, although it MAY still do so.</p>
1198
<p>If True on an unrequested (incoming) channel, this indicates that
1199
the remote contact initially requested an audio stream; this does
1200
not imply that that audio stream is still active (as indicated by
1201
<tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT"
1202
>Contents</tp:dbus-ref>).</p>
1204
<p>The name of this new content can be decided by using the
1205
<tp:member-ref>InitialAudioName</tp:member-ref> property.</p>
1207
<p>Connection managers that support the <tp:dbus-ref
1208
namespace="ofdT.Connection.Interface">ContactCapabilities</tp:dbus-ref>
1209
interface SHOULD represent the capabilities of receiving audio
1210
and/or video calls by including a channel class in
1211
a contact's capabilities with ChannelType = Call
1212
in the fixed properties dictionary, and InitialAudio and/or
1213
InitialVideo in the allowed properties list. Clients wishing to
1214
discover whether a particular contact is likely to be able to
1215
receive audio and/or video calls SHOULD use this information.</p>
1218
<p>Not all clients support video calls, and it would also be
1219
possible (although unlikely) to have a client which could only
1220
stream video, not audio.</p>
1223
<p>Clients that are willing to receive audio and/or video calls
1224
SHOULD include the following among their channel classes if
1225
calling <tp:dbus-ref
1226
namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
1227
(clients of a <tp:dbus-ref
1228
namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
1229
SHOULD instead arrange for the ChannelDispatcher to do this,
1230
by including the filters in their <tp:dbus-ref
1231
namespace="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
1235
<li>{ ChannelType = Call }</li>
1236
<li>{ ChannelType = Call, InitialAudio = True }
1237
if receiving calls with audio is supported</li>
1238
<li>{ ChannelType = Call, InitialVideo = True }
1239
if receiving calls with video is supported</li>
1243
<p>Connection managers for protocols with capability discovery,
1244
like XMPP, need this information to advertise the appropriate
1245
capabilities for their protocol.</p>
1250
<property name="InitialVideo" tp:name-for-bindings="Initial_Video"
1251
type="b" access="read" tp:immutable="yes" tp:requestable="yes">
1252
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1253
<p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
1254
a video stream. This property is immutable (cannot change).</p>
1256
<p>In particular, note that if this property is False, this does not
1257
imply that an active video stream has not been added, only that no
1258
video stream was active at the time the channel appeared.</p>
1260
<p>This property is the correct way to discover whether connection
1261
managers, contacts etc. support video calls; it appears in
1262
capabilities structures in the same way as InitialAudio.</p>
1266
<property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name"
1267
type="s" access="read" tp:immutable="yes" tp:requestable="yes">
1268
<tp:added version="0.21.2"/>
1269
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1270
<p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to
1271
True, then this property will name the intial audio content
1272
with the value of this property.</p>
1275
<p>Content names are meant to be significant, but if no name
1276
can be given to initial audio content, then its name cannot
1277
be meaningful or even localized.</p>
1280
<p>If this property is empty or missing from the channel
1281
request and InitialAudio is True, then the CM must come up
1282
with a sensible for the content, such as "audio".</p>
1284
<p>If the protocol has no concept of stream names then this
1285
property will not show up in the allowed properties list of
1286
the Requestable Channel Classes for call channels.</p>
1290
<property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name"
1291
type="s" access="read" tp:immutable="yes" tp:requestable="yes">
1292
<tp:added version="0.21.2"/>
1293
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1295
<tp:member-ref>InitialAudioName</tp:member-ref>, but for a
1296
video stream created by setting
1297
<tp:member-ref>InitialVideo</tp:member-ref> to True. This
1298
property is immutable and so cannot change.</p>
1302
<property name="MutableContents" tp:name-for-bindings="Mutable_Contents"
1303
type="b" access="read" tp:immutable="yes">
1304
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1305
<p>If True, a stream of a different content type can be added
1306
after the Channel has been requested </p>
1308
<p>If this property is missing, clients SHOULD assume that it is False,
1309
and thus that the channel's streams cannot be changed once the call
1312
<p>If this property isn't present in the "allowed" set in any of the
1313
Call entries contact capabilities, then user interfaces MAY choose to
1314
show a separate "call" option for each class of call.</p>
1317
<p>For example, once an audio-only Google Talk call has started,
1318
it is not possible to add a video stream; both audio and video
1319
must be requested at the start of the call if video is desired.
1320
User interfaces may use this pseudo-capability as a hint to
1321
display separate "Audio call" and "Video call" buttons, rather
1322
than a single "Call" button with the option to add and remove
1323
video once the call has started for contacts without this flag.
1329
<tp:hct name="audio">
1330
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1331
<p>This client supports audio calls.</p>
1335
<tp:hct name="video">
1336
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1337
<p>This client supports video calls.</p>
1341
<tp:hct name="gtalk-p2p">
1342
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1343
<p>The client can implement streaming for streams whose <tp:dbus-ref
1344
namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
1345
property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p>
1350
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1351
<p>The client can implement streaming for streams whose <tp:dbus-ref
1352
namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
1353
property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p>
1357
<tp:hct name="wlm-2009">
1358
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1359
<p>The client can implement streaming for streams whose <tp:dbus-ref
1360
namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
1361
property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p>
1366
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1367
<p>The client can implement streaming for streams whose <tp:dbus-ref
1368
namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
1369
property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p>
1373
<tp:hct name="video/h264" is-family="yes">
1374
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
1375
<p>The client supports media streaming with H264 (etc.).</p>
1377
<p>This handler capability token is a one of a family
1378
of similar tokens: for any other audio or video codec whose MIME
1379
type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
1380
capability token of this form may exist (the subtype MUST appear
1381
in lower case in this context). Clients MAY support more
1382
codecs than they explicitly advertise support for; clients SHOULD
1383
explicitly advertise support for their preferred codec(s), and
1384
for codecs like H264 that are, in practice, significant in codec
1388
<p>For instance, the XMPP capability used by the Google Video
1389
Chat web client to determine whether a client is compatible
1390
with it requires support for H264 video, so an XMPP
1391
connection manager that supports this version of Jingle should
1392
not advertise the Google Video Chat capability unless there
1393
is at least one installed client that declares that it supports
1394
<code>video/h264</code> on Call channels.</p>
1397
<p>For example, a client could advertise support for audio and video
1398
calls using Speex, Theora and H264 by having five handler capability
1399
tokens in its <tp:dbus-ref
1400
namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref>
1404
<li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li>
1405
<li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li>
1406
<li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li>
1407
<li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li>
1408
<li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li>
1411
<p>Clients MAY have media signalling abilities without explicitly
1412
supporting any particular codec, and connection managers SHOULD
1413
support this usage.</p>
1416
<p>This is necessary to support gatewaying between two Telepathy
1417
connections, in which case the available codecs might not be
1418
known to the gatewaying process.</p>
1425
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
telepathy-yell/spec/Channel_Type_Call.xml
