summaryrefslogtreecommitdiff
path: root/spec/Connection.xml
blob: 0ba095a9e93869f929b0bb2e85d1d8479f6e050e (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
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
<?xml version="1.0" ?>
<node name="/Connection"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
  >
  <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2005-2009 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.Connection">
    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Requests"/>
    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/>

    <tp:struct name="Channel_Info" array-name="Channel_Info_List">
      <tp:deprecated version="0.17.23"/>
      <tp:docstring>A struct representing a channel, as returned by
        ListChannels on the Connection interface.</tp:docstring>
      <tp:member type="o" name="Channel">
        <tp:docstring>The object path of the channel, which is on the
          same bus name as the connection</tp:docstring>
      </tp:member>
      <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type">
        <tp:docstring>The channel's type</tp:docstring>
      </tp:member>
      <tp:member type="u" tp:type="Handle_Type" name="Handle_Type">
        <tp:docstring>The type of the handle that the channel communicates
          with, or Handle_Type_None if there is no associated
          handle</tp:docstring>
      </tp:member>
      <tp:member type="u" tp:type="Handle" name="Handle">
        <tp:docstring>The handle that the channel communicates with,
          or 0 if there is no associated handle</tp:docstring>
      </tp:member>
    </tp:struct>

    <method name="Connect" tp:name-for-bindings="Connect">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request that the connection be established. This will be done
          asynchronously and errors will be returned by emitting
          <tp:member-ref>StatusChanged</tp:member-ref> signals.</p>

        <p>Calling this method on a Connection that is already connecting
          or connected is allowed, and has no effect.</p>
      </tp:docstring>
    </method>

    <method name="Disconnect" tp:name-for-bindings="Disconnect">
      <tp:docstring>
        Request that the connection be closed. This closes the connection if
        it's not already in DISCONNECTED state, and destroys the connection
        object.
      </tp:docstring>
    </method>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      access="read" type="as" tp:type="DBus_Interface[]">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The set of optional interfaces supported by this connection.
          Before the connection status changes to CONNECTED,
          this property may change at any time, but it is guaranteed that
          interfaces will only be added, not removed. After the connection
          status changes to CONNECTED, this property cannot
          change further.</p>

        <p>There is no explicit change notification; reasonable behaviour
          for a client would be to retrieve the interfaces list once
          initially, and once more when it becomes CONNECTED.</p>

        <tp:rationale>
          <p>In some connection managers, certain capabilities of a connection
            are known to be implemented for all connections (e.g. support
            for SimplePresence), and some interfaces (like SimplePresence) can
            even be used before connecting. Other capabilities may
            or may not exist, depending on server functionality; by the time
            the connection goes CONNECTED, the connection manager is expected
            to have evaluated the server's functionality and enabled any extra
            interfaces for the remainder of the Connection's lifetime.</p>
        </tp:rationale>
      </tp:docstring>
      <tp:added version="0.19.2">Clients SHOULD fall back
        to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this
        property is not supported.</tp:added>
    </property>

    <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
      <arg direction="out" type="as" tp:type="DBus_Interface[]"
        name="Interfaces">
        <tp:docstring>
          The value of the <tp:member-ref>Interfaces</tp:member-ref> property
        </tp:docstring>
      </arg>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Returns the set of optional interfaces supported by this
          connection. See <tp:member-ref>Interfaces</tp:member-ref> for more
          details.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
          <tp:docstring>
             Before version 0.17.8 calling GetInterfaces while
             on a connection that is not yet CONNECTED wasn't allowed. If a
             CM returns this error, its list of interfaces should be regarded
             as empty until it becomes CONNECTED.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="GetProtocol" tp:name-for-bindings="Get_Protocol">
      <arg direction="out" type="s" tp:type="Protocol" name="Protocol">
        <tp:docstring>
          A string identifier for the protocol
        </tp:docstring>
      </arg>

      <tp:docstring>
        Get the protocol this connection is using.
      </tp:docstring>
    </method>

    <signal name="SelfHandleChanged"
        tp:name-for-bindings="Self_Handle_Changed">
      <tp:docstring>
        Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
        changes. If the connection
        is not yet in the CONNECTED state, this signal is not guaranteed
        to be emitted.
      </tp:docstring>
      <tp:added version="0.17.10">Clients MAY assume that if the
        SelfHandle property exists, this signal will be emitted when
        necessary.</tp:added>

      <arg type="u" tp:type="Contact_Handle" name="Self_Handle">
        <tp:docstring>
          The new value of the SelfHandle property.
        </tp:docstring>
      </arg>
    </signal>

    <property name="SelfHandle" tp:name-for-bindings="Self_Handle"
      type="u" tp:type="Contact_Handle" access="read">
      <tp:docstring>
        The handle which represents the user on this connection, which will
        remain valid for the lifetime of this connection, or until a change
        in the user's identifier is signalled by the
        <tp:member-ref>SelfHandleChanged</tp:member-ref> signal.
        If the connection is not yet in the CONNECTED state, the value of
        this property MAY be zero.
      </tp:docstring>
      <tp:added version="0.17.10">For compatibility with older
        versions, clients should fall back to calling the
        <tp:member-ref>GetSelfHandle</tp:member-ref>
        method.</tp:added>
    </property>

    <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
      <arg direction="out" type="u" tp:type="Contact_Handle"
        name="Self_Handle">
        <tp:docstring>
          The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
        </tp:docstring>
      </arg>

      <tp:docstring>
        Returns the value of the SelfHandle property. Change notification
        is via the SelfHandleChanged signal.
      </tp:docstring>
      <tp:deprecated version="0.17.10">Use GetAll to get the
        SelfHandle property (and all other Connection properties)
        instead.</tp:deprecated>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
      </tp:possible-errors>
    </method>

    <property name="Status" tp:name-for-bindings="Status"
      access="read" type="u" tp:type="Connection_Status">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The current status of the connection. Change notification is via
          the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p>

        <p>If retrieval of property succeeds and yields the value Disconnected,
          this indicates that the connection has not yet been established.
          If connection has been attempted and failed, the Connection object
          SHOULD be removed from the bus entirely, meaning that retrieval of
          this property SHOULD fail.</p>
      </tp:docstring>
      <tp:added version="0.19.2">Clients SHOULD fall back
        to calling <tp:member-ref>GetStatus</tp:member-ref> if this
        property is not supported.</tp:added>
    </property>

    <method name="GetStatus" tp:name-for-bindings="Get_Status">
      <arg direction="out" type="u" tp:type="Connection_Status"
        name="Status">
        <tp:docstring>
          The value of the <tp:member-ref>Status</tp:member-ref> property
        </tp:docstring>
      </arg>

      <tp:docstring>
        Get the current status as defined in the
        <tp:member-ref>StatusChanged</tp:member-ref> signal.
      </tp:docstring>
    </method>

    <method name="HoldHandles" tp:name-for-bindings="Hold_Handles">
      <tp:changed version="0.21.6">If
        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
        this method no longer does anything.</tp:changed>
      <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          The type of handle to be held
        </tp:docstring>
      </arg>

      <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
        <tp:docstring>
          A array of integer handles to hold
        </tp:docstring>
      </arg>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
          which SHOULD always be the case in this version of telepathy-spec,
          this method does nothing and returns successfully, unless
          the given handle type or any of the given handles is invalid.</p>

        <p>In older connection managers, this method
        notifies the connection manger that your client is holding a copy
        of handles which may not be in use in any existing channel or
        list, and were not obtained by using the
        <tp:member-ref>RequestHandles</tp:member-ref> method. For
        example, a handle observed in an emitted signal, or displayed
        somewhere in the UI that is not associated with a channel. The
        connection manager must not deallocate a handle where any clients
        have used this method to indicate it is in use until the
        <tp:member-ref>ReleaseHandles</tp:member-ref>
        method is called, or the clients disappear from the bus.</p>

        <p>Note that HoldHandles is idempotent - calling it multiple times
          is equivalent to calling it once. If a handle is "referenced" by
          several components which share a D-Bus unique name, the client
          should perform reference counting internally, and only call
          ReleaseHandles when none of the cooperating components need the
          handle any longer.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The handle type is invalid
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            One of the given handles is not valid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="InspectHandles" tp:name-for-bindings="Inspect_Handles">
      <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          The type of handle to be inspected
        </tp:docstring>
      </arg>

      <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
        <tp:docstring>
          An array of integer handles of this type
        </tp:docstring>
      </arg>

      <arg direction="out" type="as" name="Identifiers">
        <tp:docstring>
          An array of identifiers corresponding to the given handles, in the same order.
        </tp:docstring>
      </arg>

      <tp:docstring>
        Return a string representation for a number of handles of a given
        type.
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The handle type is invalid
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            One of the given handles is not valid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="ListChannels" tp:name-for-bindings="List_Channels">
      <tp:deprecated version="0.17.23">Use the
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.Channels</tp:dbus-ref>
        property instead.
      </tp:deprecated>

      <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"
        name="Channel_Info">
        <tp:docstring>
          An array of structs representing channels.
        </tp:docstring>
      </arg>

      <tp:docstring>
        List all the channels which currently exist on this connection.
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
      </tp:possible-errors>
    </method>

    <signal name="NewChannel" tp:name-for-bindings="New_Channel">
      <tp:deprecated version="0.17.23">Connection managers MUST still
        emit this signal, but clients SHOULD listen for the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.NewChannels</tp:dbus-ref>
        signal instead.
      </tp:deprecated>

      <arg name="Object_Path" type="o">
        <tp:docstring>
          A D-Bus object path for the channel object on this service
        </tp:docstring>
      </arg>

      <arg name="Channel_Type" type="s" tp:type="DBus_Interface">
        <tp:docstring>
          A D-Bus interface name representing the channel type
        </tp:docstring>
      </arg>

      <arg name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          An integer representing the type of handle this channel
          communicates with, or Handle_Type_None if no handle is specified
        </tp:docstring>
      </arg>

      <arg name="Handle" type="u" tp:type="Handle">
        <tp:docstring>
          A handle indicating the specific contact, room or list this
          channel communicates with, or zero if no handle is specified
        </tp:docstring>
      </arg>

      <arg name="Suppress_Handler" type="b">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If true, the channel was requested by a client that intends to
            present it to the user itself (i.e. it passed suppress_handler=TRUE
            to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no
            other handler should be
            launched. Clients MAY assume that channels where this is true
            were created by a user request.</p>

          <p>If false, either the channel was created due to incoming
            information from the service, or the channel was requested by
            a local client that does not intend to handle the channel itself
            (this usage is deprecated).</p>

          <p>Clients MUST NOT assume that only incoming channels will have
            this flag set to false.</p>
        </tp:docstring>
      </arg>

      <tp:docstring>
        Emitted when a new Channel object is created, either through user
        request or incoming information from the service.
      </tp:docstring>
    </signal>

    <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles">
      <tp:changed version="0.21.6">If
        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
        this method no longer does anything.</tp:changed>
      <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          An integer handle type (as defined in RequestHandle)
        </tp:docstring>
      </arg>

      <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
        <tp:docstring>
          An array of integer handles being held by the client
        </tp:docstring>
      </arg>

      <tp:docstring>
        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
          which SHOULD always be the case in this version of telepathy-spec,
          this method does nothing and returns successfully, unless
          the given handle type or any of the given handles is invalid.</p>

        <p>In older connection managers, this method
        explicitly notifies the connection manager that your client is no
        longer holding any references to the given handles, and that they
        may be deallocated if they are not held by any other clients or
        referenced by any existing channels. See
        <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The handle type is invalid
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            One of the given handles is not valid
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="RequestChannel" tp:name-for-bindings="Request_Channel">
      <tp:deprecated version="0.17.23">Use
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.CreateChannel</tp:dbus-ref>
        or <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
        instead. Connection managers MAY implement RequestChannel by
        raising NotImplemented, or implement fewer types of channel via
        this API.</tp:deprecated>

      <arg direction="in" name="Type" type="s" tp:type="DBus_Interface">
        <tp:docstring>
          A D-Bus interface name representing base channel type
        </tp:docstring>
      </arg>

      <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          An integer representing the handle type, or Handle_Type_None if
          no handle is specified
        </tp:docstring>
      </arg>

      <arg direction="in" name="Handle" type="u" tp:type="Handle">
        <tp:docstring>
          A nonzero integer handle representing a contact, room, list etc.
          according to handle_type, or zero if the handle_type is
          Handle_Type_None
        </tp:docstring>
      </arg>

      <arg direction="in" name="Suppress_Handler" type="b">
        <tp:docstring>
          <p>Clients SHOULD always set this to true.</p>

          <tp:rationale>
            <p>The historical meaning was that clients that did not
              intend to take responsibility for displaying the channel to
              the user could set this to FALSE, in which case the channel
              dispatcher would launch an appropriate channel handler.</p>

            <p>However, clients whose functionality relies on having a
              working channel dispatcher should obtain that functionality by
              calling methods on the channel dispatcher, so that they will
              get an appropriate error if the channel dispatcher is missing
              or not working.</p>

            <p>The channel dispatcher itself should set this to true too,
              so that it will ignore the
              <tp:member-ref>NewChannel</tp:member-ref> signal that results
              from the creation of the channel. It can then dispatch the
              channel returned from this method to an
              appropriate handler.</p>

            <p>So, there is no sensible use-case for setting this to false,
              and setting it to false can result in unhandled channels (in
              the case where clients assume that a channel dispatcher is
              present, but it isn't).</p>
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg direction="out" type="o" name="Object_Path">
        <tp:docstring>
          The D-Bus object path for the channel created or retrieved
        </tp:docstring>
      </arg>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request a channel satisfying the specified type and communicating
          with the contact, room, list etc. indicated by the given
          handle_type and handle. The handle_type and handle may both be
          zero to request the creation of a new, empty channel, which may
          or may not be possible, depending on the protocol and channel
          type.</p>

        <p>On success, the returned channel will always be of the requested
          type (i.e. implement the requested channel-type interface).</p>

        <p>If a new, empty channel is requested, on success the returned
          channel will always be an "anonymous" channel for which the type
          and handle are both zero.</p>

        <p>If a channel to a contact, room etc. is requested, on success, the
          returned channel may either be a new or existing channel to
          the requested entity (i.e. its
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
          and <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
          properties are the
          requested handle type and handle), or a newly created "anonymous"
          channel associated with the requested handle in some
          implementation-specific way.</p>

        <p>For example, for a contact handle, the returned channel
          might be "anonymous", but implement the groups interface and have
          the requested contact already present among the members.</p>

        <p>If the request cannot be satisfied, an error is raised and no
          channel is created.</p>
      </tp:docstring>

      <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>
            Unknown channel type
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            The given handle does not exist or cannot be created
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The requested channel type cannot be created with the given handle
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
          <tp:docstring>
            The requested channel cannot be created because contact doesn't
            have the required capabilities.
          </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:possible-errors>
    </method>

    <tp:enum name="Handle_Type" type="u">
      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          A "null" handle type used to indicate the absence of a handle.
          When a handle type and a handle appear as a pair, if the handle
          type is zero, the handle must also be zero.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Contact" value="1">
        <tp:docstring>
          A contact
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Room" value="2">
        <tp:docstring>
          A chat room
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="List" value="3">
        <tp:docstring>
          A server-generated contact list (see Channel.Interface.Group)
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Group" value="4">
        <tp:docstring>
          A user-defined contact list (see Channel.Interface.Group)
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:simple-type name="Handle" type="u" array-name="Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a
        handle</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="Contact_Handle" type="u"
      array-name="Contact_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_Contact</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="Room_Handle" type="u"
      array-name="Room_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_Room</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="List_Handle" type="u"
      array-name="List_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_List</tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="Group_Handle" type="u"
      array-name="Group_Handle_List">
      <tp:docstring>An unsigned 32-bit integer representing a handle of type
        Handle_Type_Group</tp:docstring>
    </tp:simple-type>

    <method name="RequestHandles" tp:name-for-bindings="Request_Handles">
      <tp:changed version="0.21.6">If
        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
        this method no longer has its reference-counting effect.</tp:changed>
      <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
        <tp:docstring>
          The type of handle required
        </tp:docstring>
      </arg>

      <arg direction="in" name="Identifiers" type="as">
        <tp:docstring>
          An array of identifiers of entities to request handles for
        </tp:docstring>
      </arg>

      <arg direction="out" type="au" tp:type="Handle[]"
        name="Handles">
        <tp:docstring>
          An array of integer handle numbers in the same order as the given identifiers.
        </tp:docstring>
      </arg>

      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Request several handles from the connection manager which represent a
          number of contacts, rooms or server-stored lists on the service.</p>

        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
          which SHOULD always be the case in this version of telepathy-spec,
          the handles remain valid until the connection disconnects.</p>

        <p>The implementation of this method in older connection managers
        must record that these handles are in use by the
        client who invokes this method, and must not deallocate the handles
        until the client disconnects from the bus or calls the
        <tp:member-ref>ReleaseHandles</tp:member-ref>
        method. Where the identifier refers to an entity that already has a
        handle in this connection manager, this handle should be returned
        instead. The handle number 0 must not be returned by the connection
        manager.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
          <tp:docstring>
            The given identifier does not identify a valid entity of the given
            type.

            <tp:rationale>
              For instance, an XMPP connection would raise this error for
              identifiers with type Handle_Type_Room that do not contain
              exactly one '@' character, that contain spaces, and so on.
            </tp:rationale>
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The given handle type is not valid, or is not implemented on this
            connection.

            <tp:rationale>
              For instance, a connection to a protocol that doesn't have
              chat rooms would raise this error for room handles, and all CMs
              would raise this error for Handle_Type_None.
            </tp:rationale>
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u">
      <tp:enumvalue suffix="Connected" value="0">
        <tp:docstring>
          The connection is fully connected and all methods are available.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Connecting" value="1">
        <tp:docstring>
          <tp:member-ref>Connect</tp:member-ref> has been called but the
          connection has not yet been established. Some methods may fail
          until the connection has been established.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Disconnected" value="2">
        <tp:docstring>
          If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or
          <tp:member-ref>Status</tp:member-ref>, it indicates that connection
          has not yet been attempted. If seen in a
          <tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates
          that the connection has failed; the Connection object SHOULD be
          removed from D-Bus immediately, and all subsequent method calls
          SHOULD fail.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="Connection_Status_Reason" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A reason why the status of the connection changed. Apart from
          Requested, the values of this enumeration only make sense as
          reasons why the status changed to Disconnected.</p>
      </tp:docstring>

      <tp:enumvalue suffix="None_Specified" value="0">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There is no reason set for this state change. Unknown status
            reasons SHOULD be treated like this reason.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Requested" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The change is in response to a user request. Changes to the
            Connecting or Connected status SHOULD always indicate this reason;
            changes to the Disconnected status SHOULD indicate this reason
            if and only if the disconnection was requested by the user.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Network_Error" value="2">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was an error sending or receiving on the network socket.</p>

          <p>When the status changes from Connecting to Disconnected for this
            reason, the equivalent D-Bus error is either
            <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
            <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
            <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
            or some more specific error.</p>

          <p>When the status changes from Connected to Disconnected for this
            reason, the equivalent D-Bus error is either
            <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
            <code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
            or some more specific error.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Authentication_Failed" value="3">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The username or password was invalid.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Encryption_Error" value="4">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was an error negotiating SSL on this connection, or
            encryption was unavailable and require-encryption was set when the
            connection was created.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code>
            if encryption was not available at all, or
            <code>org.freedesktop.Telepathy.Error.EncryptionError</code>
            if encryption failed.</p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Name_In_Use" value="5">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>In general, this reason indicates that the requested account
            name or other identification could not be used due to conflict
            with another connection. It can be divided into three cases:</p>

          <ul>
            <li>If the status change is from Connecting to Disconnected
              and the 'register' parameter to RequestConnection was present
              and true, the requested account could not be created on the
              server because it already exists.
              The equivalent D-Bus error is
              <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
            </li>

            <li>If the status change is from Connecting to Disconnected
              but the 'register' parameter is absent or false, the connection
              manager could not connect to the specified account because
              a connection to that account already exists.
              The equivalent D-Bus error is
              <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.

              <tp:rationale>
                In some protocols, like XMPP (when connecting with the same
                JID and resource as an existing connection), the existing
                connection "wins" and the new one fails to connect.
              </tp:rationale>
            </li>

            <li>If the status change is from Connected to Disconnected,
              the existing connection was automatically disconnected because
              a new connection to the same account (perhaps from a different
              client or location) was established.
              The equivalent D-Bus error is
              <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.

              <tp:rationale>
                In some protocols, like MSNP (when connecting twice with the
                same Passport), the new connection "wins" and the
                existing one is automatically disconnected.
              </tp:rationale>
            </li>
          </ul>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Not_Provided" value="6">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server did not provide a SSL certificate.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Untrusted" value="7">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is signed by an untrusted certifying
            authority. This error SHOULD NOT be used to represent a self-signed
            certificate: use the more specific Cert_Self_Signed reason for
            that.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Expired" value="8">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate has expired.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Not_Activated" value="9">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is not yet valid.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate did not match its hostname.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate does not have the expected
            fingerprint.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Self_Signed" value="12">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate is self-signed.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Other_Error" value="13">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>There was some other error validating the server's SSL
            certificate.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Revoked" value="14">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate has been revoked.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Insecure" value="15">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The server's SSL certificate uses an insecure algorithm,
	  or is cryptographically weak.</p>

          <p>When disconnected for this reason, the equivalent D-Bus error is
            <code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>.
          </p>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16">
	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	  <p>The length in bytes of the server certificate, or the depth of the
	  sever certificate chain exceed the limits imposed by the crypto
	  library.</p>

	  <p>When disconnected for this reason, the equivalent D-Bus error is
	    <code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code>
	  </p>
	</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <signal name="ConnectionError" tp:name-for-bindings="Connection_Error">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when an error occurs that renders this connection unusable.
        </p>

        <p>Whenever this signal is emitted, it MUST immediately be followed by
          a <tp:member-ref>StatusChanged</tp:member-ref> signal with status
          Connection_Status_Disconnected and an appropriate reason
          code.</p>

        <p>Connection managers SHOULD emit this signal on disconnection, but
          need not do so. Clients MUST support connection managers that emit
          StatusChanged(Disconnected, ...) without first emitting
          ConnectionError.</p>

        <tp:rationale>
          <p>This signal provides additional information about the reason
            for disconnection. The reason for connection is always
            straightforward - it was requested - so it does not need further
            explanation. However, on errors, it can be useful to provide
            additional information.</p>

          <p>The <tp:type>Connection_Status_Reason</tp:type> is not given
            here, since it will be signalled in
            <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client
            implementation would be to store the information given by this
            signal until StatusChanged is received, at which point the
            information given by this signal can be used to supplement the
            StatusChanged signal.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Error" type="s" tp:type="DBus_Error_Name">
        <tp:docstring>
          The name of a D-Bus error describing the error that occurred,
          which may correspond to a
          <tp:type>Connection_Status_Reason</tp:type>, or may be a more
          specific Telepathy error
          (such as
          <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>
          for Connection_Status_Reason_Network_Error)
          or a protocol-specific or connection-manager-specific error in a
          suitable namespace.

          <tp:rationale>
            For instance, a SIP connection manager could signal
            "402 Payment Required" as an error in a
            connection-manager-specific namespace, or a link-local
            XMPP implementation that used Avahi could provide the error
            given to it by the avahi-daemon.
          </tp:rationale>
        </tp:docstring>
      </arg>

      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Additional information about the error, which may include
            the following well-known keys:</p>

          <dl>
            <dt>debug-message (s)</dt>
            <dd>Debugging information on the change, corresponding to the
              message part of a D-Bus error message, which SHOULD NOT be
              displayed to users under normal circumstances</dd>

            <dt>server-message (s)</dt>
            <dd>A human-readable message from the server explaining what
              happened. This may be in the user's native language, or in the
              server operator's native language, or even in Lojban.</dd>

	    <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
	    <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd>
          </dl>

        </tp:docstring>
      </arg>

    </signal>

    <signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
      <arg name="Status" type="u" tp:type="Connection_Status">
        <tp:docstring>
          An integer indicating the new status, as defined by ConnectionStatus
        </tp:docstring>
      </arg>

      <arg name="Reason" type="u" tp:type="Connection_Status_Reason">
        <tp:docstring>
          An integer indicating the reason for the status change, as defined
          by ConnectionStatusReason
        </tp:docstring>
      </arg>

      <tp:docstring>
        Emitted when the status of the connection changes.  All states and
        reasons have numerical values, as defined in ConnectionStatus
        and ConnectionStatusReason.
      </tp:docstring>
    </signal>

    <tp:contact-attribute name="contact-id" type="s">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The same string that would be returned by
          <tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
          this is always present in the result of <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
          whether it was explicitly requested or not.</p>
      </tp:docstring>
    </tp:contact-attribute>

    <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest">
      <tp:added version="0.21.3"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Register a client's interest in notifications related to one or
          more interfaces.</p>

        <p>Groups of notifications are identified by a token which is either
          a D-Bus interface name, or a string that starts with a D-Bus
          interface name. The meaning of each token is given by that D-Bus
          interface, which MUST define it in its documentation.</p>

        <tp:rationale>
          <p>Initially, all interests are in entire interface, but allowing
            other strings allows subscription to part of an interface; for
            instance, an interest in ...MailNotification/count could track
            the number of messages without caring about their detailed
            content.</p>
        </tp:rationale>

        <p>For each token with which this method interacts, the
          Connection tracks an "interest count" (like a reference count) for
          each unique bus name that has called this method. When a client
          calls this method, for each token, the interest count for its
          unique bus name is incremented; when
          <tp:member-ref>RemoveClientInterest</tp:member-ref> is called,
          all interest counts for that unique bus name are decremented.
          If the unique bus name leaves the bus (for instance, if the
          client crashes or exits), all interest counts for that unique bus
          name are set to zero.</p>

        <p>The Connection can then use these reference counts to
          avoid subscribing to protocol-level notifications unless at least
          one client has a non-zero interest count for the relevant
          token.</p>

        <tp:rationale>
          <p>This method exists to reduce memory and network overhead when
            there is no active subscription.</p>

          <p>One situation where this is useful is <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection.Interface"
              >Location</tp:dbus-ref>: on XMPP, location updates are received
            over PEP. If the Connection advertises the
            <code>geoloc+notify</code> capability, it will be sent location
            updates for all contacts. To avoid consuming resources for this,
            the connection should avoid advertising that capability until
            a client has expressed an interest in contacts' locations.</p>

          <p>Another example of a protocol that benefits from this method is
            the Google XMPP Mail Notification extension, which can be used
            to implement <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection.Interface"
              >MailNotification</tp:dbus-ref>. In this protocol, the CM
            receives a notification that something has changed, but to get
            more information, the CM must request this information. Knowing
            that nobody is currently interested in this information, the CM
            can avoid generating useless network traffic. Similarly, the CM
            may free the list of unread messages to reduce memory overhead.</p>
        </tp:rationale>

        <p>If this method is called for an interface that might require
          protocol-level subscription, but the connection cannot set up
          that subscription yet (for instance because the
          <tp:member-ref>Status</tp:member-ref> is not Connected yet), the
          Connection MUST remember the client's interest, and attempt to
          subscribe to the appropriate protocol feature when this becomes
          possible.</p>

        <p>Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.</p>

        <tp:rationale>
          <p>The only reason it could fail is if it's unimplemented, in which
            case the only thing the client can usefully do is to proceed as if
            it had succeeded.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Tokens" type="as" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Interfaces or parts of interfaces in which to register an
            interest, represented by either a
            <tp:type>DBus_Interface</tp:type>, or a string prefixed with a
            <tp:type>DBus_Interface</tp:type>.</p>

          <p>If the Connection does not support one of these tokens, this
            is not considered to be an error; the unsupported token is
            simply ignored.</p>
        </tp:docstring>
      </arg>
    </method>

    <method name="RemoveClientInterest"
      tp:name-for-bindings="Remove_Client_Interest">
      <tp:added version="0.21.3"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Release an interest registered using
          <tp:member-ref>AddClientInterest</tp:member-ref>. See that
          method's documentation for details.</p>

        <p>Clients MAY ignore any errors raised by this method; it is intended
          to be called with the reply ignored.</p>

        <tp:rationale>
          <p>The only reasons it could fail are if it's unimplemented, or if
            the client's reference-counting is wrong and it has tried to
            remove a client interest that it did not add. In both cases,
            there's nothing the client could do about it.</p>
        </tp:rationale>
      </tp:docstring>

      <arg name="Tokens" type="as" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Interfaces or parts of interfaces that were previously passed to
            <tp:member-ref>AddClientInterest</tp:member-ref>.</p>
        </tp:docstring>
      </arg>
    </method>

    <property name="HasImmortalHandles"
      tp:name-for-bindings="Has_Immortal_Handles"
      access="read" type="b">
      <tp:added version="0.21.6"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>True if handles last for the whole lifetime of the Connection.
          This SHOULD be the case in all connection managers, but clients
          MUST interoperate with older connection managers
          (which reference-count handles).</p>
      </tp:docstring>
    </property>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This models a connection to a single user account on a communication
        service. Its basic capability is to provide the facility to request and
        receive channels of differing types (such as text channels or streaming
        media channels) which are used to carry out further communication.</p>

      <p>In order to allow Connection objects to be discovered by new clients,
        the object path and well-known bus name MUST be of the form
        <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
        and
        <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
        where:</p>

      <ul>
        <li><em>cmname</em> is the same
          <tp:type>Connection_Manager_Name</tp:type> that appears
          in the connection manager's object path and well-known bus name</li>
        <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>,
          but with "-" replaced with "_" to get a valid
          object path/bus name</li>
        <li><em>account</em> is some non-empty sequence of ASCII letters,
          digits and underscores not starting with a digit</li>
      </ul>

      <p><em>account</em> SHOULD be formed such that any valid distinct
        connection instance on this protocol has a distinct name. This
        might be formed by including the server name followed by the user
        name (escaped via some suitable mechanism like telepathy-glib's
        tp_escape_as_identifier() function to preserve uniqueness); on
        protocols where connecting multiple times is permissable, a
        per-connection identifier might be necessary to ensure
        uniqueness.</p>

      <p>Clients MAY parse the object path to determine the connection
        manager name and the protocol, but MUST NOT attempt to parse the
        <em>account</em> part. Connection managers MAY use any unique string
        for this part.</p>

    <p>As well as the methods and signatures below, arbitrary interfaces may be
    provided by the Connection object to represent extra connection-wide
    functionality, such as the Connection.Interface.SimplePresence for
    receiving and
    reporting presence information, and Connection.Interface.Aliasing for
    connections where contacts may set and change an alias for themselves.
    These interfaces can be discovered using the
    <tp:member-ref>GetInterfaces</tp:member-ref> method.</p>

    <p>Contacts, rooms, and server-stored lists (such as subscribed contacts,
    block lists, or allow lists) on a service are all represented by
    immutable <em>handles</em>, which are unsigned non-zero integers which are
    valid only for the lifetime of the connection object, and are used
    throughout the protocol where these entities are represented, allowing
    simple testing of equality within clients.</p>

    <p>Zero as a handle value is sometimes used as a "null" value to mean
    the absence of a contact, room, etc.</p>

    <p>Handles have per-type uniqueness, meaning that
    every (handle type, handle number) tuple is guaranteed to be unique within
    a connection and that a handle alone (without its type) is meaningless or
    ambiguous. Connection manager implementations should reference count these
    handles to determine if they are in use either by any active clients or any
    open channels, and may deallocate them when this ceases to be true. Clients
    may request handles of a given type and identifier with the
    <tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
    identifier with the <tp:member-ref>InspectHandles</tp:member-ref>
    method, keep handles from being released with
    <tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
    longer storing handles with
    <tp:member-ref>ReleaseHandles</tp:member-ref>.</p>
    </tp:docstring>

    <tp:changed version="0.17.10">Previously, the account part of
      Connection bus names/object paths was allowed to have more than one
      component (i.e. contain dots or slashes), resulting in Connection
      bus names and object paths with more than 7 components. We now restrict
      Connection bus names/object paths to have exactly 7
      components.</tp:changed>

    <tp:changed version="0.17.23">The Requests and Contacts interfaces
      are now mandatory. Their functionality will be merged into the main
      Connection interface at some point in future.</tp:changed>

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