summaryrefslogtreecommitdiff
path: root/spec/Connection_Interface_Requests.xml
blob: 2f233fa53a92aa1561a602f3e981fabb593dca7e (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
<?xml version="1.0" ?>
<node name="/Connection_Interface_Requests"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
  >
  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2008 Nokia Corporation</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.Connection.Interface.Requests">
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
    <tp:added version="0.17.11">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An enhanced version of the Telepathy connection interface, which can
        represent bundles of channels that should be dispatched together, and
        does not assume any particular properties by which channels are
        uniquely identifiable.</p>

      <p>If this interface is implemented on a connection, then
        <tp:member-ref>NewChannels</tp:member-ref> MUST be emitted for
        all new channels, even those created with <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection"
        >RequestChannel</tp:dbus-ref>.</p>
    </tp:docstring>

    <tp:struct name="Channel_Details" array-name="Channel_Details_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>

      <tp:docstring>
        Enough details of a channel that clients can work out how to dispatch
        or handle it.
      </tp:docstring>

      <tp:member name="Channel" type="o">
        <tp:docstring>
          The object path of the channel.
        </tp:docstring>
      </tp:member>

      <tp:member name="Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel.</p>

          <p>Connection managers MUST NOT include properties in this mapping
            if their values can change. Clients MUST ignore properties
            that appear in this mapping if their values can change.</p>

          <tp:rationale>
            <p>If properties that could change were included, the following
              race condition would be likely to exist in some cases:</p>

            <ul>
              <li>NewChannels or Get("Channels") includes a property P with
                value V1</li>
              <li>Client creates a proxy object for the channel</li>
              <li>The value of P changes to V2</li>
              <li>Client connects to PChanged signal</li>
              <li>Client should call Get("P") or GetAll here, to avoid the
                race, but client's author has forgotten to do so</li>
              <li>Proxy object thinks P == V1, but actually P == V2</li>
            </ul>

            <p>We've taken the opportunity to make the API encourage the
              client author to get it right. Where possible, we intend that
              properties whose value will be used in channel dispatching
              or other "early" processing will be defined so that they are
              immutable (can never change).</p>
          </tp:rationale>

          <p>Each dictionary MUST contain the keys
            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>,
            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>
            and
            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>.
          </p>

          <tp:rationale>
            <p>We expect these to be crucial to the channel-dispatching
              process.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:changed version="0.17.14">It is now guaranteed that
        CreateChannel returns the channel before NewChannels announces it
        (the reverse was previously guaranteed).</tp:changed>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that an entirely new channel is created.</p>

        <tp:rationale>
          <p>There is deliberately no flag corresponding to the
            suppress_handler argument to
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>,
            because passing a FALSE value for that argument is deprecated.
            Requests made using this interface always behave as though
            suppress_handler was TRUE.</p>
        </tp:rationale>

      </tp:docstring>

      <arg direction="in" name="Request" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties, which MUST include
            <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>.
            Some properties
            are defined such that only an exact match makes sense, and
            connection managers MUST NOT satisfy a request with a channel
            where that property does not match; some properties are defined
            such that the connection manager MAY treat the request as merely
            a hint, and make a best-effort attempt to satisfy it. This is
            documented separately for each property.</p>

          <p>If this dictionary contains a property whose semantics
            are not known to the connection manager, this method MUST fail
            without side-effects (in particular it must not create a new
            channel).</p>

          <tp:rationale>
            <p>This is necessary if we want to be able to invent properties
              in future that, when used in a request, are hard requirements
              rather than just hints. A connection manager that did not know
              the semantics of those properties could incorrectly return a
              new channel that did not satisfy the requirements.</p>
          </tp:rationale>

          <p>The connection manager MUST NOT respond successfully,
            and SHOULD NOT create a new channel or cause any other
            side-effects, unless it can create a new channel that satisfies
            the client's requirements.</p>

          <p>Properties that will be set by this argument need not have write
            access after the channel has been created - indeed, it is
            expected that most will be read-only.</p>
        </tp:docstring>
      </arg>

      <arg name="Channel" direction="out" type="o">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The Channel object, which MUST NOT be signalled with
            <tp:member-ref>NewChannels</tp:member-ref> until after this method
            returns.</p>

          <tp:rationale>
            <p>This allows the requester to alter its handling of
              NewChannels by knowing whether one of the channels satisfied
              a request it made.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Properties" direction="out" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel that was produced, equivalent to
            the properties in <tp:type>Channel_Details</tp:type>.
            Connection managers MUST NOT include properties here whose
            values can change, for the same reasons as in
            <tp:type>Channel_Details</tp:type>.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The channel request was one that can never succeed,
            such as requesting an unsupported channel type, or requesting
            a channel type which this connection manager does not support with
            the given target handle type.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            An invalid handle was requested as the value of a property whose
            value is a handle (like
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
            or a syntactically invalid identifier was requested as the value
            of a property whose value is the string corresponding to a handle
            (like <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The request matched the fixed properties of a
            <tp:type>Requestable_Channel_Class</tp:type> in
            <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
            allowed arguments did not make sense; for example, a <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
            was requested, but the <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
            property provided was not a valid DNS name.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
          <tp:docstring>
            The requested channel cannot be created because the requested
            contact is using a client that lacks a particular feature.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.Offline">
          <tp:docstring>
            The requested channel cannot be created because the target is
            offline.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
            <p>The requested channel cannot be created, but in
              principle, a similar request might succeed in future.
              For instance, this might be because:</p>

            <ul>
              <li>a channel matching the request already exists and the
                protocol requires that only one such channel can exist at a
                time</li>
              <li>a channel matching the request has already been requested
                (by a previous call to CreateChannel,
                <tp:member-ref>EnsureChannel</tp:member-ref>,
                <tp:dbus-ref
                  namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
                or similar) and the protocol requires that only one such
                channel can exist at a time</li>
            </ul>
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
      <tp:added version="0.17.12"/>
      <tp:changed version="0.17.14">It is now guaranteed that if
        the channel was created by this call to EnsureChannel, it's returned
        before NewChannels announces it (the reverse was previously
        guaranteed).</tp:changed>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that channels are ensured to exist.</p>

        <tp:rationale>
          <p>The connection manager is in the best position to determine which
            existing channels could satisfy which requests.</p>
        </tp:rationale>

      </tp:docstring>

      <arg direction="in" name="Request" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties, with the same
            semantics as the corresponding parameter to
            <tp:member-ref>CreateChannel</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg name="Yours" direction="out" type="b">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If false, the caller of EnsureChannel MUST assume that some
            other process is handling this channel; if true, the caller of
            EnsureChannel SHOULD handle it themselves or delegate it to another
            client.</p>

          <p>If the creation of a channel makes several calls to EnsureChannel
            (and no other requests) successful, exactly one of those calls MUST
            return a true value for this argument.</p>

          <p>If the creation of a channel makes other requests successful,
            the value returned for this argument MUST be such that exactly
            one of the clients making requests ends up responsible for the
            channel. In particular, if
            <tp:member-ref>CreateChannel</tp:member-ref> returns a channel
            <em>C</em>, any EnsureChannel calls that also return <em>C</em>
            MUST return a false value for this argument.</p>
        </tp:docstring>
      </arg>

      <arg name="Channel" direction="out" type="o">
        <tp:docstring>
          The Channel object. If it was created as a result of this method
          call, it MUST NOT be signalled by
          <tp:member-ref>NewChannels</tp:member-ref> until after this method
          returns.

          <tp:rationale>
            <p>This allows the requester to alter its handling of
              NewChannels by knowing whether one of the channels satisfied
              a request it made.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Properties" direction="out" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties of the channel that was produced, equivalent to
            the properties in <tp:type>Channel_Details</tp:type>.
            Connection managers MUST NOT include properties here whose
            values can change, for the same reasons as in
            <tp:type>Channel_Details</tp:type>.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The channel request was one that can never succeed,
            such as requesting an unsupported channel type, or requesting
            a channel type which this connection manager does not support with
            the given target handle type.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            An invalid handle was requested as the value of a property whose
            value is a handle (like
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
            or a syntactically invalid identifier was requested as the value
            of a property whose value is the string corresponding to a handle
            (like <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The request matched the fixed properties of a
            <tp:type>Requestable_Channel_Class</tp:type> in
            <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
            allowed arguments did not make sense; for example, a <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
            was requested, but the <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
            property provided was not a valid DNS name.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
          <tp:docstring>
            The requested channel cannot be created because the requested
            contact is using a client that lacks a particular feature.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.Offline">
          <tp:docstring>
            The requested channel cannot be created because the target is
            offline.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The requested channel cannot be created, but in
            principle, a similar request might succeed in future.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
        <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <signal name="NewChannels" tp:name-for-bindings="New_Channels">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:changed version="0.17.14">Added a guarantee of ordering
        relative to NewChannel</tp:changed>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>New channels have been created. The connection manager SHOULD emit
          a single signal for any group of closely related channels that are
          created at the same time, so that the channel dispatcher can try to
          dispatch them to a handler as a unit.</p>

        <p>In particular, if additional channels are created as a side-effect
          of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
          these channels SHOULD appear in the same NewChannels signal as
          the channel that satisfies the request.</p>

        <tp:rationale>
          <p>Joining a MUC Tube in XMPP requires joining the corresponding
            MUC (chatroom), so a <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
            channel can be created as a side-effect.</p>
        </tp:rationale>

        <p>Every time NewChannels is emitted, it MUST be followed by
          a <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
          signal for each channel.</p>

        <tp:rationale>
          <p>The double signal emission is for the benefit of older Telepathy
            clients, which won't be listening for NewChannels.</p>

          <p>The more informative NewChannels signal comes first so that
            clients that did not examine the connection to find
            out whether Requests is supported will see the more informative
            signal for each channel first, and then ignore the less
            informative signal because it announces a new channel of which
            they are already aware.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
        <tp:docstring>
          The channels and their details. All channels that are signalled
          together like this MUST have the same
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
          property, which may
          either refer to an existing bundle, or establish a new bundle.
        </tp:docstring>
      </arg>
    </signal>

    <property name="Channels" tp:name-for-bindings="Channels"
      type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring>
        A list of all the channels which currently exist on this connection.
        Change notification is via the
        <tp:member-ref>NewChannels</tp:member-ref> and
        <tp:member-ref>ChannelClosed</tp:member-ref> signals.
      </tp:docstring>
    </property>

    <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring>
        Emitted when a channel is closed and hence disappears from the
        <tp:member-ref>Channels</tp:member-ref> property.

        <tp:rationale>
          This is redundant with the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>
          signal on the channel itself, but it does provide full change
          notification for the Channels property.
        </tp:rationale>
      </tp:docstring>

      <arg name="Removed" type="o">
        <tp:docstring>
          The channel which has been removed from the Channels property
        </tp:docstring>
      </arg>
    </signal>

    <tp:mapping name="Channel_Class" array-name="Channel_Class_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Mapping representing a class of channels that can be requested
          from a connection manager, can be handled by a user interface,
          are supported by a contact, etc.</p>

        <p>Classes of channel are identified by the fixed values of
          a subset of their properties.</p>

        <p>Channel classes SHOULD always include the keys
          <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
          and
          <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
          </p>
      </tp:docstring>

      <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
        <tp:docstring>
          A D-Bus interface name, followed by a dot and a D-Bus property name.
        </tp:docstring>
      </tp:member>

      <tp:member type="v" name="Value">
        <tp:docstring>
          The value of the property.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:struct name="Requestable_Channel_Class"
      array-name="Requestable_Channel_Class_List">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Structure representing a class of channels that can be requested,
          identified by a set of properties that identify that class of
          channel.</p>

        <tp:rationale>
          <p>This will often just be the channel type and the handle type,
            but can include other properties of the channel - for instance,
            encrypted channels might require properties that
            unencrypted channels do not, like an encryption key.</p>
        </tp:rationale>

        <p>In some cases, these classes of channel may overlap, in the sense
          that one class fixes all the properties that another class does,
          plus some more properties.</p>

        <tp:rationale>
          <p>For older clients to still be able to understand how to request
            channels in the presence of a hypothetical "encryption" interface,
            we'd need to represent it like this:</p>

          <ul>
            <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
            <li>class 2: Channel.ChannelType = Text,
              Channel.TargetHandleType = CONTACT,
              Encryption.Encrypted = TRUE</li>
          </ul>
        </tp:rationale>
      </tp:docstring>

      <tp:member name="Fixed_Properties" type="a{sv}"
        tp:type="Channel_Class">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The property values that identify this requestable channel class.
            These properties MUST be included in requests for a channel of this
            class, and MUST take these values.</p>

          <p>Clients that do not understand the semantics of all the
            Fixed_Properties MUST NOT request channels of this class, since
            they would be unable to avoid making an incorrect request.</p>

          <p>This implies that connection managers wishing to make channels
            available to old or minimal clients SHOULD have a channel class
            with the minimum number of Fixed_Properties, and MAY additionally
            have channel classes with extra Fixed_Properties.</p>

          <p>Interface designers SHOULD avoid introducing fixed properties
            whose types are not serializable in a <code>.manager</code>
            file.</p>

          <tp:rationale>
            <p>Connection managers with a fixed property that is not
              serializable cannot have a complete <code>.manager</code>
              file.</p>
          </tp:rationale>
        </tp:docstring>
      </tp:member>

      <tp:member name="Allowed_Properties" type="as"
        tp:type="DBus_Qualified_Member[]">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Properties that MAY be set when requesting a channel of this
            channel type and handle type.</p>

          <p>This array MUST NOT include properties that are in the
            Fixed_Properties mapping.</p>

          <p>Properties in this array may either be required or optional,
            according to their documented semantics.</p>

          <tp:rationale>
            <p>For instance, if
              TargetHandleType takes a value that is not Handle_Type_None,
              one or the other of TargetHandle and TargetID is required.
              Clients are expected to understand the documented relationship
              between the properties, so we do not have separate arrays
              of required and optional properties.</p>
          </tp:rationale>

          <p>If this array contains the
            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
            property, then this class of channel can be combined with other
            channels with that property in a request, or added to an existing
            bundle. If not, this signifies that the connection manager is
            unable to mark channels of this class as part of a bundle - this
            means that to the remote contact they are likely to be
            indistinguishable from channels requested separately.</p>
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="RequestableChannelClasses" access="read"
      type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
      tp:name-for-bindings="Requestable_Channel_Classes">
      <tp:added version="0.17.11">(as stable API)</tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The classes of channel that are expected to be available on this
          connection, i.e. those for which
          <tp:member-ref>CreateChannel</tp:member-ref> can reasonably
          be expected to succeed. User interfaces can use this information
          to show or hide UI components.</p>

        <p>This property cannot change after the connection has gone to
          state Connection_Status_Connected, so there is no change
          notification (if the connection has context-dependent capabilities,
          it SHOULD advertise support for all classes of channel that it might
          support during its lifetime). Before this state has been reached,
          the value of this property is undefined.</p>

        <tp:rationale>
          <p>This is not on an optional interface, because connection
            managers can always offer some sort of clue about the channel
            classes they expect to support (at worst, they can announce
            support for everything for which they have code).</p>
        </tp:rationale>
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->