summaryrefslogtreecommitdiff
path: root/spec/Channel_Dispatcher.xml
blob: 2dd000b4021bfbc70cec7ed7058faf3b274ba079 (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
<?xml version="1.0" ?>
<node name="/Channel_Dispatcher"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">

  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2008-2009 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.ChannelDispatcher">
    <tp:added version="0.17.26">(as a stable interface)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>The channel dispatcher is responsible for responding to new
        channels and launching client processes to handle them. It also
        provides functionality for client processes to request that new
        channels are created.</p>

      <p>If a channel dispatcher is running, it is responsible for dispatching
        new channels on all
        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s
        created by the
        <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
        Connections not created by the AccountManager are outside the scope
        of the channel dispatcher.</p>

      <tp:rationale>
        <p>Connections created by standalone Telepathy clients
          that do not intend to interact with the channel dispatcher
          should be ignored - otherwise, the channel dispatcher would try
          to launch handlers for channels that the standalone client
          was already handling internally.</p>
      </tp:rationale>

      <p>The current channel dispatcher is defined to be the process that
        owns the well-known bus name
        <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on
        the session bus. This process MUST export an object with this
        interface at the object path
        <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p>

      <p>Until a mechanism exists for making a reasonable automatic choice
        of ChannelDispatcher implementation, implementations SHOULD NOT
        register as an activatable service for the ChannelDispatcher's
        well-known bus name. Instead, it is RECOMMENDED that some component
        of the user's session will select and activate a particular
        implementation, and that other Telepathy-enabled programs
        can detect whether channel request/dispatch functionality is available
        by checking whether the ChannelDispatcher's well-known name is in use
        at runtime.</p>

      <p>There are three categories of client process defined by this
        specification:</p>

      <dl>
        <dt><tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt>
        <dd><p>Observers monitor the creation of new channels. This
            functionality can be used for things like message logging.
            All observers are notified simultaneously.</p></dd>

        <dt><tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>
        <dd>
          <p>Approvers notify the user that new channels have been created,
            and also select which channel handler will be used for the channel,
            either by asking the user or by choosing the most appropriate
            channel handler.</p>
        </dd>

        <dt><tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt>
        <dd>
          <p>Each new channel or set of channels is passed to exactly one
            handler as its final destination. A typical channel handler is a
            user interface process handling channels of a particular type.</p>
        </dd>
      </dl>
    </tp:docstring>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" access="read" tp:type="DBus_Interface[]">
      <tp:docstring>
        A list of the extra interfaces provided by this channel dispatcher.
      </tp:docstring>
    </property>

    <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Equivalent to calling
          <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty
          <var>Hints</var> parameter.</p>
      </tp:docstring>

      <arg direction="in" name="Account" type="o">
        <tp:docstring>
          The
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
          for which the new channel is to be created.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Requested_Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="User_Action_Time" type="x"
        tp:type="User_Action_Timestamp">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The time at which user action occurred, or 0 if this channel
            request is for some reason not involving user action.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="Preferred_Handler" type="s"
        tp:type="DBus_Well_Known_Name">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Either the well-known bus name (starting with
            <code>org.freedesktop.Telepathy.Client.</code>)
            of the preferred handler for this
            channel, or an empty string to indicate that any handler would be
            acceptable.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
        <tp:changed version="0.19.0">
          Previously, the spec didn't say that this should disregard the
          handler's filter. This has been implemented since
          telepathy-mission-control 5.3.2.
        </tp:changed>
      </arg>

      <arg direction="out" name="Request" type="o">
        <tp:docstring>
          A
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The Preferred_Handler is syntactically invalid or does
            not start with <code>org.freedesktop.Telepathy.Client.</code>,
            the Account does not exist, or one of the Requested_Properties
            is invalid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>

    </method>

    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Equivalent to calling
          <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty
          <var>Hints</var> parameter.</p>
      </tp:docstring>

      <arg direction="in" name="Account" type="o">
        <tp:docstring>
          The
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
          for which the new channel is to be created.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Requested_Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="User_Action_Time" type="x"
        tp:type="User_Action_Timestamp">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The time at which user action occurred, or 0 if this channel
            request is for some reason not involving user action.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="Preferred_Handler" type="s"
        tp:type="DBus_Well_Known_Name">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Either the well-known bus name (starting with
            <code>org.freedesktop.Telepathy.Client.</code>)
            of the preferred handler for this
            channel, or an empty string to indicate that any handler would be
            acceptable. The behaviour and rationale are the same as for the
            corresponding parameter to
            <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="out" name="Request" type="o">
        <tp:docstring>
          A
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The Preferred_Handler is syntactically invalid or does
            not start with <code>org.freedesktop.Telepathy.Client.</code>,
            the Account does not exist, or one of the Requested_Properties
            is invalid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>

    </method>

    <method name="CreateChannelWithHints"
            tp:name-for-bindings="Create_Channel_With_Hints">
      <tp:added version="0.21.5">
        Support for this method is indicated by the
        <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
        Clients MUST recover from this method being unsupported by falling back
        to <tp:dbus-ref
          namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>.
      </tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Start a request to create a channel. This initially just creates a
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object, which can be used to continue the request and track its
          success or failure.</p>

        <tp:rationale>
          <p>The request can take a long time - in the worst case, the
            channel dispatcher has to ask the account manager to put the
            account online, the account manager has to ask the operating
            system to obtain an Internet connection, and the operating
            system has to ask the user whether to activate an Internet
            connection using an on-demand mechanism like dialup.</p>

          <p>This means that using a single D-Bus method call and response
            to represent the whole request will tend to lead to that call
            timing out, which is not the behaviour we want.</p>
        </tp:rationale>

        <p>If this method is called for an Account that is disabled, invalid
          or otherwise unusable, no error is signalled until
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
          is called, at which point
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
          is emitted with an appropriate error.</p>

        <tp:rationale>
          <p>This means there's only one code path for errors, apart from
            InvalidArgument for "that request makes no sense".</p>

          <p>It also means that the request will proceed if the account is
            enabled after calling CreateChannel, but before calling
            Proceed.</p>
        </tp:rationale>
      </tp:docstring>

      <arg direction="in" name="Account" type="o">
        <tp:docstring>
          The
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
          for which the new channel is to be created.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Requested_Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties. This has the same
            semantics as the corresponding parameter to
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
          </p>

          <p>Certain properties will not necessarily make sense in this
            dictionary: for instance,
            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
            can only be given if the requester is able to interact with a
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
            to the desired account.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="User_Action_Time" type="x"
        tp:type="User_Action_Timestamp">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The time at which user action occurred, or 0 if this channel
            request is for some reason not involving user action.
            The <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
            property will be set to this value, and it will eventually be
            passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="Preferred_Handler" type="s"
        tp:type="DBus_Well_Known_Name">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Either the well-known bus name (starting with
            <code>org.freedesktop.Telepathy.Client.</code>)
            of the preferred handler for this
            channel, or an empty string to indicate that any handler would be
            acceptable. The channel dispatcher SHOULD dispatch as many as
            possible of the resulting channels (ideally, all of them)
            to that handler—irrespective of whether that handler's <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
            matches the channel—and SHOULD remember the preferred handler
            so it can try to dispatch subsequent channels in the same bundle
            to the same handler.</p>

          <tp:rationale>
            <p>This must be the well-known bus name, not the unique name,
              to ensure that all handlers do indeed have the Client API,
              and the Client object on the handler can be located easily.</p>

            <p>This is partly so the channel dispatcher can call
              <tp:dbus-ref
                namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
              on it, and partly so the channel dispatcher
              can recover state if it crashes and is restarted.</p>

            <p>The filter should be disregarded for ease of use of this
              interface: clients will usually use this argument to request
              channels be sent to themself, and this should trump the filter
              not matching. This also allows a client to become the handler
              for a channel produced by one of its own requests, while not
              being a candidate to handle other channels of that type.</p>
          </tp:rationale>

          <p>If this is a well-known bus name and the handler has the
            Requests interface, the channel dispatcher SHOULD
            call <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
            on that Handler after this method has returned.</p>

          <tp:rationale>
            <p>This ordering allows a Handler which calls CreateChannel with
              itself as the preferred handler to associate the call to
              AddRequest with that call.</p>
          </tp:rationale>

          <p>This is copied to the ChannelRequest that is returned,
            as the <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
            property.</p>
        </tp:docstring>

        <tp:changed version="0.19.0">
          Previously, the spec didn't say that this should disregard the
          handler's filter. This has been implemented since
          telepathy-mission-control 5.3.2.
        </tp:changed>
      </arg>

      <arg direction="in" name="Hints" type="a{sv}">
        <tp:docstring>
          <p>Additional information about the channel request, which will be
            used as the value for the resulting request's <tp:dbus-ref
              namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
            property.</p>

          <tp:rationale>
            <p>See the Hints property's documentation for rationale.</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg direction="out" name="Request" type="o">
        <tp:docstring>
          A
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The Preferred_Handler is syntactically invalid or does
            not start with <code>org.freedesktop.Telepathy.Client.</code>,
            the Account does not exist, or one of the Requested_Properties
            is invalid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>

    </method>

    <method name="EnsureChannelWithHints"
            tp:name-for-bindings="Ensure_Channel_With_Hints">
      <tp:added version="0.21.5">
        Support for this method is indicated by the
        <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
        Clients MUST recover from this method being unsupported by falling back
        to <tp:dbus-ref
          namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>.
      </tp:added>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Start a request to ensure that a channel exists, creating it if
          necessary.  This initially just creates a <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object, which can be used to continue the request and track its
          success or failure.</p>

        <p>If this method is called for an Account that is disabled, invalid
          or otherwise unusable, no error is signalled until
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
          is called, at which point
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
          is emitted with an appropriate error.</p>

        <tp:rationale>
          <p>The rationale is as for <tp:dbus-ref
              namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p>
        </tp:rationale>
      </tp:docstring>

      <arg direction="in" name="Account" type="o">
        <tp:docstring>
          The
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
          for which the new channel is to be created.
        </tp:docstring>
      </arg>

      <arg direction="in" name="Requested_Properties" type="a{sv}"
        tp:type="Qualified_Property_Value_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A dictionary containing desirable properties. This has the same
            semantics as the corresponding parameter to
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
          </p>

          <p>Certain properties will not necessarily make sense in this
            dictionary: for instance,
            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
            can only be given if the requester is able to interact with a
            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
            to the desired account.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="User_Action_Time" type="x"
        tp:type="User_Action_Timestamp">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The time at which user action occurred, or 0 if this channel
            request is for some reason not involving user action.</p>

          <p>This parameter is used in the same way as the corresponding
            parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
        </tp:docstring>
      </arg>

      <arg direction="in" name="Preferred_Handler" type="s"
        tp:type="DBus_Well_Known_Name">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Either the well-known bus name (starting with
            <code>org.freedesktop.Telepathy.Client.</code>)
            of the preferred handler for this
            channel, or an empty string to indicate that any handler would be
            acceptable. The behaviour and rationale are the same as for the
            corresponding parameter to
            <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except
            as noted here.</p>

          <p>If any new channels are created in response to this
            request, the channel dispatcher SHOULD dispatch as many as
            possible of the resulting channels (ideally, all of them)
            to that handler, and SHOULD remember the preferred handler
            so it can try to dispatch subsequent channels in the same bundle
            to the same handler. If the requested channel already exists (that
            is, <tp:dbus-ref
              namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
            returns <code>Yours=False</code>) then the channel dispatcher
            SHOULD re-dispatch the channel to its existing handler, and MUST
            NOT dispatch it to this client (unless it is the existing handler);
            the request is still deemed to have succeeded in this case.</p>

          <tp:rationale>
            <p>An address book application, for example, might call <tp:dbus-ref
                namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
              to ensure that a text channel with a particular contact is
              displayed to the user; it does not care whether a new channel was
              made. An IM client might call <tp:dbus-ref
                namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
              in response to the user double-clicking an entry in the contact
              list, with itself as the <code>Preferred_Handler</code>; if the
              user already has a conversation with that contact in another
              application, they would expect the existing window to be
              presented, rather than their double-click leading to an error
              message.  So the request should succeed, even if its
              <code>Preferred_Handler</code> is not used.</p>
          </tp:rationale>

        </tp:docstring>
      </arg>

      <arg direction="in" name="Hints" type="a{sv}">
        <tp:docstring>
          Additional information about the channel request, which will be used
          as the value for the resulting request's <tp:dbus-ref
          namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
          property.</tp:docstring>
      </arg>

      <arg direction="out" name="Request" type="o">
        <tp:docstring>
          A
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
          object.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The Preferred_Handler is syntactically invalid or does
            not start with <code>org.freedesktop.Telepathy.Client.</code>,
            the Account does not exist, or one of the Requested_Properties
            is invalid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>

    </method>

    <property name="SupportsRequestHints"
              tp:name-for-bindings="Supports_Request_Hints"
              type="b" access="read">
      <tp:added version="0.21.5"/>
      <tp:docstring>
        If <code>True</code>, the channel dispatcher is new enough to support
        <tp:member-ref>CreateChannelWithHints</tp:member-ref> and
        <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition
        to the older <tp:dbus-ref
          namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>
        and <tp:dbus-ref
          namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
        methods, and also new enough to emit <tp:dbus-ref
          namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref>
        before the older <tp:dbus-ref
          namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal.
        If <code>False</code> or missing, only the metadata-less
        variants are supported.
      </tp:docstring>
    </property>

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