← Back to branch summary

~ubuntu-branches/ubuntu/wily/telepathy-glib/wily

« back to all changes in this revision

Viewing changes to spec/Channel_Interface_Group.xml

  • Committer: Bazaar Package Importer
  • Author(s): Simon McVittie
  • Date: 2009-03-24 22:06:52 UTC
  • mfrom: (1.3.1 upstream) (17.1.10 sid)
  • Revision ID: james.westby@ubuntu.com-20090324220652-c8dvom0nsqomp23d
Tags: 0.7.28-1
* New upstream version (ABI, API added)
* Put the -dbg package in section debug, as per recent archive changes
* Remove obsolete Conflicts/Replaces with libtelepathy-glib-static-dev, which
  was never in a stable release (and probably never in Debian at all)

Show diffs side-by-side

added added

removed removed

Lines of Context:
spec/Channel_Interface_Group.xml
1
1
<?xml version="1.0" ?>
2
2
<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
 
  <tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
4
 
  <tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
5
 
  <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
 
3
  <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
 
4
  <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
 
5
  <tp:copyright>Copyright © 2006 INdT</tp:copyright>
6
6
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
7
7
    <p>This library is free software; you can redistribute it and/or
8
8
modify it under the terms of the GNU Lesser General Public
24
24
    <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List">
25
25
      <tp:docstring>A structure representing a contact whose attempt to
26
26
        join a group is to be confirmed by the local user using
27
 
        AddMembers.</tp:docstring>
 
27
        <tp:member-ref>AddMembers</tp:member-ref>.</tp:docstring>
28
28
      <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added">
29
29
        <tp:docstring>
30
30
          The contact to be added to the group
48
48
      </tp:member>
49
49
    </tp:struct>
50
50
 
51
 
    <method name="AddMembers">
52
 
      <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
 
51
    <method name="AddMembers" tp:name-for-bindings="Add_Members">
 
52
      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
53
53
        <tp:docstring>
54
54
          An array of contact handles to invite to the channel
55
55
        </tp:docstring>
56
56
      </arg>
57
 
      <arg direction="in" name="message" type="s">
 
57
      <arg direction="in" name="Message" type="s">
58
58
        <tp:docstring>
59
59
          A string message, which can be blank if desired
60
60
        </tp:docstring>
65
65
 
66
66
        <p>A message may be provided along with the request, which will be sent
67
67
        to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
68
 
        CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this
 
68
        CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT
 
69
        <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
69
70
        message should be provided.</p>
70
71
 
71
72
        <p>Attempting to add contacts who are already members is allowed;
83
84
      </tp:possible-errors>
84
85
    </method>
85
86
 
86
 
    <method name="GetAllMembers">
 
87
    <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members">
87
88
      <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
88
89
        Properties D-Bus interface to get properties including Members,
89
90
        RemotePendingMembers and LocalPendingMembers instead, falling back to
90
 
        this method and GetLocalPendingMembers if necessary.</tp:deprecated>
 
91
        this method and GetLocalPendingMembersWithInfo if necessary.
 
92
      </tp:deprecated>
91
93
 
92
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]">
 
94
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
95
        name="Members">
93
96
        <tp:docstring>
94
97
          array of handles of current members
95
98
        </tp:docstring>
96
99
      </arg>
97
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]">
 
100
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
101
        name="Local_Pending">
98
102
        <tp:docstring>
99
103
          array of handles of local pending members
100
104
        </tp:docstring>
101
105
      </arg>
102
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]">
 
106
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
107
        name="Remote_Pending">
103
108
        <tp:docstring>
104
109
          array of handles of remote pending members
105
110
        </tp:docstring>
117
122
    <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u">
118
123
      <tp:flag suffix="Can_Add" value="1">
119
124
        <tp:docstring>
120
 
            The AddMembers method can be used to add or invite members who are
 
125
            The <tp:member-ref>AddMembers</tp:member-ref> method can be used to
 
126
            add or invite members who are
121
127
            not already in the local pending list (which is always valid).
122
128
        </tp:docstring>
123
129
      </tp:flag>
124
130
      <tp:flag suffix="Can_Remove" value="2">
125
131
        <tp:docstring>
126
 
            The RemoveMembers method can be used to remove channel members
 
132
            The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
 
133
            to remove channel members
127
134
            (removing those on the pending local list is always valid).
128
135
        </tp:docstring>
129
136
      </tp:flag>
130
137
      <tp:flag suffix="Can_Rescind" value="4">
131
138
        <tp:docstring>
132
 
            The RemoveMembers method can be used on people on the remote
 
139
            The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
 
140
            on people on the remote
133
141
            pending list.
134
142
        </tp:docstring>
135
143
      </tp:flag>
136
144
      <tp:flag suffix="Message_Add" value="8">
137
145
        <tp:docstring>
138
 
            A message may be sent to the server when calling AddMembers on
 
146
            A message may be sent to the server when calling
 
147
            <tp:member-ref>AddMembers</tp:member-ref> on
139
148
            contacts who are not currently pending members.
140
149
        </tp:docstring>
141
150
      </tp:flag>
142
151
      <tp:flag suffix="Message_Remove" value="16">
143
152
        <tp:docstring>
144
 
            A message may be sent to the server when calling RemoveMembers on
 
153
            A message may be sent to the server when calling
 
154
            <tp:member-ref>RemoveMembers</tp:member-ref> on
145
155
            contacts who are currently channel members.
146
156
        </tp:docstring>
147
157
      </tp:flag>
148
158
      <tp:flag suffix="Message_Accept" value="32">
149
159
        <tp:docstring>
150
 
            A message may be sent to the server when calling AddMembers on
 
160
            A message may be sent to the server when calling
 
161
            <tp:member-ref>AddMembers</tp:member-ref> on
151
162
            contacts who are locally pending.
152
163
        </tp:docstring>
153
164
      </tp:flag>
154
165
      <tp:flag suffix="Message_Reject" value="64">
155
166
        <tp:docstring>
156
 
            A message may be sent to the server when calling RemoveMembers on
 
167
            A message may be sent to the server when calling
 
168
            <tp:member-ref>RemoveMembers</tp:member-ref> on
157
169
            contacts who are locally pending.
158
170
        </tp:docstring>
159
171
      </tp:flag>
160
172
      <tp:flag suffix="Message_Rescind" value="128">
161
173
        <tp:docstring>
162
 
            A message may be sent to the server when calling RemoveMembers on
 
174
            A message may be sent to the server when calling
 
175
            <tp:member-ref>RemoveMembers</tp:member-ref> on
163
176
            contacts who are remote pending.
164
177
        </tp:docstring>
165
178
      </tp:flag>
169
182
            The members of this group have handles which are specific to
170
183
            this channel, and are not valid as general-purpose handles on
171
184
            the connection. Depending on the channel, it may be possible to
172
 
            call GetHandleOwners to find the owners of these handles, which
173
 
            should be done if you wish to eg subscribe to the contact's
174
 
            presence.
 
185
            check the <tp:member-ref>HandleOwners</tp:member-ref> property or
 
186
            call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the
 
187
            owners of these handles, which should be done if you wish to (e.g.)
 
188
            subscribe to the contact's presence.
175
189
          </p>
176
190
 
177
191
          <p>
192
206
      <tp:flag suffix="Handle_Owners_Not_Available" value="1024">
193
207
        <tp:docstring>
194
208
          In rooms with channel specific handles (ie Channel_Specific_Handles
195
 
          flag is set), this flag indicates that none of the handle owners are
196
 
          available, and that GetHandleOwners method will always return 0 for
197
 
          channel members other than the self handle.
 
209
          flag is set), this flag indicates that no handle owners are
 
210
          available, apart from the owner of the
 
211
          <tp:member-ref>SelfHandle</tp:member-ref>.
 
212
 
 
213
          <tp:rationale>
 
214
            This used to be an important optimization to avoid repeated
 
215
            GetHandleOwners calls, before we introduced the
 
216
            <tp:member-ref>HandleOwners</tp:member-ref> property and
 
217
            <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal.
 
218
          </tp:rationale>
198
219
        </tp:docstring>
199
220
      </tp:flag>
200
221
      <tp:flag suffix="Properties" value="2048">
203
224
          specification 0.17.6 are fully supported.
204
225
        </tp:docstring>
205
226
      </tp:flag>
 
227
      <tp:flag suffix="Members_Changed_Detailed" value="4096">
 
228
        <tp:docstring>
 
229
          Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref>
 
230
          will be emitted for changes to this group's members in addition to
 
231
          <tp:member-ref>MembersChanged</tp:member-ref>.
 
232
          Clients can then connect to the former and ignore emission of the
 
233
          latter. This flag's state MUST NOT change over the lifetime of a
 
234
          channel.
 
235
 
 
236
          <tp:rationale>
 
237
            If it were allowed to change, client bindings would have to always
 
238
            connect to MembersChanged just in case the flag ever went away (and
 
239
            generally be unnecessarily complicated), which would mostly negate
 
240
            the point of having this flag in the first place.
 
241
          </tp:rationale>
 
242
        </tp:docstring>
 
243
      </tp:flag>
 
244
      <tp:flag suffix="Message_Depart" value="8192">
 
245
        <tp:added version="0.17.21"/>
 
246
        <tp:docstring>
 
247
          A message may be sent to the server when calling
 
248
          <tp:member-ref>RemoveMembers</tp:member-ref> on
 
249
          the <tp:member-ref>SelfHandle</tp:member-ref>.
 
250
 
 
251
          <tp:rationale>
 
252
            This would be set for XMPP Multi-User Chat or IRC channels,
 
253
            but not for a typical implementation of streamed media calls.
 
254
          </tp:rationale>
 
255
        </tp:docstring>
 
256
      </tp:flag>
206
257
    </tp:flags>
207
258
 
208
259
    <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
209
 
      access="read">
 
260
      access="read" tp:name-for-bindings="Group_Flags">
210
261
      <tp:docstring>
211
262
        An integer representing the bitwise-OR of flags on this
212
263
        channel. The user interface can use this to present information about
213
264
        which operations are currently valid. Change notification is via
214
 
        the GroupFlagsChanged signal.
 
265
        the <tp:member-ref>GroupFlagsChanged</tp:member-ref> signal.
215
266
      </tp:docstring>
216
267
      <tp:added version="0.17.6">For backwards compatibility,
217
268
        clients should fall back to calling GetGroupFlags if
218
269
        Channel_Group_Flag_Properties is not present.</tp:added>
219
270
    </property>
220
271
 
221
 
    <method name="GetGroupFlags">
222
 
      <arg direction="out" type="u" tp:type="Channel_Group_Flags">
 
272
    <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags">
 
273
      <arg direction="out" type="u" tp:type="Channel_Group_Flags"
 
274
        name="Group_Flags">
223
275
        <tp:docstring>
224
276
          The value of the GroupFlags property
225
277
        </tp:docstring>
226
278
      </arg>
227
279
      <tp:docstring>
228
 
        Returns the value of the GroupFlags property.
 
280
        Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> property.
229
281
      </tp:docstring>
230
282
      <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
231
283
        Properties D-Bus interface to get properties including GroupFlags
259
311
    </tp:mapping>
260
312
 
261
313
    <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map"
262
 
      access="read">
 
314
      access="read" tp:name-for-bindings="Handle_Owners">
263
315
      <tp:docstring>
264
316
        A map from channel-specific handles to their owners, including
265
317
        at least all of the channel-specific handles in this channel's members,
267
319
        the keys of this mapping is not channel-specific in this channel.
268
320
        Handles which are channel-specific, but for which the owner is
269
321
        unknown, MUST appear in this mapping with 0 as owner. Change
270
 
        notification is via the HandleOwnersChanged signal.
 
322
        notification is via the
 
323
        <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal.
271
324
      </tp:docstring>
272
325
      <tp:added version="0.17.6"/>
273
326
    </property>
274
327
 
275
 
    <signal name="HandleOwnersChanged">
 
328
    <signal name="HandleOwnersChanged"
 
329
      tp:name-for-bindings="Handle_Owners_Changed">
276
330
      <tp:docstring>
277
 
        Emitted whenever the HandleOwners property changes.
 
331
        Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref>
 
332
        property changes.
278
333
      </tp:docstring>
279
334
      <tp:added version="0.17.6">This signal should not be relied on
280
335
        unless Channel_Group_Flag_Properties is present.</tp:added>
291
346
        <tp:docstring>
292
347
          The channel-specific handles that were removed from the keys of the
293
348
          HandleOwners property, as a result of the contact leaving this group
294
 
          in a previous MembersChanged signal
 
349
          in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal
295
350
        </tp:docstring>
296
351
      </arg>
297
352
    </signal>
298
353
 
299
 
    <method name="GetHandleOwners">
300
 
      <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
 
354
    <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners">
 
355
      <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
301
356
        <tp:docstring>
302
357
          A list of integer handles representing members of the channel
303
358
        </tp:docstring>
304
359
      </arg>
305
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]">
 
360
      <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners">
306
361
        <tp:docstring>
307
362
          An array of integer handles representing the owner handles of
308
363
          the given room members, in the same order, or 0 if the
339
394
      </tp:possible-errors>
340
395
    </method>
341
396
 
342
 
    <method name="GetLocalPendingMembers">
343
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
 
397
    <method name="GetLocalPendingMembers"
 
398
      tp:name-for-bindings="Get_Local_Pending_Members">
 
399
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
400
        name="Handles"/>
344
401
      <tp:docstring>
345
402
        Returns the To_Be_Added handle (only) for each structure in the
346
 
        LocalPendingMembers property.
 
403
        <tp:member-ref>LocalPendingMembers</tp:member-ref> property.
347
404
      </tp:docstring>
348
405
      <tp:deprecated version="0.17.6">Use the LocalPendingMembers
349
406
        property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
353
410
      </tp:possible-errors>
354
411
    </method>
355
412
 
356
 
    <method name="GetLocalPendingMembersWithInfo">
 
413
    <method name="GetLocalPendingMembersWithInfo"
 
414
      tp:name-for-bindings="Get_Local_Pending_Members_With_Info">
357
415
      <tp:added version="0.15.0" />
358
416
      <tp:docstring>
359
 
        Returns the LocalPendingMembers property.
 
417
        Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> property.
360
418
      </tp:docstring>
361
419
      <tp:deprecated version="0.17.6">Use the LocalPendingMembers
362
420
        property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
363
 
      <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]">
 
421
      <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]"
 
422
        name="Info">
364
423
        <tp:docstring>
365
424
          An array of structs containing:
366
425
          <ul>
373
432
            </li>
374
433
            <li>
375
434
              The reason for the request: one of the values of
376
 
              ChannelGroupChangeReason
 
435
              <tp:type>Channel_Group_Change_Reason</tp:type>
377
436
            </li>
378
437
            <li>
379
438
              A string message containing the reason for the request if any (or
389
448
    </method>
390
449
 
391
450
    <property name="LocalPendingMembers" access="read"
392
 
      type="a(uuus)" tp:type="Local_Pending_Info[]">
 
451
      type="a(uuus)" tp:type="Local_Pending_Info[]"
 
452
      tp:name-for-bindings="Local_Pending_Members">
393
453
      <tp:docstring>
394
454
        An array of structs containing handles representing contacts
395
455
        requesting channel membership and awaiting local approval with
396
 
        AddMembers.
 
456
        <tp:member-ref>AddMembers</tp:member-ref>.
397
457
      </tp:docstring>
398
458
      <tp:added version="0.17.6">If Channel_Group_Flag_Properties is
399
459
        not present, clients should fall back to using the
401
461
        from that to the deprecated GetAllMembers method.</tp:added>
402
462
    </property>
403
463
 
404
 
    <property name="Members" access="read" type="au" tp:type="Contact_Handle[]">
 
464
    <property name="Members" tp:name-for-bindings="Members"
 
465
      access="read" type="au" tp:type="Contact_Handle[]">
405
466
      <tp:docstring>
406
467
        The members of this channel.
407
468
      </tp:docstring>
409
470
        is not set, fall back to calling GetAllMembers.</tp:added>
410
471
    </property>
411
472
 
412
 
    <method name="GetMembers">
413
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
 
473
    <method name="GetMembers" tp:name-for-bindings="Get_Members">
 
474
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
475
        name="Handles"/>
414
476
      <tp:docstring>
415
 
        Returns the Members property.
 
477
        Returns the <tp:member-ref>Members</tp:member-ref> property.
416
478
      </tp:docstring>
417
479
      <tp:deprecated version="0.17.6">Use the Members
418
480
        property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
423
485
    </method>
424
486
 
425
487
    <property name="RemotePendingMembers" access="read" type="au"
426
 
      tp:type="Contact_Handle[]">
 
488
      tp:type="Contact_Handle[]" tp:name-for-bindings="Remote_Pending_Members">
427
489
      <tp:docstring>
428
490
        An array of handles representing contacts who have been
429
491
        invited to the channel and are awaiting remote approval.
432
494
        is not set, fall back to calling GetAllMembers.</tp:added>
433
495
    </property>
434
496
 
435
 
    <method name="GetRemotePendingMembers">
436
 
      <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
 
497
    <method name="GetRemotePendingMembers"
 
498
      tp:name-for-bindings="Get_Remote_Pending_Members">
 
499
      <arg direction="out" type="au" tp:type="Contact_Handle[]"
 
500
        name="Handles"/>
437
501
      <tp:docstring>
438
502
        Returns an array of handles representing contacts who have been
439
503
        invited to the channel and are awaiting remote approval.
440
504
      </tp:docstring>
441
 
      <tp:deprecated version="0.17.6">Use the RemotePendingMembers
 
505
      <tp:deprecated version="0.17.6">Use the
 
506
        <tp:member-ref>RemotePendingMembers</tp:member-ref>
442
507
        property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
443
508
      <tp:possible-errors>
444
509
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
446
511
      </tp:possible-errors>
447
512
    </method>
448
513
 
449
 
    <signal name="SelfHandleChanged">
 
514
    <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed">
450
515
      <tp:docstring>
451
 
        Emitted whenever the SelfHandle property changes.
 
516
        Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
 
517
        changes.
452
518
      </tp:docstring>
453
519
      <tp:added version="0.17.6">This signal should not be relied on
454
520
        unless Channel_Group_Flag_Properties is present.</tp:added>
461
527
    </signal>
462
528
 
463
529
    <property name="SelfHandle" type="u" tp:type="Contact_Handle"
464
 
      access="read">
 
530
      access="read" tp:name-for-bindings="Self_Handle">
465
531
      <tp:docstring>
466
532
        The handle for the user on this channel (which can also be a
467
533
        local or remote pending member), or 0 if the user is not a member at
468
 
        all (which is likely to be the case, for instance, on ContactList
469
 
        channels). Note that this is different from the connection
470
 
        GetSelfHandle on some protocols, so the value of this handle should
 
534
        all (which is likely to be the case, for instance, on <tp:dbus-ref
 
535
        namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>
 
536
        channels). Note that this is different from the result of
 
537
        <tp:dbus-ref
 
538
        namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>
 
539
        on some protocols, so the value of this handle should
471
540
        always be used with the methods of this interface.
472
541
      </tp:docstring>
473
542
      <tp:added version="0.17.6">For backwards compatibility,
475
544
        Channel_Group_Flag_Properties is not present.</tp:added>
476
545
    </property>
477
546
 
478
 
    <method name="GetSelfHandle">
479
 
      <arg direction="out" type="u" tp:type="Contact_Handle"/>
 
547
    <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
 
548
      <arg direction="out" type="u" tp:type="Contact_Handle"
 
549
        name="Self_Handle"/>
480
550
      <tp:docstring>
481
 
        Returns the value of the SelfHandle property.
 
551
        Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref>
 
552
        property.
482
553
      </tp:docstring>
483
554
      <tp:deprecated version="0.17.6">Clients should retrieve the
484
555
        SelfHandle property using GetAll instead,
489
560
      </tp:possible-errors>
490
561
    </method>
491
562
 
492
 
    <signal name="GroupFlagsChanged">
493
 
      <arg name="added" type="u" tp:type="Channel_Group_Flags">
 
563
    <signal name="GroupFlagsChanged" tp:name-for-bindings="Group_Flags_Changed">
 
564
      <arg name="Added" type="u" tp:type="Channel_Group_Flags">
494
565
        <tp:docstring>
495
566
          A bitwise OR of the flags which have been set
496
567
        </tp:docstring>
497
568
      </arg>
498
 
      <arg name="removed" type="u" tp:type="Channel_Group_Flags">
 
569
      <arg name="Removed" type="u" tp:type="Channel_Group_Flags">
499
570
        <tp:docstring>
500
571
          A bitwise OR of the flags which have been cleared
501
572
        </tp:docstring>
502
573
      </arg>
503
574
      <tp:docstring>
504
 
        Emitted when the flags as returned by GetGroupFlags are changed.
 
575
        Emitted when the flags as returned by
 
576
        <tp:member-ref>GetGroupFlags</tp:member-ref> are changed.
505
577
        The user interface should be updated as appropriate.
506
578
      </tp:docstring>
507
579
    </signal>
513
585
        </tp:docstring>
514
586
      </tp:enumvalue>
515
587
      <tp:enumvalue suffix="Offline" value="1">
516
 
        <tp:docstring>
517
 
            The change is due to a user going offline. Also used when
518
 
            user is already offline, but this wasn't known previously.
 
588
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
589
          <p>The change is due to a user going offline. Also used when
 
590
            user is already offline, but this wasn't known previously.</p>
 
591
 
 
592
          <p>If a one-to-one <tp:dbus-ref
 
593
              namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
 
594
            call fails because the contact being called is offline, the
 
595
            connection manager SHOULD indicate this by removing both the
 
596
            <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
 
597
            handle from the Group interface with reason Offline.</p>
 
598
 
 
599
          <tp:rationale>
 
600
            For 1-1 calls, the call terminates as a result of removing the
 
601
            remote contact, so the SelfHandle should be removed at the same
 
602
            time as the remote contact and for the same reason.
 
603
          </tp:rationale>
 
604
 
 
605
          <p>If a handle is removed from a group for this reason, the
 
606
            equivalent D-Bus error is
 
607
            <code>org.freedesktop.Telepathy.Error.Offline</code>.</p>
519
608
        </tp:docstring>
520
609
      </tp:enumvalue>
521
610
      <tp:enumvalue suffix="Kicked" value="2">
522
 
        <tp:docstring>
523
 
            The change is due to a kick operation.
 
611
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
612
          <p>The change is due to a kick operation.</p>
 
613
 
 
614
          <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
 
615
            from a group for this reason, the equivalent D-Bus error is
 
616
            <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>.
 
617
          </p>
524
618
        </tp:docstring>
525
619
      </tp:enumvalue>
526
620
      <tp:enumvalue suffix="Busy" value="3">
527
 
        <tp:docstring>
528
 
            The change is due to a busy indication.
 
621
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
622
          <p>The change is due to a busy indication.</p>
 
623
 
 
624
          <p>If a one-to-one <tp:dbus-ref
 
625
              namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
 
626
            call fails because the contact being called is busy, the
 
627
            connection manager SHOULD indicate this by removing both the
 
628
            <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
 
629
            handle from the Group interface with reason Busy.</p>
 
630
 
 
631
          <tp:rationale>
 
632
            For 1-1 calls, the call terminates as a result of removing the
 
633
            remote contact, so the SelfHandle should be removed at the same
 
634
            time as the remote contact and for the same reason.
 
635
          </tp:rationale>
 
636
 
 
637
          <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
 
638
            from a group for this reason, the equivalent D-Bus error is
 
639
            <code>org.freedesktop.Telepathy.Error.Busy</code>.
 
640
          </p>
529
641
        </tp:docstring>
530
642
      </tp:enumvalue>
531
643
      <tp:enumvalue suffix="Invited" value="4">
532
644
        <tp:docstring>
533
 
            The change is due to an invitation.
 
645
          The change is due to an invitation. This reason SHOULD only be used
 
646
          when contacts are added to the remote-pending set (to indicate that
 
647
          the contact has been invited) or to the members (to indicate that
 
648
          the contact has accepted the invitation).
 
649
 
 
650
          <tp:rationale>
 
651
            Otherwise, what would it mean?
 
652
          </tp:rationale>
534
653
        </tp:docstring>
535
654
      </tp:enumvalue>
536
655
      <tp:enumvalue suffix="Banned" value="5">
537
 
        <tp:docstring>
538
 
            The change is due to a kick+ban operation.
 
656
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
657
          <p>The change is due to a kick+ban operation.</p>
 
658
 
 
659
          <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
 
660
            from a group for this reason, the equivalent D-Bus error is
 
661
            <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>.
 
662
          </p>
539
663
        </tp:docstring>
540
664
      </tp:enumvalue>
541
665
      <tp:enumvalue suffix="Error" value="6">
544
668
        </tp:docstring>
545
669
      </tp:enumvalue>
546
670
      <tp:enumvalue suffix="Invalid_Contact" value="7">
547
 
        <tp:docstring>
548
 
            The change is because the requested contact does not exist.
 
671
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
672
          <p>The change is because the requested contact does not exist.</p>
 
673
 
 
674
          <p>For instance, if the user invites a nonexistent contact to a
 
675
            chatroom or attempts to call a nonexistent contact, this could
 
676
            be indicated by the CM adding that contact's handle to
 
677
            remote-pending for reason None or Invited, then removing it for
 
678
            reason Invalid_Contact. In the case of a 1-1 StreamedMedia
 
679
            call, the CM SHOULD remove the self handle from the Group
 
680
            in the same signal.</p>
 
681
 
 
682
          <tp:rationale>
 
683
            For 1-1 calls, the call terminates as a result of removing the
 
684
            remote contact, so the SelfHandle should be removed at the same
 
685
            time as the remote contact and for the same reason.
 
686
          </tp:rationale>
 
687
 
 
688
          <p>If a contact is removed from a group for this reason, the
 
689
            equivalent D-Bus error is
 
690
            <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>.
 
691
          </p>
549
692
        </tp:docstring>
550
693
      </tp:enumvalue>
551
694
      <tp:enumvalue suffix="No_Answer" value="8">
552
 
        <tp:docstring>
553
 
            The change is because the requested contact did not respond.
 
695
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
696
          <p>The change is because the requested contact did not respond.</p>
 
697
 
 
698
          <p>If a one-to-one <tp:dbus-ref
 
699
              namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
 
700
            call fails because the contact being called did not respond, the
 
701
            connection manager SHOULD indicate this by removing both the
 
702
            <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
 
703
            handle from the Group interface with reason No_Answer.</p>
 
704
 
 
705
          <tp:rationale>
 
706
            Documenting existing practice.
 
707
          </tp:rationale>
 
708
 
 
709
          <p>If a contact is removed from a group for this reason, the
 
710
            equivalent D-Bus error is
 
711
            <code>org.freedesktop.Telepathy.Error.NoAnswer</code>.
 
712
          </p>
554
713
        </tp:docstring>
555
714
      </tp:enumvalue>
556
715
      <tp:enumvalue suffix="Renamed" value="9">
557
 
        <tp:docstring>
558
 
          The change is because a contact's unique identifier changed.
 
716
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
717
          <p>The change is because a contact's unique identifier changed.
559
718
          There must be exactly one handle in the removed set and exactly
560
 
          one handle in one of the added sets. The Renamed signal on the
561
 
          Renaming interface will have been emitted for the same handles,
562
 
          shortly before this MembersChanged signal is emitted.
 
719
          one handle in one of the added sets. The <tp:dbus-ref
 
720
            namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref>
 
721
          signal on the
 
722
          <tp:dbus-ref
 
723
            namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref>
 
724
          interface will have been emitted for the same handles,
 
725
          shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p>
563
726
        </tp:docstring>
564
727
      </tp:enumvalue>
565
728
      <tp:enumvalue suffix="Permission_Denied" value="10">
566
 
        <tp:docstring>
567
 
            The change is because there was no permission to contact the
568
 
            requested handle.
 
729
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
730
          <p>The change is because there was no permission to contact the
 
731
            requested handle.</p>
 
732
 
 
733
          <p>If a contact is removed from a group for this reason, the
 
734
            equivalent D-Bus error is
 
735
            <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>.
 
736
          </p>
569
737
        </tp:docstring>
570
738
      </tp:enumvalue>
571
739
      <tp:enumvalue suffix="Separated" value="11">
578
746
          <p>
579
747
            If members are added with this reason code, the change is because
580
748
            unconnected parts of the group have rejoined. If this channel
581
 
            carries messages (e.g. Text or Tubes channels) applications must
 
749
            carries messages (e.g. <tp:dbus-ref
 
750
              namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
 
751
            or <tp:dbus-ref
 
752
              namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref>
 
753
            channels) applications must
582
754
            assume that the contacts being added are likely to have missed some
583
755
            messages as a result of the separation, and that the contacts
584
756
            in the group are likely to have missed some messages from the
590
762
            the group with reason Separated. Application protocols in Tubes
591
763
            should be prepared to cope with this situation.
592
764
          </p>
 
765
 
 
766
          <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be
 
767
            removed from channels with this reason.</p>
593
768
        </tp:docstring>
594
769
      </tp:enumvalue>
595
770
    </tp:enum>
596
771
 
597
 
    <signal name="MembersChanged">
598
 
      <arg name="message" type="s">
 
772
    <signal name="MembersChanged" tp:name-for-bindings="Members_Changed">
 
773
      <arg name="Message" type="s">
599
774
        <tp:docstring>
600
775
          A string message from the server, or blank if not
601
776
        </tp:docstring>
602
777
      </arg>
603
 
      <arg name="added" type="au" tp:type="Contact_Handle[]">
 
778
      <arg name="Added" type="au" tp:type="Contact_Handle[]">
604
779
        <tp:docstring>
605
780
          A list of members added to the channel
606
781
        </tp:docstring>
607
782
      </arg>
608
 
      <arg name="removed" type="au" tp:type="Contact_Handle[]">
 
783
      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
609
784
        <tp:docstring>
610
785
          A list of members removed from the channel
611
786
        </tp:docstring>
612
787
      </arg>
613
 
      <arg name="local_pending" type="au" tp:type="Contact_Handle[]">
 
788
      <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
614
789
        <tp:docstring>
615
790
          A list of members who are pending local approval
616
791
        </tp:docstring>
617
792
      </arg>
618
 
      <arg name="remote_pending" type="au" tp:type="Contact_Handle[]">
 
793
      <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
619
794
        <tp:docstring>
620
795
          A list of members who are pending remote approval
621
796
        </tp:docstring>
622
797
      </arg>
623
 
      <arg name="actor" type="u" tp:type="Contact_Handle">
 
798
      <arg name="Actor" type="u" tp:type="Contact_Handle">
624
799
        <tp:docstring>
625
800
          The contact handle of the person who made the change, or 0
626
801
          if not known
627
802
        </tp:docstring>
628
803
      </arg>
629
 
      <arg name="reason" type="u" tp:type="Channel_Group_Change_Reason">
 
804
      <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason">
630
805
        <tp:docstring>
631
 
          A reason for the change: one of the values of
632
 
          ChannelGroupChangeReason
 
806
          A reason for the change
633
807
        </tp:docstring>
634
808
      </arg>
635
809
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
639
813
          which may be displayed to the user if desired.</p>
640
814
 
641
815
        <p>All channel-specific handles that are mentioned in this signal
642
 
          MUST be represented in the value of the HandleOwners property.
643
 
          In practice, this will mean that HandleOwnersChanged is
 
816
          MUST be represented in the value of the
 
817
          <tp:member-ref>HandleOwners</tp:member-ref> property.
 
818
          In practice, this will mean that
 
819
          <tp:member-ref>HandleOwnersChanged</tp:member-ref> is
644
820
          emitted <em>before</em> emitting a MembersChanged signal in which
645
821
          channel-specific handles are added, but that it is emitted
646
822
          <em>after</em> emitting a MembersChanged signal in which
648
824
      </tp:docstring>
649
825
    </signal>
650
826
 
651
 
    <method name="RemoveMembers">
652
 
      <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
653
 
        <tp:docstring>
654
 
          An array of contact handles to remove from the channel
655
 
        </tp:docstring>
656
 
      </arg>
657
 
      <arg direction="in" name="message" type="s">
658
 
        <tp:docstring>
659
 
          A string message, which can be blank if desired
660
 
        </tp:docstring>
661
 
      </arg>
 
827
    <tp:mapping name="Handle_Identifier_Map">
662
828
      <tp:docstring>
663
 
        Requests the removal of contacts from a channel, reject their request
664
 
        for channel membership on the pending local list, or rescind their
665
 
        invitation on the pending remote list. A message may be provided along
666
 
        with the request, which will be sent to the server if supported. See
667
 
        the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE,
668
 
        CHANNEL_GROUP_FLAG_MESSAGE_REJECT and
669
 
        CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this
670
 
        message should be provided.
 
829
        A map from handles to the corresponding normalized string identifier.
 
830
      </tp:docstring>
 
831
      <tp:added version="0.17.17"/>
 
832
 
 
833
      <tp:member type="u" name="Handle" tp:type="Contact_Handle">
 
834
        <tp:docstring>
 
835
          A nonzero handle
 
836
        </tp:docstring>
 
837
      </tp:member>
 
838
      <tp:member type="s" name="Identifier">
 
839
        <tp:docstring>
 
840
          The same string that would be returned by <tp:dbus-ref
 
841
            namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
 
842
          for this handle.
 
843
        </tp:docstring>
 
844
      </tp:member>
 
845
    </tp:mapping>
 
846
 
 
847
    <signal name="MembersChangedDetailed"
 
848
      tp:name-for-bindings="Members_Changed_Detailed">
 
849
      <arg name="Added" type="au" tp:type="Contact_Handle[]">
 
850
        <tp:docstring>
 
851
          A list of members added to the channel
 
852
        </tp:docstring>
 
853
      </arg>
 
854
      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
 
855
        <tp:docstring>
 
856
          A list of members removed from the channel
 
857
        </tp:docstring>
 
858
      </arg>
 
859
      <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
 
860
        <tp:docstring>
 
861
          A list of members who are pending local approval
 
862
        </tp:docstring>
 
863
      </arg>
 
864
      <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
 
865
        <tp:docstring>
 
866
          A list of members who are pending remote approval
 
867
        </tp:docstring>
 
868
      </arg>
 
869
      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
 
870
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
871
          <p>Information about the change, which may include the following
 
872
            well-known keys:</p>
 
873
 
 
874
          <dl>
 
875
            <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt>
 
876
            <dd>The contact handle of the person who made the change; 0 or
 
877
              omitted if unknown or not applicable.</dd>
 
878
 
 
879
            <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt>
 
880
            <dd>A reason for the change.</dd>
 
881
 
 
882
            <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt>
 
883
            <dd>
 
884
              <p>The string identifiers for handles mentioned in this signal, to
 
885
              give clients the minimal information necessary to react to the
 
886
              event without waiting for round-trips.  Connection managers
 
887
              SHOULD include the identifiers for members added to the group and
 
888
              for the actor (if any); they MAY omit the identifiers for handles
 
889
              which have been removed from the group.</p>
 
890
 
 
891
              <tp:rationale>
 
892
                <p>On IRC, an event such as a netsplit could cause the vast
 
893
                majority of a channel to leave.  Given that clients should
 
894
                already know the identifiers of a channel's members, including
 
895
                potentially hundreds of strings in the netsplit signal is
 
896
                unnecessary.</p>
 
897
              </tp:rationale>
 
898
 
 
899
              <p>Clients MUST NOT assume that the presence or absence of a
 
900
                handle in this mapping is meaningful. This mapping is merely
 
901
                an optimization for round-trip reduction, and connection
 
902
                managers MAY add additional handles, omit some handles, or
 
903
                omit the mapping completely.</p>
 
904
            </dd>
 
905
 
 
906
            <dt>message (s)</dt>
 
907
            <dd>A string message from the server regarding the change</dd>
 
908
 
 
909
            <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt>
 
910
            <dd>A (possibly implementation-specific) DBus error describing the
 
911
              change, providing more specific information than the
 
912
              <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This
 
913
              MUST only be present if it is strictly more informative than
 
914
              'change-reason'; if present, 'change-reason' MUST be set to the
 
915
              closest available reason.
 
916
 
 
917
              <tp:rationale>
 
918
                A SIP connection manager might want to signal "402 Payment
 
919
                required" as something more specific than Error or
 
920
                Permission_Denied so that a SIP-aware UI could handle it
 
921
                specially; including a namespaced error permits this to be done
 
922
                without <tp:type>Channel_Group_Change_Reason</tp:type> being
 
923
                extended to encompass every error any CM ever wants to report.
 
924
              </tp:rationale>
 
925
            </dd>
 
926
 
 
927
            <dt>debug-message (s)</dt>
 
928
            <dd>Debugging information on the change. SHOULD NOT be shown to
 
929
              users in normal circumstances.</dd>
 
930
          </dl>
 
931
        </tp:docstring>
 
932
      </arg>
 
933
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
934
        <p>Emitted when contacts join any of the three lists (members, local
 
935
          pending or remote pending) or when they leave any of the three
 
936
          lists. This signal provides a superset of the information provided by
 
937
          <tp:member-ref>MembersChanged</tp:member-ref>;
 
938
          if the channel's <tp:member-ref>GroupFlags</tp:member-ref>
 
939
          contains Members_Changed_Detailed, then clients may listen exclusively
 
940
          to this signal in preference to that signal.</p>
 
941
 
 
942
        <p>All channel-specific handles that are mentioned in this signal
 
943
          MUST be represented in the value of the
 
944
          <tp:member-ref>HandleOwners</tp:member-ref> property.  In practice,
 
945
          this will mean that
 
946
          <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted
 
947
          <em>before</em> emitting a MembersChangedDetailed signal in which
 
948
          channel-specific handles are added, but that it is emitted
 
949
          <em>after</em> emitting a MembersChangedDetailed signal in which
 
950
          channel-specific handles are removed.</p>
 
951
      </tp:docstring>
 
952
      <tp:added version="0.17.16"/>
 
953
    </signal>
 
954
 
 
955
    <method name="RemoveMembers" tp:name-for-bindings="Remove_Members">
 
956
      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
 
957
        <tp:docstring>
 
958
          An array of contact handles to remove from the channel
 
959
        </tp:docstring>
 
960
      </arg>
 
961
      <arg direction="in" name="Message" type="s">
 
962
        <tp:docstring>
 
963
          A string message, which can be blank if desired
 
964
        </tp:docstring>
 
965
      </arg>
 
966
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 
967
        <p>Requests the removal of contacts from a channel, reject their
 
968
          request for channel membership on the pending local list, or
 
969
          rescind their invitation on the pending remote list.</p>
 
970
 
 
971
        <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group,
 
972
          it can be removed via this method, in order to leave the group
 
973
          gracefully. This is the recommended way to leave a chatroom, close
 
974
          or reject a <tp:dbus-ref
 
975
            namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
 
976
          call, and so on.</p>
 
977
 
 
978
        <p>Accordingly, connection managers SHOULD support
 
979
          doing this, regardless of the value of
 
980
          <tp:member-ref>GroupFlags</tp:member-ref>.
 
981
          If doing so fails with PermissionDenied, this is considered to a bug
 
982
          in the connection manager, but clients MUST recover by falling back
 
983
          to closing the channel with the <tp:dbus-ref
 
984
            namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
 
985
          method.</p>
 
986
 
 
987
        <p>Removing any contact from the local pending list is always
 
988
          allowed. Removing contacts other than the
 
989
          <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members
 
990
          is allowed if and only if Channel_Group_Flag_Can_Remove is in the
 
991
          <tp:member-ref>GroupFlags</tp:member-ref>,
 
992
          while removing contacts other than the
 
993
          <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list
 
994
          is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
 
995
          <tp:member-ref>GroupFlags</tp:member-ref>.</p>
 
996
 
 
997
        <p>A message may be provided along with the request, which will be
 
998
          sent to the server if supported. See the
 
999
          Channel_Group_Flag_Message_Remove,
 
1000
          Channel_Group_Flag_Message_Depart,
 
1001
          Channel_Group_Flag_Message_Reject and
 
1002
          Channel_Group_Flag_Message_Rescind
 
1003
          <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
 
1004
          message should be provided.</p>
671
1005
      </tp:docstring>
672
1006
      <tp:possible-errors>
673
1007
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
678
1012
      </tp:possible-errors>
679
1013
    </method>
680
1014
 
681
 
    <method name="RemoveMembersWithReason">
682
 
      <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
 
1015
    <method name="RemoveMembersWithReason"
 
1016
      tp:name-for-bindings="Remove_Members_With_Reason">
 
1017
      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
683
1018
        <tp:docstring>
684
1019
          An array of contact handles to remove from the channel
685
1020
        </tp:docstring>
686
1021
      </arg>
687
 
      <arg direction="in" name="message" type="s">
 
1022
      <arg direction="in" name="Message" type="s">
688
1023
        <tp:docstring>
689
1024
          A string message, which can be blank if desired
690
1025
        </tp:docstring>
691
1026
      </arg>
692
 
      <arg direction="in" name="reason" type="u"
 
1027
      <arg direction="in" name="Reason" type="u"
693
1028
           tp:type="Channel_Group_Change_Reason">
694
1029
        <tp:docstring>
695
 
          A reason for the change: one of the values of
696
 
          ChannelGroupChangeReason
 
1030
          A reason for the change
697
1031
        </tp:docstring>
698
1032
      </arg>
699
1033
      <tp:docstring>
700
 
        As RemoveMembers, but a reason code may be provided where
 
1034
        As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may
 
1035
        be provided where
701
1036
        appropriate. The reason code may be ignored if the underlying
702
1037
        protocol is unable to represent the given reason.
703
1038
      </tp:docstring>
721
1056
    cannot be presumed by the channel's existence (for example, a channel you
722
1057
    may request membership of but your request may not be granted).</p>
723
1058
 
724
 
  <p>This interface implements three lists: a list of current members, and two
725
 
    lists of local pending and remote pending members. Contacts on the remote
 
1059
  <p>This interface implements three lists: a list of current members
 
1060
    (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending
 
1061
    and remote pending members
 
1062
    (<tp:member-ref>LocalPendingMembers</tp:member-ref> and
 
1063
    <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively).
 
1064
    Contacts on the remote
726
1065
    pending list have been invited to the channel, but the remote user has not
727
1066
    accepted the invitation. Contacts on the local pending list have requested
728
1067
    membership of the channel, but the local user of the framework must accept
729
1068
    their request before they may join. A single contact should never appear on
730
1069
    more than one of the three lists. The lists are empty when the channel is
731
 
    created, and the MembersChanged signal should be emitted when information
 
1070
    created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal
 
1071
    (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains
 
1072
    Members_Changed_Detailed, the
 
1073
    <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal)
 
1074
    should be emitted when information
732
1075
    is retrieved from the server, or changes occur.</p>
733
1076
 
734
 
  <p>Addition of members to the channel may be requested by using AddMembers. If
 
1077
  <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or
 
1078
    <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates
 
1079
    that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from
 
1080
    the channel, and the channel subsequently emits <tp:dbus-ref
 
1081
      namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>,
 
1082
    clients SHOULD consider the details given in the MembersChanged or
 
1083
    MembersChangedDetailed signal to be the reason why the channel closed.</p>
 
1084
 
 
1085
  <p>Addition of members to the channel may be requested by using
 
1086
    <tp:member-ref>AddMembers</tp:member-ref>. If
735
1087
    remote acknowledgement is required, use of the AddMembers method will cause
736
1088
    users to appear on the remote pending list. If no acknowledgement is
737
1089
    required, AddMembers will add contacts to the member list directly.  If a
739
1091
    will grant their membership request.</p>
740
1092
 
741
1093
  <p>Removal of contacts from the channel may be requested by using
742
 
    RemoveMembers.  If a contact is awaiting authorisation on the local pending
 
1094
    <tp:member-ref>RemoveMembers</tp:member-ref>.  If a contact is awaiting
 
1095
    authorisation on the local pending
743
1096
    list, RemoveMembers will refuse their membership request. If a contact is
744
1097
    on the remote pending list but has not yet accepted the invitation,
745
1098
    RemoveMembers will rescind the request if possible.</p>