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
|
<?xml version="1.0" ?>
<node name="/Channel_Interface_Room"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
<tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>
<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.</p>
<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.</p>
</tp:license>
<interface name="org.freedesktop.Telepathy.Channel.Interface.Room2">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:added version="0.24.0">(version 2)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Different IM protocols use a variety of ways to name chat rooms. The
simplest example is perhaps IRC, where chat rooms have short,
persistent, human-readable string names, and are generally global
across the network. Skype chat rooms have persistent string names, so
you can leave and re-join a room, but these names are opaque unique
identifiers. MSN chat rooms are unnamed, and you can only join one by
being invited. And XMPP wins the coveted “most complicated chat rooms”
prize: chat rooms may be hosted by different servers with different DNS
names; normally they have human-readable names, except that all MUCs on
Google Talk's conference server have UUIDs as names, and <a
href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym
title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4
<q>Requesting a Unique Room Name</q></a> defines a protocol for
requesting a unique, opaque room name on the server. Note that
this interface is not restricted to Text channels, and can
also be used on Call channels.</p>
<p>This interface intends to support and differentiate these mechanisms
more clearly than the <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
and <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
properties can alone. It initially contains a pair of properties used
to represent the human-readable parts of a
<tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples
for different protocols are represented as follows:</p>
<ul>
<li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a
channel with properties
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>Room</code>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
= <code>"#telepathy"</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>"#telepathy"</code>,
<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
that the room has a human-readable identifier, and is not confined to
a particular server on the network.
<tp:rationale>
Actually, IRC supports creating “local” channels specific to the
server they are created on. These channels have identifiers
starting with <tt>&</tt> rather than <tt>#</tt>. These could be
represented by setting <tp:member-ref>Server</tp:member-ref>
appropriately.
</tp:rationale>
</li>
<li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>Room</code>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
= <code>"0xdeadbeef"</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
that the room has an identifier but no human-readable name.
</li>
<li>An MSN group chat has
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>None</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
that the room has neither an identifier (so it cannot be re-joined
later) nor a human-readable name.
</li>
<li>A standard Jabber multi-user chat
<tt>jdev@conference.jabber.org</tt> has
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>Room</code>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
= <code>"jdev@conference.jabber.org"</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>"jdev"</code>,
<tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>.
</li>
<li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>Room</code>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
= <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
<tp:member-ref>Server</tp:member-ref> =
<code>"groupchat.google.com"</code>, indicating that the room has a
persistent identifier, no human-readable name, and is hosted by a
particular server.
</li>
<li>Similarly, a XEP-0045 §10.1.4 uniquely-named room
<tt>lrcgsnthzvwm@conference.jabber.org</tt> has
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= <code>Room</code>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
= <code>"lrcgsnthzvwm@conference.jabber.org"</code>,
<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
<tp:member-ref>Server</tp:member-ref> =
<code>"conference.jabber.org"</code>, indicating that the room has a
persistent identifier, no human-readable name, and is hosted by a
particular server.
</li>
</ul>
<h4>Requestable channel classes</h4>
<p>If the connection supports joining text chat rooms by unique
identifier, like Skype, it should advertise a
<tp:type>Requestable_Channel_Class</tp:type> matching:</p>
<blockquote>
<pre>
( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
>Text</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandleType</tp:dbus-ref>: Room,
},
Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetID</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandle</tp:dbus-ref>,
]
)</pre></blockquote>
<p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandle</tp:dbus-ref>.</p>
<p>If, like IRC, the room identifiers are also human-readable, the
RCCs should also include RoomName in <var>Allowed_Properties</var>:</p>
<blockquote>
<pre>
( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
>Text</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandleType</tp:dbus-ref>: Room,
},
Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetID</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandle</tp:dbus-ref>,
...<tp:member-ref>RoomName</tp:member-ref>
]
),
( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
>Text</tp:dbus-ref>
},
Allowed = [ ...<tp:member-ref>RoomName</tp:member-ref>,
]
)</pre></blockquote>
<p>Requests may specify the RoomName in place of
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
. Note how <tp:member-ref>RoomName</tp:member-ref> appears
in <var>Allowed_Properties</var> of a different RCC because
when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandleType</tp:dbus-ref> is omitted (or is None), both
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandle</tp:dbus-ref> and
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetID</tp:dbus-ref> must also be omitted.
<tp:member-ref>RoomName</tp:member-ref> is allowed in conjuction
with
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
in some situations, as explained below in the <em>Requesting room
channels</em> section.
</p>
<p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref>
should also be included in the allowed properties, but
CMs MUST use a reasonable default
<tp:member-ref>Server</tp:member-ref> if not explicitly
specified in a channel request. The CM's default server MAY
be configurable by a connection parameter specified on a
<tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
>RequestConnection</tp:dbus-ref> call, similarly to how the
fallback conference server is specified on jabber connections in
gabble.</p>
<p>If the protocol supports unnamed rooms, <tp:member-ref>RoomName</tp:member-ref>
should be fixed to the empty string, and
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
should be None:</p>
<blockquote>
<pre>
( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
>Text</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
>TargetHandleType</tp:dbus-ref>: None,
...<tp:member-ref>RoomName</tp:member-ref>: "",
},
Allowed = [ ]
)</pre></blockquote>
<h4>Requesting room channels</h4>
<p>When explicitly joining a room, the CM cannot know whether the room
ID is unique or not. As a result, if this is the case, adding an
empty string <tp:member-ref>RoomName</tp:member-ref> into the channel
request will ensure the CM knows. For example:</p>
<blockquote>
<pre>
{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org",
...<tp:member-ref>RoomName</tp:member-ref>: ""
}</pre></blockquote>
<p>If <tp:member-ref>RoomName</tp:member-ref> features in
<var>Allowed_Properties</var> then the only value allowed in conjunction
with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
is the empty string. Requests with conflicting
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
and <tp:member-ref>RoomName</tp:member-ref> properties
will fail with InvalidArgument.</p>
<p>To create a XEP-0045 §10.1.4 uniquely-named room channel
on the conference.jabber.org server, then the following channel
request should be made:</p>
<blockquote>
<pre>
{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
...<tp:member-ref>RoomName</tp:member-ref>: ""
...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
}</pre>
</blockquote>
<p>If everything is successful, then when the channel request is
satisfied, a new channel will appear with the following properties:</p>
<blockquote>
<pre>
{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
...<tp:member-ref>RoomName</tp:member-ref>: ""
...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
}</pre>
</blockquote>
<p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs)
and then created a room with such a name on the said server. The empty
<tp:member-ref>RoomName</tp:member-ref> property shows that the room name
is not human-readable.</p>
</tp:docstring>
<property name="RoomName" tp:name-for-bindings="Room_Name" type="s"
access="read" tp:immutable="yes" tp:requestable="yes">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The human-readable identifier of a chat room. Note that if
non-empty, this property (and perhaps also
<tp:member-ref>Server</tp:member-ref>) should be sufficient in
a channel request to join the room. XMPP MUCs have a room name
concept which is more like a topic, except more
persistent. This D-Bus property is <strong>not</strong> this
XMPP room name, but the bit before the @ in the room jid; see
<tp:dbus-ref
namespace='ofdT.Channel.Interface'>RoomConfig1.Title</tp:dbus-ref>
for that concept.</p>
<p>This property cannot change during the lifetime of the channel. It
should appear in the <var>Allowed_Properties</var> of a
<tp:type>Requestable_Channel_Class</tp:type> for the connection if
rooms on this connection have human-readable names, and can be joined
by name.</p>
</tp:docstring>
</property>
<property name="Server" tp:name-for-bindings="Server" type="s"
access="read" tp:immutable="yes" tp:requestable="yes">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>For protocols with a concept of chatrooms on multiple servers with
different DNS names (like XMPP), the DNS name of the server hosting
this channel (for example, <tt>"conference.jabber.org"</tt> or
<tt>"groupchat.google.com"</tt>). For other protocols, the empty
string.</p>
<p>This property cannot change during the lifetime of the channel. It
should appear in the <var>Allowed_Properties</var> of a
<tp:type>Requestable_Channel_Class</tp:type> for the connection if
and only if non-empty values are supported.</p>
</tp:docstring>
</property>
<property name="Creator" tp:name-for-bindings="Creator"
type="s" access="read" tp:immutable="yes">
<tp:added version="0.25.0"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The normalized contact ID representing who created the room; or
the empty string if unknown.
</tp:docstring>
</property>
<property name="CreatorHandle" tp:name-for-bindings="Creator_Handle"
type="u" tp:type="Contact_Handle" access="read"
tp:immutable="yes">
<tp:added version="0.25.0"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The handle corresponding to <tp:member-ref>Creator</tp:member-ref>;
or 0 if <tp:member-ref>Creator</tp:member-ref> is unknown.
</tp:docstring>
</property>
<property name="CreationTimestamp"
tp:name-for-bindings="Creation_Timestamp"
type="x" tp:type="Unix_Timestamp64" access="read"
tp:immutable="yes">
<tp:added version="0.25.0"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
A unix timestamp indicating when the room was created; or
<code>INT_MAX64</code> if unknown.
</tp:docstring>
</property>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
