summaryrefslogtreecommitdiff
path: root/spec/Media_Stream_Handler.xml
blob: c9ae78f4643350a405024cda9d5bb4d8073226c6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
<?xml version="1.0" ?>
<node name="/Media_Stream_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
  <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
  </tp:license>
  <interface name="org.freedesktop.Telepathy.Media.StreamHandler">

    <tp:struct name="Media_Stream_Handler_Candidate"
      array-name="Media_Stream_Handler_Candidate_List">
      <tp:member type="s" name="Name"/>
      <tp:member type="a(usuussduss)" name="Transports"
        tp:type="Media_Stream_Handler_Transport[]"/>
    </tp:struct>

    <tp:struct name="Media_Stream_Handler_Transport"
      array-name="Media_Stream_Handler_Transport_List">
      <tp:member type="u" name="Component_Number"/>
      <tp:member type="s" name="IP_Address"/>
      <tp:member type="u" name="Port"/>
      <tp:member type="u" tp:type="Media_Stream_Base_Proto" name="Protocol"/>
      <tp:member type="s" name="Subtype"/>
      <tp:member type="s" name="Profile"/>
      <tp:member type="d" name="Preference_Value"/>
      <tp:member type="u" tp:type="Media_Stream_Transport_Type"
        name="Transport_Type"/>
      <tp:member type="s" name="Username"/>
      <tp:member type="s" name="Password"/>
    </tp:struct>

    <tp:struct name="Media_Stream_Handler_Codec"
      array-name="Media_Stream_Handler_Codec_List">
      <tp:docstring>
        Information about a codec supported by a client or a peer's client.
      </tp:docstring>

      <tp:member type="u" name="Codec_ID">
        <tp:docstring>
          The codec's payload identifier, as per RFC 3551 (static or dynamic)
        </tp:docstring>
      </tp:member>
      <tp:member type="s" name="Name">
        <tp:docstring>The codec's name</tp:docstring>
      </tp:member>
      <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type">
        <tp:docstring>Type of stream this codec supports</tp:docstring>
      </tp:member>
      <tp:member type="u" name="Clock_Rate">
        <tp:docstring>Sampling frequency in Hertz</tp:docstring>
      </tp:member>
      <tp:member type="u" name="Number_Of_Channels">
        <tp:docstring>Number of supported channels</tp:docstring>
      </tp:member>
      <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map">
        <tp:docstring>Codec-specific optional parameters</tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
      type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
      <tp:added version="0.17.22"/>
      <tp:docstring>
        The IP addresses of possible STUN servers to use for NAT traversal, as
        dotted-quad IPv4 address literals or RFC2373 IPv6 address literals.
        This property cannot change once the stream has been created, so there
        is no change notification. The IP addresses MUST NOT be given as DNS
        hostnames.

        <tp:rationale>
          High-quality connection managers already need an asynchronous
          DNS resolver, so they might as well resolve this name to an IP
          to make life easier for streaming implementations.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="CreatedLocally" tp:name-for-bindings="Created_Locally"
      type="b" access="read">
      <tp:added version="0.17.22"/>
      <tp:docstring>
        True if we were the creator of this stream, false otherwise.
        <tp:rationale>
          This information is needed for some nat traversal mechanisms, such
          as ICE-UDP, where the creator gets the role of the controlling agent.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="NATTraversal" tp:name-for-bindings="NAT_Traversal"
      type="s" access="read">
      <tp:added version="0.17.22"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The transport (NAT traversal technique) to be used for this
          stream. Well-known values include:</p>

        <dl>
          <dt>none</dt>
          <dd>Raw UDP, with or without STUN, should be used. If the
            <tp:member-ref>STUNServers</tp:member-ref> property is non-empty,
            STUN SHOULD be used.</dd>

          <dt>stun</dt>
          <dd>A deprecated synonym for 'none'.</dd>

          <dt>gtalk-p2p</dt>
          <dd>Google Talk peer-to-peer connectivity establishment should be
            used, as implemented in libjingle 0.3.</dd>

          <dt>ice-udp</dt>
          <dd>Interactive Connectivity Establishment should be used,
            as defined by the IETF MMUSIC working group.</dd>

          <dt>wlm-8.5</dt>
          <dd>The transport used by Windows Live Messenger 8.5 or later,
            which resembles ICE draft 6, should be used.</dd>

          <dt>wlm-2009</dt>
          <dd>The transport used by Windows Live Messenger 2009 or later,
            which resembles ICE draft 19, should be used.</dd>
        </dl>

        <p>This property cannot change once the stream has been created, so
          there is no change notification.</p>
      </tp:docstring>
    </property>

    <property name="RelayInfo" type="aa{sv}" access="read"
      tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A list of mappings describing TURN or Google relay servers
          available for the client to use in its candidate gathering, as
          determined from the protocol. Map keys are:</p>

        <dl>
          <dt><code>ip</code> - s</dt>
          <dd>The IP address of the relay server as a dotted-quad IPv4
            address literal or an RFC2373 IPv6 address literal. This MUST NOT
            be a DNS hostname.

            <tp:rationale>
              High-quality connection managers already need an asynchronous
              DNS resolver, so they might as well resolve this name to an IP
              and make life easier for streaming implementations.
            </tp:rationale>
          </dd>

          <dt><code>type</code> - s</dt>
          <dd>
            <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
              key is omitted), <code>tcp</code> for TCP, or
              <code>tls</code>.</p>

            <p>The precise meaning of this key depends on the
              <tp:member-ref>NATTraversal</tp:member-ref> property: if
              NATTraversal is <code>ice-udp</code>, <code>tls</code> means
              TLS over TCP as referenced by ICE draft 19, and if
              NATTraversal is <code>gtalk-p2p</code>, <code>tls</code> means
              a fake SSL session over TCP as implemented by libjingle.</p>
          </dd>

          <dt><code>port</code> - q</dt>
          <dd>The UDP or TCP port of the relay server as an ASCII unsigned
            integer</dd>

          <dt><code>username</code> - s</dt>
          <dd>The username to use</dd>

          <dt><code>password</code> - s</dt>
          <dd>The password to use</dd>

          <dt><code>component</code> - u</dt>
          <dd>The component number to use this relay server for, as an
            ASCII unsigned integer; if not included, this relay server
            may be used for any or all components.

            <tp:rationale>
              In ICE draft 6, as used by Google Talk, credentials are only
              valid once, so each component needs relaying separately.
            </tp:rationale>
          </dd>
        </dl>

        <tp:rationale>
          <p>An equivalent of the gtalk-p2p-relay-token property on
            MediaSignalling channels is not included here. The connection
            manager should be responsible for making the necessary HTTP
            requests to turn the token into a username and password.</p>
        </tp:rationale>

        <p>The type of relay server that this represents depends on
          the value of the <tp:member-ref>NATTraversal</tp:member-ref>
          property. If NATTraversal is ice-udp, this is a TURN server;
          if NATTraversal is gtalk-p2p, this is a Google relay server;
          otherwise, the meaning of RelayInfo is undefined.</p>

        <p>If relaying is not possible for this stream, the list is empty.</p>

        <p>This property cannot change once the stream has been created, so
          there is no change notification.</p>
      </tp:docstring>
    </property>

    <signal name="AddRemoteCandidate"
      tp:name-for-bindings="Add_Remote_Candidate">
      <arg name="Candidate_ID" type="s">
        <tp:docstring>
          String identifier for this candidate
        </tp:docstring>
      </arg>
      <arg name="Transports" type="a(usuussduss)"
        tp:type="Media_Stream_Handler_Transport[]">
        <tp:docstring>
          Array of transports for this candidate with fields,
          as defined in NewNativeCandidate
        </tp:docstring>
      </arg>
      <tp:docstring>
        Signal emitted when the connection manager wishes to inform the
        client of a new remote candidate.
      </tp:docstring>
    </signal>
    <signal name="Close" tp:name-for-bindings="Close">
      <tp:docstring>
        Signal emitted when the connection manager wishes the stream to be
        closed.
      </tp:docstring>
    </signal>
    <method name="CodecChoice" tp:name-for-bindings="Codec_Choice">
      <arg direction="in" name="Codec_ID" type="u"/>
      <tp:docstring>
        Inform the connection manager of codec used to receive data.
      </tp:docstring>
    </method>
    <method name="Error" tp:name-for-bindings="Error">
      <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error">
        <tp:docstring>
          ID of error, from the MediaStreamError enumeration
        </tp:docstring>
      </arg>
      <arg direction="in" name="Message" type="s">
        <tp:docstring>
          String describing the error
        </tp:docstring>
      </arg>
      <tp:docstring>
        Inform the connection manager that an error occured in this stream. The
        connection manager should emit the StreamError signal for the stream on
        the relevant channel, and remove the stream from the session.
      </tp:docstring>
    </method>
    <tp:enum name="Media_Stream_Error" type="u">
      <tp:enumvalue suffix="Unknown" value="0">
        <tp:docstring>
          An unknown error occured.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="EOS" value="1">
        <tp:docstring>
          The end of the stream was reached.
        </tp:docstring>
        <tp:deprecated version="0.17.27">
          This error has no use anywhere. In Farsight 1 times, it was used to
          indicate a GStreamer EOS (when the end of a file is reached). But
          since this is for live calls, it makes no sense.
        </tp:deprecated>
      </tp:enumvalue>
      <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          There are no common codecs between the local side
          and the other particpants in the call. The possible codecs are not
          signalled here: the streaming implementation is assumed to report
          them in an implementation-dependent way, e.g. Farsight should use
          GstMissingElement.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Connection_Failed" value="3">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          A network connection for the Media could not be established or was
          lost.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Network_Error" value="4">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          There was an error in the networking stack
          (other than the connection failure).
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="No_Codecs" value="5">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          There are no installed codecs for this media type.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Invalid_CM_Behavior" value="6">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          The CM is doing something wrong.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Media_Error" value="7">
        <tp:added version="0.17.27"/>
        <tp:docstring>
          There was an error in the media processing stack.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>
    <method name="NativeCandidatesPrepared"
      tp:name-for-bindings="Native_Candidates_Prepared">
      <tp:docstring>
        Informs the connection manager that all possible native candisates
        have been discovered for the moment.
      </tp:docstring>
    </method>
    <method name="NewActiveCandidatePair"
      tp:name-for-bindings="New_Active_Candidate_Pair">
      <arg direction="in" name="Native_Candidate_ID" type="s"/>
      <arg direction="in" name="Remote_Candidate_ID" type="s"/>
      <tp:docstring>
        Informs the connection manager that a valid candidate pair
        has been discovered and streaming is in progress.
      </tp:docstring>
    </method>
    <tp:enum name="Media_Stream_Base_Proto" type="u">
      <tp:enumvalue suffix="UDP" value="0">
        <tp:docstring>UDP (User Datagram Protocol)</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="TCP" value="1">
        <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring>
      </tp:enumvalue>
    </tp:enum>
    <method name="NewNativeCandidate"
      tp:name-for-bindings="New_Native_Candidate">
      <arg direction="in" name="Candidate_ID" type="s">
        <tp:docstring>
          String identifier for this candidate
        </tp:docstring>
      </arg>
      <arg direction="in" name="Transports" type="a(usuussduss)"
        tp:type="Media_Stream_Handler_Transport[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          Array of transports for this candidate, with fields:
          <ul>
            <li>component number</li>
            <li>IP address (as a string)</li>
            <li>port</li>
            <li>base network protocol (one of the values of MediaStreamBaseProto)</li>
            <li>proto subtype (e.g. RTP)</li>
            <li>proto profile (e.g. AVP)</li>
            <li>our preference value of this transport (double in range 0.0-1.0
              inclusive); 1 signals the most preferred transport</li>
            <li>transport type, one of the values of MediaStreamTransportType</li>
            <li>username if authentication is required</li>
            <li>password if authentication is required</li>
          </ul>
        </tp:docstring>
      </arg>
      <tp:docstring>
        Inform this MediaStreamHandler that a new native transport candidate
        has been ascertained.
      </tp:docstring>
    </method>
    <tp:enum name="Media_Stream_Transport_Type" type="u">
      <tp:enumvalue suffix="Local" value="0">
        <tp:docstring>
          A local address
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Derived" value="1">
        <tp:docstring>
          An external address derived by a method such as STUN
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Relay" value="2">
        <tp:docstring>
          An external stream relay
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>
    <method name="Ready" tp:name-for-bindings="Ready">
      <arg direction="in" name="Codecs" type="a(usuuua{ss})"
        tp:type="Media_Stream_Handler_Codec[]">
        <tp:docstring>
          Locally-supported codecs.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Inform the connection manager that a client is ready to handle
        this StreamHandler. Also provide it with info about all supported
        codecs.
      </tp:docstring>
    </method>
    <method name="SetLocalCodecs" tp:name-for-bindings="Set_Local_Codecs">
      <arg name="Codecs" type="a(usuuua{ss})" direction="in"
        tp:type="Media_Stream_Handler_Codec[]">
        <tp:docstring>
          Locally-supported codecs
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Used to provide codecs after Ready(), so the media client can go
          ready for an incoming call and exchange candidates/codecs before
          knowing what local codecs are available.</p>

        <p>This is useful for gatewaying calls between two connection managers.
          Given an incoming call, you need to call
          <tp:member-ref>Ready</tp:member-ref> to get the remote codecs before
          you can use them as the "local" codecs to place the outgoing call,
          and hence receive the outgoing call's remote codecs to use as the
          incoming call's "local" codecs.</p>

        <p>In this situation, you would pass an empty list of codecs to the
          incoming call's Ready method, then later call SetLocalCodecs on the
          incoming call in order to respond to the offer.</p>
      </tp:docstring>
    </method>
    <signal name="RemoveRemoteCandidate"
      tp:name-for-bindings="Remove_Remote_Candidate">
      <arg name="Candidate_ID" type="s">
        <tp:docstring>
          String identifier for remote candidate to drop
        </tp:docstring>
      </arg>
      <tp:deprecated version="0.17.18">
        There is no case where you want to release candidates (except
        for an ICE reset, and there you'd want to replace then all,
        using <tp:member-ref>SetRemoteCandidateList</tp:member-ref>).
      </tp:deprecated>
      <tp:docstring>
        Signal emitted when the connection manager wishes to inform the
        client that the remote end has removed a previously usable
        candidate.

        <tp:rationale>
          It seemed like a good idea at the time, but wasn't.
        </tp:rationale>
      </tp:docstring>
    </signal>
    <signal name="SetActiveCandidatePair"
      tp:name-for-bindings="Set_Active_Candidate_Pair">
      <arg name="Native_Candidate_ID" type="s"/>
      <arg name="Remote_Candidate_ID" type="s"/>
      <tp:docstring>
        Emitted by the connection manager to inform the client that a
        valid candidate pair has been discovered by the remote end
        and streaming is in progress.
      </tp:docstring>
    </signal>
    <signal name="SetRemoteCandidateList"
      tp:name-for-bindings="Set_Remote_Candidate_List">
      <arg name="Remote_Candidates" type="a(sa(usuussduss))"
        tp:type="Media_Stream_Handler_Candidate[]">
        <tp:docstring>
        A list of candidate id and a list of transports
        as defined in NewNativeCandidate
        </tp:docstring>
      </arg>
      <tp:docstring>
        Signal emitted when the connection manager wishes to inform the
        client of all the available remote candidates at once.
      </tp:docstring>
    </signal>
    <signal name="SetRemoteCodecs" tp:name-for-bindings="Set_Remote_Codecs">
      <arg name="Codecs" type="a(usuuua{ss})"
        tp:type="Media_Stream_Handler_Codec[]">
        <tp:docstring>
          Codecs supported by the remote peer.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Signal emitted when the connection manager wishes to inform the
        client of the codecs supported by the remote end.
	If these codecs are compatible with the remote codecs, then the client
        must call <tp:member-ref>SupportedCodecs</tp:member-ref>,
        otherwise call <tp:member-ref>Error</tp:member-ref>.
      </tp:docstring>
    </signal>
    <signal name="SetStreamPlaying" tp:name-for-bindings="Set_Stream_Playing">
      <arg name="Playing" type="b"/>
      <tp:docstring>
        If emitted with argument TRUE, this means that the connection manager
        wishes to set the stream playing; this means that the streaming
        implementation should expect to receive data. If emitted with argument
        FALSE this signal is basically meaningless and should be ignored.

        <tp:rationale>
          We're very sorry.
        </tp:rationale>
      </tp:docstring>
    </signal>
    <signal name="SetStreamSending" tp:name-for-bindings="Set_Stream_Sending">
      <arg name="Sending" type="b"/>
      <tp:docstring>
        Signal emitted when the connection manager wishes to set whether or not
        the stream sends to the remote end.
      </tp:docstring>
    </signal>
    <signal name="StartTelephonyEvent"
      tp:name-for-bindings="Start_Telephony_Event">
      <arg name="Event" type="y">
        <tp:docstring>
          A telephony event code as defined by RFC 4733.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request that a telephony event (as defined by RFC 4733) is transmitted
        over this stream until StopTelephonyEvent is called.
      </tp:docstring>
    </signal>
    <signal name="StopTelephonyEvent"
      tp:name-for-bindings="Stop_Telephony_Event">
      <tp:docstring>
        Request that any ongoing telephony events (as defined by RFC 4733)
        being transmitted over this stream are stopped.
      </tp:docstring>
    </signal>
    <method name="StreamState" tp:name-for-bindings="Stream_State">
      <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"/>
      <tp:docstring>
        Informs the connection manager of the stream's current state, as
        as specified in Channel.Type.StreamedMedia::ListStreams.
      </tp:docstring>
    </method>

    <method name="SupportedCodecs" tp:name-for-bindings="Supported_Codecs">
      <arg direction="in" name="Codecs" type="a(usuuua{ss})"
        tp:type="Media_Stream_Handler_Codec[]">
        <tp:docstring>
          Locally supported codecs.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Inform the connection manager of the supported codecs for this session.
        This is called after the connection manager has emitted SetRemoteCodecs
        to notify what codecs are supported by the peer, and will thus be an
        intersection of all locally supported codecs (passed to Ready)
        and those supported by the peer.
      </tp:docstring>
    </method>

    <method name="CodecsUpdated" tp:name-for-bindings="Codecs_Updated">
      <arg direction="in" name="Codecs" type="a(usuuua{ss})"
        tp:type="Media_Stream_Handler_Codec[]">
        <tp:docstring>
          Locally supported codecs, which SHOULD be the same as were previously
          in effect, but possibly with different parameters.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Inform the connection manager that the parameters of the supported
        codecs for this session have changed. The connection manager should
        send the new parameters to the remote contact.

        <tp:rationale>
          This is required for H.264 and Theora, for example.
        </tp:rationale>
      </tp:docstring>
    </method>

    <signal name="SetStreamHeld" tp:name-for-bindings="Set_Stream_Held">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the connection manager wishes to place the stream on
          hold (so the streaming client should free hardware or software
          resources) or take the stream off hold (so the streaming client
          should reacquire the necessary resources).</p>

        <p>When placing a channel's streams on hold, the connection manager
          SHOULD notify the remote contact that this will be done (if
          appropriate in the protocol) before it emits this signal.</p>

        <tp:rationale>
          <p>It is assumed that relinquishing a resource will not fail.
            If it does, the call is probably doomed anyway.</p>
        </tp:rationale>

        <p>When unholding a channel's streams, the connection manager
          SHOULD emit this signal and wait for success to be indicated
          via HoldState before it notifies the remote contact that the
          channel has been taken off hold.</p>

        <tp:rationale>
          <p>This means that if a resource is unavailable, the remote
            contact will never even be told that we tried to acquire it.</p>
        </tp:rationale>
      </tp:docstring>
      <tp:added version="0.17.3"/>

      <arg name="Held" type="b">
        <tp:docstring>
          If true, the stream is to be placed on hold.
        </tp:docstring>
      </arg>
    </signal>

    <method name="HoldState" tp:name-for-bindings="Hold_State">
      <tp:docstring>
        Notify the connection manager that the stream's hold state has
        been changed successfully in response to SetStreamHeld.
      </tp:docstring>
      <tp:added version="0.17.3"/>
      <arg direction="in" name="Held" type="b">
        <tp:docstring>
          If true, the stream is now on hold.
        </tp:docstring>
      </arg>
    </method>

    <method name="UnholdFailure" tp:name-for-bindings="Unhold_Failure">
      <tp:docstring>
        Notify the connection manager that an attempt to reacquire the
        necessary hardware or software resources to unhold the stream,
        in response to SetStreamHeld, has failed.
      </tp:docstring>
      <tp:added version="0.17.3"/>
    </method>

    <tp:docstring>
    Handles signalling the information pertaining to a specific media stream.
    A client should provide information to this handler as and when it is
    available.
    </tp:docstring>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->