Commit de08b0f2535085b338b5245a0ff237e60ae03483 - telepathy-spec

Imported Upstream version 0.24.0 Jonny Lamb 12 years ago

13 changed file(s) with 876 addition(s) and 239 deletion(s). Raw diff Collapse all Expand all

+345

-0

ChangeLog less more

	0	commit 82a0472e5b37c36e9879f87d152bd7725ac4ecfd
	1	Author: Will Thompson <will.thompson@collabora.co.uk>
	2	Date: Mon Oct 10 11:22:11 2011 +0100
	3
	4	Version 0.24.0
	5
	6	commit 629ddca74435de4a99fd1e1a273a9175167c456b
	7	Author: Will Thompson <will.thompson@collabora.co.uk>
	8	Date: Mon Oct 10 11:17:01 2011 +0100
	9
	10	NEWS for 0.24.0
	11
	12	commit 1a4d9739426f608018c8a1b101137048795cfeb2
	13	Author: Will Thompson <will.thompson@collabora.co.uk>
	14	Date: Mon Oct 10 11:17:07 2011 +0100
	15
	16	Mark changes as changed in 0.24.0
	17
	18	commit e1615f4325ef20f7c59379ebc73fa8b2522d17b6
	19	Merge: c2b50e9 ff3b6d9
	20	Author: Will Thompson <will.thompson@collabora.co.uk>
	21	Date: Mon Oct 10 10:26:55 2011 +0100
	22
	23	Merge branch 'a-bit-more-room'
	24
	25	Fixes: <https://bugs.freedesktop.org/show_bug.cgi?id=23151#c41>
	26
	27	commit ff3b6d94d3ffacadea60521d167ceaf88fb90253
	28	Author: Will Thompson <will.thompson@collabora.co.uk>
	29	Date: Mon Oct 10 10:20:41 2011 +0100
	30
	31	Subject: remove duplicated PropertiesChanged notes
	32
	33	Now that the spec generator obeys the EmitsChangedSignal annotation, we
	34	don't need to mention that each property emits this signal manually.
	35
	36	commit a95a5fdd21e531a6c58a748fdf4f8dc2b78da99e
	37	Author: Will Thompson <will.thompson@collabora.co.uk>
	38	Date: Mon Oct 10 10:00:12 2011 +0100
	39
	40	Subject: add ActorHandle
	41
	42	This addresses Xavier's point on
	43	<https://bugs.freedesktop.org/show_bug.cgi?id=23151#c41>: including both
	44	an ID and a handle allows TpContact objects to be created synchronously.
	45
0	46	commit c2b50e990e649b0247c3f6b09a5eefb7f3f7a280
1	47	Author: Xavier Claessens <xclaesse@gmail.com>
2	48	Date: Thu Sep 29 19:13:44 2011 +0200

22	68	Add MemberIdentifiers, SelfContactChanged and HandleOwnersChangedDetailed
23	69
24	70	Fixes fd.o#38248
	71
	72	commit 4980ef409d09297e0dac56fafefa182eaa6292bd
	73	Author: Will Thompson <will.thompson@collabora.co.uk>
	74	Date: Tue Sep 6 15:06:59 2011 +0100
	75
	76	Undraft Room, Subject and RoomConfig.
	77
	78	The former two are both at version 2, given that both of them have been
	79	implemented before elsewhere as .DRAFT.
	80
	81	commit 3e7521ee128441df9c8ea1b780ca566af587e26c
	82	Author: Will Thompson <will.thompson@collabora.co.uk>
	83	Date: Fri Sep 2 12:07:00 2011 +0100
	84
	85	RoomConfig1: add ConfigurationRetrieved
	86
	87	I found out while writing Gabble's tests that having a checkpoint signal
	88	for “hey the configuration is all ready now” would be useful as a client
	89	developer.
	90
	91	commit f3809c1aa810bddb11b8c41ddf9943c55fd0ab14
	92	Author: Will Thompson <will.thompson@collabora.co.uk>
	93	Date: Mon Aug 29 11:38:08 2011 +0100
	94
	95	RoomConfig.UpdateConfiguration: improve error docs
	96
	97	commit e20bf17fb849d68c91a0490eff958727eadbc583
	98	Author: Will Thompson <will.thompson@collabora.co.uk>
	99	Date: Mon Aug 29 11:02:04 2011 +0100
	100
	101	RoomConfig: remove <tp:added/> from Password[Protected]
	102
	103	These were from when I had added these properties to the existing
	104	Password interface.
	105
	106	commit 225d8d06e12a47aa6f61dddbe0804696c8665cd3
	107	Author: Will Thompson <will.thompson@collabora.co.uk>
	108	Date: Mon Aug 29 11:00:29 2011 +0100
	109
	110	RoomConfig: consistently use <code>True</code>
	111
	112	commit 673d20b199224d7dd6741a6eb3d47e1cac830077
	113	Author: Will Thompson <will.thompson@collabora.co.uk>
	114	Date: Fri Aug 26 15:13:52 2011 +0100
	115
	116	specparser: when errant text is encountered, print it
	117
	118	It's impossible to figure out where the offending unguarded text is if
	119	you don't get told what the text is. :)
	120
	121	commit 9c9e0dc5707b532427fb9c5d3345fdc546691f00
	122	Author: Will Thompson <will.thompson@collabora.co.uk>
	123	Date: Tue Aug 2 11:58:22 2011 +0100
	124
	125	specparser: warn on encountering old-style props
	126
	127	commit aee0d893bd6367b6b2ac7bd43c13d62c2df572b1
	128	Author: Will Thompson <will.thompson@collabora.co.uk>
	129	Date: Tue Aug 2 11:56:25 2011 +0100
	130
	131	Deprecate Telepathy.Properties
	132
	133	commit e292fff92d08757bcc5ca1f82c1a05179bf27b06
	134	Author: Will Thompson <will.thompson@collabora.co.uk>
	135	Date: Tue Aug 2 11:55:40 2011 +0100
	136
	137	MediaSignalling: remove Telepathy properties
	138
	139	These are super-obsolete.
	140
	141	commit 00eac2f473366f257f76b83666ccd897ab915547
	142	Author: Will Thompson <will.thompson@collabora.co.uk>
	143	Date: Tue Aug 2 11:53:19 2011 +0100
	144
	145	Text: remove Telepathy properties
	146
	147	commit 9df491130870319019a6243f3e808188faff2724
	148	Author: Will Thompson <will.thompson@collabora.co.uk>
	149	Date: Wed Aug 3 17:24:37 2011 +0100
	150
	151	RoomConfig: note that this replaces Text's properties
	152
	153	commit 36fe3d35ce6d423559eb749d9c974f80539a7df7
	154	Author: Will Thompson <will.thompson@collabora.co.uk>
	155	Date: Tue Aug 2 11:49:09 2011 +0100
	156
	157	RoomConfig: add props and method for modification
	158
	159	commit 27e51ad0079b7f9cbcd86bb377d4ba6604286f70
	160	Author: Will Thompson <will.thompson@collabora.co.uk>
	161	Date: Wed Aug 3 17:19:59 2011 +0100
	162
	163	Password: note that password config lives on RoomConfig
	164
	165	commit 9d7d5feea1dee9d129994d58d917d6d974f7e2e3
	166	Author: Will Thompson <will.thompson@collabora.co.uk>
	167	Date: Mon Aug 1 17:05:44 2011 +0100
	168
	169	Add Password-related properties to RoomConfig
	170
	171	commit 0d48137642515c2aed563e30cf34769124f46c45
	172	Author: Will Thompson <will.thompson@collabora.co.uk>
	173	Date: Mon Aug 1 13:59:04 2011 +0100
	174
	175	Define RoomConfig, with D-Bus properties for Text's Tp properties
	176
	177	This omits the subject properties (which live on Subject), and currently
	178	omits the password properties (which are a little bit more involved,
	179	particularly on XMPP where you can't generally see what the current
	180	password is as a non-owner of a room).
	181
	182	commit 0db811f2a1329d5fd56c23173b1f2bb49a084cd2
	183	Author: Will Thompson <will.thompson@collabora.co.uk>
	184	Date: Tue Aug 2 11:48:09 2011 +0100
	185
	186	Docs: ignore emits_changed on immutable properties
	187
	188	If you mark a whole interface with emits_changed, but have immutable
	189	properties, we don't want the immutable properties to have the note
	190	about the changed signal.
	191
	192	commit 3566dca46b1fb96d49605ece1f8fde740d6b2168
	193	Author: Will Thompson <will.thompson@collabora.co.uk>
	194	Date: Mon Aug 1 15:28:37 2011 +0100
	195
	196	specparser: tidy up getting EmitsChangedSignal annotation
	197
	198	I think this is neater; it also adds a nice warning that would have
	199	caught a mistake I made.
	200
	201	commit 421a9cbeef88d09306e76347de58367e97cb368c
	202	Author: Will Thompson <will.thompson@collabora.co.uk>
	203	Date: Sun Jul 31 09:30:37 2011 +0100
	204
	205	Subject: correctly annotate with EmitsChangedSignal
	206
	207	Sadly, this is how annotations are done in D-Bus. Also, by moving the
	208	annotation up to the interface itself, it applies to all properties
	209	(rather than three of the properties being omitted).
	210
	211	commit bdd234f063288e1e88e3ef40f8eeb4e1eecdebe4
	212	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	213	Date: Mon May 9 16:28:12 2011 +0100
	214
	215	Subject: note how CanSet might not be correct
	216
	217	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	218
	219	commit 03adf5f7a57374426b2f420c6f6b0e57e3c7aff4
	220	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	221	Date: Mon May 9 16:09:24 2011 +0100
	222
	223	Room, Subject: add note how these interfaces are good for Call too
	224
	225	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	226
	227	commit 5853c87b69c516014905a5a711db8d5ad07a5bcd
	228	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	229	Date: Mon May 9 15:50:38 2011 +0100
	230
	231	Subject: make SetSubject return success if the operation was a success
	232
	233	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	234
	235	commit c06589821e3b5ff86564396f733473cafbd813c0
	236	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	237	Date: Mon May 9 15:48:09 2011 +0100
	238
	239	Subject: use PropertiesChanged as the change notification
	240
	241	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	242
	243	commit 0199b1d6e8bbe00df5de45a3d50ea14b6fe717b2
	244	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	245	Date: Mon May 9 15:34:49 2011 +0100
	246
	247	Subject: reference Room interface, not Room channels
	248
	249	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	250
	251	commit c29f6eb35b0a76281150a84cf76f046c2bdb7ce7
	252	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	253	Date: Mon May 9 15:33:10 2011 +0100
	254
	255	Room: make RoomName and Server immutable and requestable
	256
	257	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	258
	259	commit 5823b564b96f1004e74de70f3bde42609499c5c4
	260	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	261	Date: Mon May 9 15:28:54 2011 +0100
	262
	263	Subject: split Subject struct into four properties
	264
	265	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	266
	267	commit 4d3b1d6aff69fd51b5160d4c28b73017148f263c
	268	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	269	Date: Mon May 9 15:18:58 2011 +0100
	270
	271	Subject: replace flags with CanSet
	272
	273	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	274
	275	commit 084708f246c466c9f90a8271435b73fa2fe285a4
	276	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	277	Date: Mon Jan 3 17:37:23 2011 +0000
	278
	279	Room: split subject stuff out into separate interface
	280
	281	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	282
	283	commit f45813cab5155b15d8b59bbc96973351e474cf49
	284	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	285	Date: Mon Jan 3 17:19:47 2011 +0000
	286
	287	Room: SetSubject errors with PermissionDenied if user is not allowed
	288
	289	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	290
	291	commit bcf78e79b7a988d7e9b8700c08cfafa8f28c6a7a
	292	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	293	Date: Mon Jan 3 17:18:41 2011 +0000
	294
	295	Room: make SetSubject error with NotImplemented instead of InvalidArgument
	296
	297	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	298
	299	commit 7458786cc972c20a031ee6b7b5235fb4c06f12c4
	300	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	301	Date: Mon Jan 3 17:12:53 2011 +0000
	302
	303	Room: add more docs describing the Present flag
	304
	305	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	306
	307	commit 501af9e1e09e20bdcae17f8e80dc2156d4ce3888
	308	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	309	Date: Mon Jan 3 17:05:17 2011 +0000
	310
	311	Room: rename RoomID to RoomName
	312
	313	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	314
	315	commit 5fae6619221a00a40308d290cbc2fe4557e5b647
	316	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	317	Date: Mon Jan 3 10:23:49 2011 +0000
	318
	319	Text: point to Room in the top-level docstring
	320
	321	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	322
	323	commit edd5ccfda910cf28b263eddf31a57707e49b92de
	324	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	325	Date: Mon Jan 3 10:00:34 2011 +0000
	326
	327	Room: reference the new SubjectChanged property
	328
	329	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	330
	331	commit 30226918ddec442a3d9609727cc39d3cef960430
	332	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	333	Date: Mon Jan 3 09:58:57 2011 +0000
	334
	335	Room: add a SubjectChanged signal
	336
	337	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	338
	339	commit b8fb3fb8eb9c502caeaa148e186078687fa60a60
	340	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	341	Date: Mon Jan 3 09:56:10 2011 +0000
	342
	343	Room: add a SetSubject method
	344
	345	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	346
	347	commit 7212e5ebf1046dd4f4f3752a946edd73fd5adb22
	348	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	349	Date: Mon Jan 3 09:55:45 2011 +0000
	350
	351	Room: add the subject flags to the Room_Subject struct
	352
	353	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	354
	355	commit bb02392282234fd8e0772c3f6bd04802a864c1ce
	356	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	357	Date: Mon Jan 3 09:52:31 2011 +0000
	358
	359	Room: add Room_Subject_Flags
	360
	361	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
	362
	363	commit 31d51f455a45a526e1009f5428f936b8dedcd21a
	364	Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
	365	Date: Mon Jan 3 09:49:28 2011 +0000
	366
	367	Text: link to RoomID in the name tp property docstring
	368
	369	Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
25	370
26	371	commit dce867f9306d6f0bcb4d88f96b31a0879396d674
27	372	Author: Will Thompson <will.thompson@collabora.co.uk>

+36

-0

NEWS less more

0	0	This file contains the same edited highlights as the announcement emails.
1	1	For full details, see the ChangeLog in tarballs, or "git log" in Git
2	2	checkouts.
	3
	4	telepathy-spec 0.24.0 (2011-10-10)
	5	==================================
	6
	7	The “underestimating the future” release. This is the start of a new
	8	stable branch of the Telepathy specification.
	9
	10	Changes since 0.23.4:
	11
	12	• Channel.Interface.Room has been undrafted, with a few changes:
	13	· The RoomID property has become RoomName;
	14	· The Subject property has been split off onto a separate interface,
	15	Channel.Interface.Subject (which is also undrafted).
	16
	17	• Channel.Interface.RoomConfig has been defined to replace the remaining
	18	klunky Telepathy.Properties on Channel.Type.Text.
	19
	20	• As a result, the Telepathy.Properties interface has been deprecated,
	21	since all interfaces which historically used it now have better
	22	replacements.
	23
	24	Other notable changes since the 0.22 stable branch:
	25
	26	• Most interfaces now provide both handles and identifiers for contacts.
	27	This makes life easier for telepathy-glib and telepathy-qt4 (and, by
	28	extension, application authors).
	29
	30	• A new revision of the Call family of interfaces has landed. It is
	31	still marked experimental.
	32
	33	• ChannelDispatcher has a pair of new methods, DelegateChannels() and
	34	PresentChannel(), to aid user interfaces where channels can be shown
	35	in a number of places (like Gnome 3).
	36
	37	• FileTransfer now has a URI property to indicate the on-disk location
	38	of the file being sent or received.
3	39
4	40	telepathy-spec 0.23.4 (2011-09-29)
5	41	==================================

-0

doc/templates/interface.html less more

417	417	$property.get_changed()
418	418	$property.get_deprecated()
419	419
	420	#if not $property.immutable:
420	421	#if $property.emits_changed == $property.EMITS_CHANGED_UPDATES
421	422	<div class="annotation emits-changed emits-changed-updates">
422	423	When this property changes, the

434	435	The <code>org.freedesktop.DBus.Properties.PropertiesChanged</code>
435	436	signal is <strong>not</strong> emitted when this property changes.
436	437	</div>
	438	#end if
437	439	#end if
438	440
439	441	#if $property.is_connection_parameter:

-48

spec/Channel_Interface_Media_Signalling.xml less more

20	20	<interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling">
21	21	<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
22	22	<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
	23	<tp:changed version="0.24.0">The old-style Telepathy properties,
	24	deprecated since March 2009, have been removed.</tp:changed>
23	25
24	26	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
25	27	<p>An interface for signalling a channel containing synchronised media

103	105	</tp:docstring>
104	106	</signal>
105	107
106		<tp:property name="nat-traversal" type="s">
107		<tp:deprecated version="0.17.22">Use the <tp:dbus-ref
108		namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
109		property on the Media.StreamHandler, if available; use this
110		as a fallback.</tp:deprecated>
111		<tp:docstring>
112		A string indicating the NAT traversal techniques employed by the
113		streams within this channel if they do not have a <tp:dbus-ref
114		namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
115		property. The possible values are the same as for the NATTraversal
116		property on the streams.
117		</tp:docstring>
118		</tp:property>
119
120		<tp:property name="stun-server" type="s">
121		<tp:deprecated version="0.17.22">Use the <tp:dbus-ref
122		namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
123		property on the Media.StreamHandler, if available; use this
124		as a fallback.</tp:deprecated>
125		<tp:docstring>
126		The IP address or hostname of the STUN server to use for NAT traversal
127		if the individual streams do not specify one.
128		</tp:docstring>
129		</tp:property>
130
131		<tp:property name="stun-port" type="q">
132		<tp:deprecated version="0.17.22">Use the <tp:dbus-ref
133		namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
134		property on the Media.StreamHandler, if available; use this
135		as a fallback.</tp:deprecated>
136		<tp:docstring>
137		The UDP port number to use on the provided STUN server.
138		</tp:docstring>
139		</tp:property>
140
141		<tp:property name="gtalk-p2p-relay-token" type="s">
142		<tp:deprecated version="0.17.22">XMPP connection managers
143		supporting the Google Talk relay server SHOULD make the necessary
144		HTTP requests to find a username and password, and use those
145		to populate the <tp:dbus-ref
146		namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref>
147		property on the Media.StreamHandler.</tp:deprecated>
148		<tp:docstring>
149		The authentication token for use with the Google Talk peer-to-peer relay
150		server.
151		</tp:docstring>
152		</tp:property>
153
154	108	<tp:hct name="gtalk-p2p">
155	109	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
156	110	<p>The client can implement streaming for streams whose <tp:dbus-ref

+11

-8

spec/Channel_Interface_Password.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2	2	<tp:copyright>
3		Copyright © 2005-2009 Collabora Limited
	3	Copyright © 2005-2011 Collabora Limited
4	4	Copyright © 2005-2009 Nokia Corporation
5	5	Copyright © 2006 INdT
6	6	</tp:copyright>

89	89	</method>
90	90	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
91	91	<p>Interface for channels that may have a password set that users need
92		to provide before being able to join, or may be able to view or change
93		once they have joined the channel.</p>
	92	to provide before being able to join. The
	93	<tp:member-ref>GetPasswordFlags</tp:member-ref> method and the
	94	associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref>
	95	signal indicate whether the user must now provide a password to join
	96	the channel.</p>
94	97
95		<p>The <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the
96		associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref>
97		signal indicate whether the channel has a password, whether the user
98		must now provide it to join, and whether it can be viewed or changed
99		by the user.</p>
	98	<p>Once the user has joined the channel, the current
	99	password-protectedness of the room can be checked (and possibly
	100	modified) using the <tp:dbus-ref
	101	namespace='ofdT.Channel.Interface'>RoomConfig1</tp:dbus-ref>
	102	interface, if implemented.</p>
100	103	</tp:docstring>
101	104	</interface>
102	105	</node>

+33

-69

spec/Channel_Interface_Room.xml less more

20	20	02110-1301, USA.</p>
21	21	</tp:license>
22	22
23		<interface name="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
24		tp:causes-havoc="experimental">
	23	<interface name="org.freedesktop.Telepathy.Channel.Interface.Room2">
25	24	<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
26		<tp:added version="0.19.11">(draft 1)</tp:added>
	25	<tp:added version="0.24.0">(version 2)</tp:added>
27	26
28	27	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
29	28	<p>Different IM protocols use a variety of ways to name chat rooms. The

39	38	href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym
40	39	title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4
41	40	<q>Requesting a Unique Room Name</q></a> defines a protocol for
42		requesting a unique, opaque room name on the server.</p>
	41	requesting a unique, opaque room name on the server. Note that
	42	this interface is not restricted to Text channels, and can
	43	also be used on Call channels.</p>
43	44
44	45	<p>This interface intends to support and differentiate these mechanisms
45	46	more clearly than the <tp:dbus-ref

60	61	<tp:dbus-ref
61	62	namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
62	63	= <code>"#telepathy"</code>,
63		<tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>,
	64	<tp:member-ref>RoomName</tp:member-ref> = <code>"#telepathy"</code>,
64	65	<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
65	66	that the room has a human-readable identifier, and is not confined to
66	67	a particular server on the network.

81	82	<tp:dbus-ref
82	83	namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
83	84	= <code>"0xdeadbeef"</code>,
84		<tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
	85	<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
85	86	<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
86	87	that the room has an identifier but no human-readable name.
87	88	</li>

90	91	<tp:dbus-ref
91	92	namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
92	93	= <code>None</code>,
93		<tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
	94	<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
94	95	<tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
95	96	that the room has neither an identifier (so it cannot be re-joined
96	97	later) nor a human-readable name.

104	105	<tp:dbus-ref
105	106	namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
106	107	= <code>"jdev@conference.jabber.org"</code>,
107		<tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>,
	108	<tp:member-ref>RoomName</tp:member-ref> = <code>"jdev"</code>,
108	109	<tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>.
109	110	</li>
110	111

115	116	<tp:dbus-ref
116	117	namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
117	118	= <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>,
118		<tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
	119	<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
119	120	<tp:member-ref>Server</tp:member-ref> =
120	121	<code>"groupchat.google.com"</code>, indicating that the room has a
121	122	persistent identifier, no human-readable name, and is hosted by a

130	131	<tp:dbus-ref
131	132	namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
132	133	= <code>"lrcgsnthzvwm@conference.jabber.org"</code>,
133		<tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
	134	<tp:member-ref>RoomName</tp:member-ref> = <code>""</code>,
134	135	<tp:member-ref>Server</tp:member-ref> =
135	136	<code>"conference.jabber.org"</code>, indicating that the room has a
136	137	persistent identifier, no human-readable name, and is hosted by a

164	165	>TargetHandle</tp:dbus-ref>.</p>
165	166
166	167	<p>If, like IRC, the room identifiers are also human-readable, the
167		RCCs should also include RoomID in <var>Allowed_Properties</var>:</p>
	168	RCCs should also include RoomName in <var>Allowed_Properties</var>:</p>
168	169
169	170	<blockquote>
170	171	<pre>

178	179	>TargetID</tp:dbus-ref>,
179	180	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
180	181	>TargetHandle</tp:dbus-ref>,
181		...<tp:member-ref>RoomID</tp:member-ref>
	182	...<tp:member-ref>RoomName</tp:member-ref>
182	183	]
183	184	),
184	185

186	187	>ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
187	188	>Text</tp:dbus-ref>
188	189	},
189		Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>,
	190	Allowed = [ ...<tp:member-ref>RoomName</tp:member-ref>,
190	191	]
191	192	)</pre></blockquote>
192	193
193		<p>Requests may specify the RoomID in place of
	194	<p>Requests may specify the RoomName in place of
194	195	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
195	196	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
196		. Note how <tp:member-ref>RoomID</tp:member-ref> appears
	197	. Note how <tp:member-ref>RoomName</tp:member-ref> appears
197	198	in <var>Allowed_Properties</var> of a different RCC because
198	199	when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
199	200	>TargetHandleType</tp:dbus-ref> is omitted (or is None), both

201	202	>TargetHandle</tp:dbus-ref> and
202	203	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
203	204	>TargetID</tp:dbus-ref> must also be omitted.
204		<tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction
	205	<tp:member-ref>RoomName</tp:member-ref> is allowed in conjuction
205	206	with
206	207	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
207	208	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>

220	221	fallback conference server is specified on jabber connections in
221	222	gabble.</p>
222	223
223		<p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref>
	224	<p>If the protocol supports unnamed rooms, <tp:member-ref>RoomName</tp:member-ref>
224	225	should be fixed to the empty string, and
225	226	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
226	227	should be None:</p>

232	233	>Text</tp:dbus-ref>,
233	234	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
234	235	>TargetHandleType</tp:dbus-ref>: None,
235		...<tp:member-ref>RoomID</tp:member-ref>: "",
	236	...<tp:member-ref>RoomName</tp:member-ref>: "",
236	237	},
237	238	Allowed = [ ]
238	239	)</pre></blockquote>

241	242
242	243	<p>When explicitly joining a room, the CM cannot know whether the room
243	244	ID is unique or not. As a result, if this is the case, adding an
244		empty string <tp:member-ref>RoomID</tp:member-ref> into the channel
	245	empty string <tp:member-ref>RoomName</tp:member-ref> into the channel
245	246	request will ensure the CM knows. For example:</p>
246	247
247	248	<blockquote>

249	250	{ ...<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>,
250	251	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
251	252	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org",
252		...<tp:member-ref>RoomID</tp:member-ref>: ""
	253	...<tp:member-ref>RoomName</tp:member-ref>: ""
253	254	}</pre></blockquote>
254	255
255		<p>If <tp:member-ref>RoomID</tp:member-ref> features in
	256	<p>If <tp:member-ref>RoomName</tp:member-ref> features in
256	257	<var>Allowed_Properties</var> then the only value allowed in conjunction
257	258	with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
258	259	or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
259	260	is the empty string. Requests with conflicting
260	261	<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
261		and <tp:member-ref>RoomID</tp:member-ref> properties
	262	and <tp:member-ref>RoomName</tp:member-ref> properties
262	263	will fail with InvalidArgument.</p>
263	264
264	265	<p>To create a XEP-0045 §10.1.4 uniquely-named room channel

268	269	<blockquote>
269	270	<pre>
270	271	{ ...<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>,
271		...<tp:member-ref>RoomID</tp:member-ref>: ""
	272	...<tp:member-ref>RoomName</tp:member-ref>: ""
272	273	...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
273	274	}</pre>
274	275	</blockquote>

281	282	{ ...<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>,
282	283	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
283	284	...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
284		...<tp:member-ref>RoomID</tp:member-ref>: ""
	285	...<tp:member-ref>RoomName</tp:member-ref>: ""
285	286	...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
286	287	}</pre>
287	288	</blockquote>
288	289
289	290	<p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs)
290	291	and then created a room with such a name on the said server. The empty
291		<tp:member-ref>RoomID</tp:member-ref> property shows that the room name
	292	<tp:member-ref>RoomName</tp:member-ref> property shows that the room name
292	293	is not human-readable.</p>
293	294
294	295	</tp:docstring>
295	296
296		<property name="RoomID" tp:name-for-bindings="Room_ID" type="s"
297		access="read">
	297	<property name="RoomName" tp:name-for-bindings="Room_Name" type="s"
	298	access="read" tp:immutable="yes" tp:requestable="yes">
298	299	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
299	300	<p>The human-readable identifier of a chat room. Note that if
300	301	non-empty, this property (and perhaps also

302	303	a channel request to join the room. XMPP MUCs have a room name
303	304	concept which is more like a topic, except more
304	305	persistent. This D-Bus property is <strong>not</strong> this
305		XMPP room name, but the bit before the @ in the room jid.</p>
	306	XMPP room name, but the bit before the @ in the room jid; see
	307	<tp:dbus-ref
	308	namespace='ofdT.Channel.Interface'>RoomConfig1.Title</tp:dbus-ref>
	309	for that concept.</p>
306	310
307	311	<p>This property cannot change during the lifetime of the channel. It
308	312	should appear in the <var>Allowed_Properties</var> of a

313	317	</property>
314	318
315	319	<property name="Server" tp:name-for-bindings="Server" type="s"
316		access="read">
	320	access="read" tp:immutable="yes" tp:requestable="yes">
317	321	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
318	322	<p>For protocols with a concept of chatrooms on multiple servers with
319	323	different DNS names (like XMPP), the DNS name of the server hosting

327	331	and only if non-empty values are supported.</p>
328	332	</tp:docstring>
329	333	</property>
330
331		<tp:struct name="Room_Subject">
332		<tp:docstring>
333		A struct representing the subject of a room channel.
334		</tp:docstring>
335		<tp:member type="s" name="Subject">
336		<tp:docstring>
337		A human-readable description of the current subject of
338		conversation in the channel, similar to /topic in IRC.
339		</tp:docstring>
340		</tp:member>
341		<tp:member type="s" name="Actor">
342		<tp:docstring>
343		A normalized contact ID representing who last modified the
344		subject, or the empty string if it is not known.
345		</tp:docstring>
346		</tp:member>
347		<tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp">
348		<tp:docstring>
349		A unix timestamp indicating when the subject was last modified.
350		</tp:docstring>
351		</tp:member>
352		</tp:struct>
353
354		<property name="Subject" tp:name-for-bindings="Subject"
355		type="(ssx)" tp:type="Room_Subject" access="read">
356		<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
357		<p>The subject on the room such as the topic in an IRC channel,
358		or the room name in XMPP MUCs. In protocols which do not support
359		subjects (like MSN), this property should be ("", "", 0).</p>
360
361		<tp:rationale>This property replaces the subject, subject-contact, and
362		subject-timestamp Telepathy properties of Text channels, as Telepathy
363		properties are soon to be deprecated completely.</tp:rationale>
364
365		<p>This property may change during the lifetime of the channel and
366		MUST not be included in a channel request.</p>
367		</tp:docstring>
368		</property>
369
370	334	</interface>
371	335	</node>
372	336	<!-- vim:set sw=2 sts=2 et ft=xml: -->

+248

-0

spec/Channel_Interface_Room_Config.xml less more

	0	<?xml version="1.0" ?>
	1	<node name="/Channel_Interface_Room_Config"
	2	xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
	3
	4	<tp:copyright>Copyright © 2011 Collabora Ltd.</tp:copyright>
	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
	6	<p>This library is free software; you can redistribute it and/or
	7	modify it under the terms of the GNU Lesser General Public
	8	License as published by the Free Software Foundation; either
	9	version 2.1 of the License, or (at your option) any later version.</p>
	10
	11	<p>This library is distributed in the hope that it will be useful,
	12	but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	14	Lesser General Public License for more details.</p>
	15
	16	<p>You should have received a copy of the GNU Lesser General Public
	17	License along with this library; if not, write to the Free Software
	18	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
	19	02110-1301, USA.</p>
	20	</tp:license>
	21
	22	<interface name="org.freedesktop.Telepathy.Channel.Interface.RoomConfig1">
	23	<tp:added version="0.24.0">version 1. This replaces the old-school
	24	Telepathy properties on <tp:dbus-ref
	25	namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</tp:added>
	26	<tp:requires interface='org.freedesktop.Telepathy.Channel.Interface.Room2'/>
	27	<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal"
	28	value="true"/>
	29
	30	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	31	<p>Represents the configuration of a chatroom, some aspects of which may
	32	be modifiable by the user, depending on their priviledges. This
	33	corresponds to the room configuration on XMPP, and various channel mode
	34	flags on IRC.</p>
	35
	36	<p>The “topic” (on IRC) or “subject” (on XMPP) is not part of this
	37	interface; it can be found on the <tp:dbus-ref
	38	namespace='ofdT.Channel.Interface'>Subject2</tp:dbus-ref>
	39	interface.</p>
	40	</tp:docstring>
	41
	42	<property name="Anonymous" tp:name-for-bindings="Anonymous" type="b" access="read">
	43	<tp:docstring>
	44	<code>True</code> if people may join the channel without other members being made
	45	aware of their identity.
	46	</tp:docstring>
	47	</property>
	48	<property name="InviteOnly" tp:name-for-bindings="InviteOnly" type="b" access="read">
	49	<tp:docstring>
	50	<code>True</code> if people may not join the channel until they have been invited.
	51	</tp:docstring>
	52	</property>
	53	<property name="Limit" tp:name-for-bindings="Limit" type="u" access="read">
	54	<tp:docstring>
	55	The limit to the number of members; or <tt>0</tt> if there is no limit.
	56	</tp:docstring>
	57	</property>
	58	<property name="Moderated" tp:name-for-bindings="Moderated" type="b" access="read">
	59	<tp:docstring>
	60	<code>True</code> if channel membership is not sufficient to allow participation.
	61	</tp:docstring>
	62	</property>
	63	<property name="Title" tp:name-for-bindings="Title" type="s" access="read">
	64	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	65	A human-visible name for the channel, if it differs from <tp:dbus-ref
	66	namespace='ofdT.Channel.Interface'>Room2.RoomName</tp:dbus-ref>; the
	67	empty string, otherwise.
	68
	69	<tp:rationale>
	70	<p>On XMPP, this represents the <code>muc#roomconfig_roomname</code>
	71	field of the <a
	72	href='http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner'><code>muc#roomconfig</code></a>
	73	form. So for <code>jdev@conference.jabber.org</code>, for example:</p>
	74
	75	<ul>
	76	<li><tp:dbus-ref
	77	namespace='ofdT.Channel.Interface'>Room2.RoomName</tp:dbus-ref>
	78	= <code>"jdev"</code>;</li>
	79	<li><tp:dbus-ref
	80	namespace='ofdT.Channel.Interface'>Room2.Server</tp:dbus-ref>
	81	= <code>"conference.jabber.org"</code>;</li>
	82	<li><tp:member-ref>Title</tp:member-ref> = <code>"General Jabber
	83	development discussion"</code>.</li>
	84	</ul>
	85
	86	<p>XEP-0045 is awful.</p>
	87	</tp:rationale>
	88	</tp:docstring>
	89	</property>
	90	<property name="Description" tp:name-for-bindings="Description" type="s" access="read">
	91	<tp:docstring>
	92	A human-readable description of the channel's overall purpose; if any.
	93	</tp:docstring>
	94	</property>
	95	<property name="Persistent" tp:name-for-bindings="Persistent" type="b" access="read">
	96	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	97	<code>True</code> if the channel will remain in existence on the server after all
	98	members have left it.
	99	</tp:docstring>
	100	</property>
	101	<property name="Private" tp:name-for-bindings="Private" type="b" access="read">
	102	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	103	<code>True</code> if the channel is not visible to non-members.
	104	</tp:docstring>
	105	</property>
	106
	107	<property name="PasswordProtected" type="b" access="read"
	108	tp:name-for-bindings="Password_Protected">
	109	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	110	<code>True</code> if contacts joining this channel must provide a
	111	password to be granted entry. Note that this property does not
	112	indicate that a password is required <em>right now</em>; see the
	113	<tp:dbus-ref namespace='ofdT.Channel.Interface'>Password</tp:dbus-ref>
	114	interface for the API used to provide a password while joining a room.
	115	</tp:docstring>
	116	</property>
	117
	118	<property name="Password" tp:name-for-bindings="Password" type="s" access="read">
	119	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	120	If <tp:member-ref>PasswordProtected</tp:member-ref> is
	121	<code>True</code>, the password required to enter the channel, if
	122	known. If the password is unknown, or
	123	<tp:member-ref>PasswordProtected</tp:member-ref> is
	124	<code>False</code>, the empty string.
	125
	126	<tp:rationale>
	127	On XMPP—bless its cotton socks!—non-owners of a MUC cannot see its
	128	current password, even if they just provided the password in order to
	129	join the room…
	130	</tp:rationale>
	131	</tp:docstring>
	132	</property>
	133
	134	<property name="CanUpdateConfiguration" type="b" access="read"
	135	tp:name-for-bindings="Can_Update_Configuration">
	136	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	137	If <code>True</code>, the user may call
	138	<tp:member-ref>UpdateConfiguration</tp:member-ref> to change the values
	139	of the properties listed in
	140	<tp:member-ref>MutableProperties</tp:member-ref>.
	141	</tp:docstring>
	142	</property>
	143
	144	<property name="MutableProperties" type="as" access="read"
	145	tp:name-for-bindings="Mutable_Properties">
	146	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	147	<p>A list of (unqualified) property names on this interface which may
	148	be modified using <tp:member-ref>UpdateConfiguration</tp:member-ref>
	149	(if <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is
	150	<code>True</code>). Properties not listed here cannot be
	151	modified.</p>
	152
	153	<p>For example, IRC does not have the concept of joining a room without
	154	other participants knowing your true identity; so on IRC the
	155	<tp:member-ref>Anonymous</tp:member-ref> property will always be
	156	<code>False</code>, and
	157	<tp:member-ref>MutableProperties</tp:member-ref> will not include
	158	<code>"Anonymous"</code>.</p>
	159	</tp:docstring>
	160	</property>
	161
	162	<property name="ConfigurationRetrieved" type="b" access="read"
	163	tp:name-for-bindings="Configuration_Retrieved">
	164	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	165	<p><code>True</code> once the initial room configuration has been
	166	retrieved, or <code>False</code> otherwise. On some services, this
	167	may take some time after you've joined a room to fetch the
	168	configuration. Once this property changes to <code>True</code>, the
	169	other properties on this interface can be assumed to be accurate;
	170	this property MUST not change to <code>False</code> after it becomes
	171	<code>True</code>.</p>
	172
	173	<tp:rationale>
	174	<p>An application's “configure this room” dialog might choose to
	175	display a spinner while this property is <code>False</code>, rather
	176	than allowing the user to edit probably-inaccurate
	177	configuration.</p>
	178	</tp:rationale>
	179	</tp:docstring>
	180	</property>
	181
	182	<method name="UpdateConfiguration" tp:name-for-bindings="Update_Configuration">
	183	<arg direction="in" name="Properties" type="a{sv}">
	184	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	185	<p>
	186	The new values of one or more properties on this interface, which
	187	must be listed in
	188	<tp:member-ref>MutableProperties</tp:member-ref>. For
	189	instance, to set up a channel for discussing top-secret corporate
	190	merge plans, this parameter might be:
	191	</p>
	192
	193	<blockquote>
	194	<pre>{
	195	'Private': True,
	196	'InviteOnly': True,
	197	'Description': "The first rule of #inteltakeover is: do not talk about #inteltakeover",
	198	}</pre></blockquote>
	199	</tp:docstring>
	200	</arg>
	201	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	202	<p>If <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is
	203	<code>True</code>, modifies the current values of one or more
	204	room properties. This method SHOULD NOT return until the change has
	205	been accepted or declined by the server.</p>
	206
	207	<p>Note that the server may ostensibly accept the changes (thus
	208	allowing this method to return success) but signal different values;
	209	for example, the server might truncate
	210	<tp:member-ref>Title</tp:member-ref> to some maximum length. Callers
	211	SHOULD continue to listen for the <code>PropertiesChanged</code>
	212	signal, and trust the values it signals over those provided to this
	213	method.</p>
	214	</tp:docstring>
	215
	216	<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
	217	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	218	The user is not allowed to reconfigure this room.
	219	</tp:docstring>
	220	</tp:error>
	221
	222	<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
	223	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	224	One or more of the specified properties is unknown, or ill-typed.
	225	</tp:docstring>
	226	</tp:error>
	227
	228	<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
	229	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	230	One or more of the specified properties cannot be modified on this
	231	protocol.
	232	</tp:docstring>
	233	</tp:error>
	234
	235	<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
	236	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	237	The room's current configuration has not yet been retrieved, so we
	238	cannot update it just yet. The application might like to try again
	239	once the <tp:member-ref>ConfigurationRetrieved</tp:member-ref>
	240	property becomes <code>True</code>.
	241	</tp:docstring>
	242	</tp:error>
	243	</method>
	244
	245	</interface>
	246	</node>
	247	<!-- vim:set sw=2 sts=2 et ft=xml: -->

+127

-0

spec/Channel_Interface_Subject.xml less more

	0	<?xml version="1.0" ?>
	1	<node name="/Channel_Interface_Subject"
	2	xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
	3
	4	<tp:copyright>Copyright © 2010–2011 Collabora Ltd.</tp:copyright>
	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
	6	<p>This library is free software; you can redistribute it and/or
	7	modify it under the terms of the GNU Lesser General Public
	8	License as published by the Free Software Foundation; either
	9	version 2.1 of the License, or (at your option) any later version.</p>
	10
	11	<p>This library is distributed in the hope that it will be useful,
	12	but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	14	Lesser General Public License for more details.</p>
	15
	16	<p>You should have received a copy of the GNU Lesser General Public
	17	License along with this library; if not, write to the Free Software
	18	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
	19	02110-1301, USA.</p>
	20	</tp:license>
	21
	22	<interface name="org.freedesktop.Telepathy.Channel.Interface.Subject2">
	23	<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
	24	<tp:added version="0.24.0">(version 2)</tp:added>
	25	<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal"
	26	value="true"/>
	27
	28	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	29	<p>An interface channels can implement to support subjects. Most
	30	of the time this will be implemented by channels implementing
	31	the <tp:dbus-ref
	32	namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref>
	33	interface, but some protocols support subjects in 1-to-1 chats
	34	(such as Skype). Note that this interface is not restricted to
	35	Text channels, and can also be used on Call channels.</p>
	36	</tp:docstring>
	37
	38	<method name="SetSubject" tp:name-for-bindings="Set_Subject">
	39	<arg direction="in" type="s" name="Subject">
	40	<tp:docstring>The new subject.</tp:docstring>
	41	</arg>
	42	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	43	<p>Set the room's subject. Clients SHOULD look at the subject
	44	flags before calling this method as the user might not have
	45	permission to set the subject.</p>
	46
	47	<p>A successful return of this method indicates a successful
	48	change in subject, but clients should still listen for changes
	49	to the <tp:member-ref>Subject</tp:member-ref> property for
	50	further changes by other users or the server.</p>
	51	</tp:docstring>
	52	<tp:possible-errors>
	53	<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
	54	<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
	55	</tp:possible-errors>
	56	</method>
	57
	58	<property name="Subject" tp:name-for-bindings="Subject"
	59	type="s" access="read">
	60	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	61	<p>The human-readable subject on the channel such as the topic
	62	in an IRC channel, or the room name in XMPP MUCs.</p>
	63
	64	<tp:rationale>This property replaces the subject Telepathy
	65	property of Text channels, as Telepathy properties are soon to
	66	be deprecated completely.</tp:rationale>
	67
	68	<p>This property may change during the lifetime of the channel and
	69	MUST not be included in a channel request.</p>
	70	</tp:docstring>
	71	</property>
	72
	73	<property name="Actor" tp:name-for-bindings="Actor"
	74	type="s" access="read">
	75	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	76	<p>The normalized contact ID representing who last modified
	77	the subject, or the empty string if it is not known.</p>
	78
	79	<tp:rationale>This property replaces the subject-contact
	80	Telepathy property of Text channels, as Telepathy properties
	81	are soon to be deprecated completely.</tp:rationale>
	82	</tp:docstring>
	83	</property>
	84
	85	<property name="ActorHandle" tp:name-for-bindings="Actor_Handle"
	86	type="u" tp:type="Contact_Handle" access="read">
	87	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	88	<p>The handle corresponding to <tp:member-ref>Actor</tp:member-ref>.</p>
	89	</tp:docstring>
	90	</property>
	91
	92	<property name="Timestamp" tp:name-for-bindings="Timestamp"
	93	type="x" tp:type="Unix_Timestamp64" access="read">
	94	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	95	<p>A unix timestamp indicating when the subject was last
	96	modified.</p>
	97
	98	<tp:rationale>This property replaces the subject-timestamp
	99	Telepathy property of Text channels, as Telepathy properties
	100	are soon to be deprecated completely.</tp:rationale>
	101	</tp:docstring>
	102	</property>
	103
	104	<property name="CanSet" tp:name-for-bindings="Can_Set"
	105	type="b" access="read">
	106	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	107	<p>TRUE if the <tp:member-ref>Subject</tp:member-ref> property
	108	can be set by the user by calling
	109	<tp:member-ref>SetSubject</tp:member-ref>, otherwise
	110	FALSE.</p>
	111
	112	<p>If implementations are unsure of what this value should be
	113	it SHOULD still be set to what it believes the value
	114	is. As a result, clients should be aware that
	115	<tp:member-ref>SetSubject</tp:member-ref> can still fail
	116	even with this property set to TRUE.</p>
	117
	118	<tp:rationale>In XMPP it is impossible to know whether an
	119	occupant can set the subject as XMPP server implementations
	120	are wildly inconsistent.</tp:rationale>
	121	</tp:docstring>
	122	</property>
	123
	124	</interface>
	125	</node>
	126	<!-- vim:set sw=2 sts=2 et ft=xml: -->

-4

spec/Channel_Type_Room_List.xml less more

85	85	<dt>subject (s)</dt>
86	86	<dd>The current subject of conversation in the room (as would
87	87	be returned by getting the string part of the <tp:dbus-ref
88		namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
	88	namespace="org.freedesktop.Telepathy.Channel.Interface.Subject2"
89	89	>Subject</tp:dbus-ref> property)</dd>
90	90
91	91	<dt>members (u)</dt>

100	100	<dt>room-id (s)</dt>
101	101	<dd>The human-readable identifier of a chat room (as would be
102	102	returned by getting the <tp:dbus-ref
103		namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
104		>RoomID</tp:dbus-ref> property)</dd>
	103	namespace="org.freedesktop.Telepathy.Channel.Interface.Room2"
	104	>RoomName</tp:dbus-ref> property)</dd>
105	105
106	106	<dt>server (s)</dt>
107	107	<dd>The DNS name of the server hosting these channels (as would be
108	108	returned by getting the <tp:dbus-ref
109		namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
	109	namespace="org.freedesktop.Telepathy.Channel.Interface.Room2"
110	110	>Server</tp:dbus-ref> property)</dd>
111	111	</dl>
112	112	</tp:docstring>

+14

-86

spec/Channel_Type_Text.xml less more

23	23	interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
24	24	<tp:changed version="0.21.5">The Messages interface is now
25	25	mandatory</tp:changed>
	26	<tp:changed version="0.24.0">This interface used to have a bunch of
	27	clunky <tp:dbus-ref
	28	namespace='org.freedesktop'>Telepathy.Properties</tp:dbus-ref>. They have
	29	been removed in favour of D-Bus properties on the <tp:dbus-ref
	30	namespace='ofdT.Channel.Interface'>Room2</tp:dbus-ref>, <tp:dbus-ref
	31	namespace='ofdT.Channel.Interface'>Subject2</tp:dbus-ref> and
	32	<tp:dbus-ref namespace='ofdT.Channel.Interface'>RoomConfig1</tp:dbus-ref>
	33	interfaces.</tp:changed>
26	34
27	35	<tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List">
28	36	<tp:docstring>

429	437	</tp:flag>
430	438	</tp:flags>
431	439
432		<tp:property name="anonymous" type="b">
433		<tp:docstring>
434		True if people may join the channel without other members being made
435		aware of their identity.
436		</tp:docstring>
437		</tp:property>
438		<tp:property name="invite-only" type="b">
439		<tp:docstring>
440		True if people may not join the channel until they have been invited.
441		</tp:docstring>
442		</tp:property>
443		<tp:property name="limit" type="u">
444		<tp:docstring>
445		The limit to the number of members, if limited is true.
446		</tp:docstring>
447		</tp:property>
448		<tp:property name="limited" type="b">
449		<tp:docstring>
450		True if there is a limit to the number of channel members.
451		</tp:docstring>
452		</tp:property>
453		<tp:property name="moderated" type="b">
454		<tp:docstring>
455		True if channel membership is not sufficient to allow participation.
456		</tp:docstring>
457		</tp:property>
458		<tp:property name="name" type="s">
459		<tp:docstring>
460		A human-visible name for the channel, if it differs from the channel's
461		<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>.
462		</tp:docstring>
463		</tp:property>
464		<tp:property name="description" type="s">
465		<tp:docstring>
466		A human-readable description of the channel's overall purpose.
467		</tp:docstring>
468		</tp:property>
469		<tp:property name="password" type="s">
470		<tp:docstring>
471		The password required to enter the channel if password-required is true.
472		</tp:docstring>
473		</tp:property>
474		<tp:property name="password-required" type="b">
475		<tp:docstring>
476		True if a password must be provided to enter the channel.
477		</tp:docstring>
478		</tp:property>
479		<tp:property name="persistent" type="b">
480		<tp:docstring>
481		True if the channel will remain in existence on the server after all
482		members have left it.
483		</tp:docstring>
484		</tp:property>
485		<tp:property name="private" type="b">
486		<tp:docstring>
487		True if the channel is not visible to non-members.
488		</tp:docstring>
489		</tp:property>
490		<tp:property name="subject" type="s">
491		<tp:docstring>
492		A human-readable description of the current subject of conversation in
493		the channel, similar to /topic in IRC. This is equivalent to the
494		<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
495		>Subject</tp:dbus-ref> property in the Room interface which will replace
496		this Telepathy property.
497		</tp:docstring>
498		</tp:property>
499		<tp:property name="subject-contact" type="u" tp:type="Contact_Handle">
500		<tp:docstring>
501		A contact handle representing who last modified the subject, or 0
502		if it isn't known. This is equivalent to the
503		<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
504		>Subject</tp:dbus-ref> property in the Room interface which will replace
505		this Telepathy property.
506		</tp:docstring>
507		</tp:property>
508		<tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp">
509		<tp:docstring>
510		A unix timestamp indicating when the subject was last modified.
511		This is equivalent to the
512		<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
513		>Subject</tp:dbus-ref> property in the Room interface which will replace
514		this Telepathy property.
515		</tp:docstring>
516		</tp:property>
517
518	440	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
519	441	<p>A channel type for sending and receiving messages. This channel type
520	442	is primarily used for textual messages, but can also be used for

679	601	eventually need a distinction between Close and Destroy.</p>
680	602	</tp:rationale>
681	603
	604	<p>Opaquely-named rejoinable chatrooms (such as Skype rooms) are
	605	represented using the properties in the <tp:dbus-ref
	606	namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref>
	607	interface. Instructions and examples of how to request
	608	such channels are given in said interface's description.</p>
	609
682	610	</tp:docstring>
683	611	</interface>
684	612	</node>

-0

spec/Properties_Interface.xml less more

18	18	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
19	19	</tp:license>
20	20	<interface name="org.freedesktop.Telepathy.Properties">
	21	<tp:deprecated version="0.24.0">All uses of this interface have been
	22	expunged, and it may now be laid to rest.</tp:deprecated>
21	23
22	24	<tp:struct name="Property_Spec" array-name="Property_Spec_List">
23	25	<tp:docstring>A struct (property ID, property name, D-Bus signature,

-1

spec/all.xml less more

2	2	xmlns:xi="http://www.w3.org/2001/XInclude">
3	3
4	4	<tp:title>Telepathy D-Bus Interface Specification</tp:title>
5		<tp:version>0.23.4</tp:version>
	5	<tp:version>0.24.0</tp:version>
6	6
7	7	<tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright>
8	8	<tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>

164	164	<xi:include href="Channel_Interface_Group.xml"/>
165	165	<xi:include href="Channel_Interface_Password.xml"/>
166	166	<xi:include href="Channel_Interface_Room.xml"/>
	167	<xi:include href="Channel_Interface_Room_Config.xml"/>
167	168	<xi:include href="Channel_Interface_SASL_Authentication.xml"/>
168	169	<xi:include href="Channel_Interface_Credentials_Storage.xml"/>
169	170	<xi:include href="Channel_Interface_Securable.xml"/>
170	171	<xi:include href="Channel_Interface_Service_Point.xml"/>
	172	<xi:include href="Channel_Interface_Subject.xml"/>
171	173	<xi:include href="Channel_Interface_Tube.xml"/>
172	174
173	175	<tp:section name="Text-specific interfaces">

+49

-23

tools/specparser.py less more

149	149	if (child.nodeType == dom.TEXT_NODE and
150	150	child.data.strip() != ''):
151	151	raise BrokenHTML('Text found in node %s of %s, did you mean '
152		'to use <tp:docstring/>?' %
153		(self.__class__.__name__, self.parent))
	152	'to use <tp:docstring/>? Offending text:\n\n%s' %
	153	(self.__class__.__name__, self.parent, child.data.strip()))
154	154	elif child.nodeType == dom.ELEMENT_NODE:
155	155	if child.tagName in ('p', 'em', 'strong', 'ul', 'li', 'dl',
156	156	'a', 'tt', 'code'):

613	613	def __repr__(self):
614	614	return '%s(%s:%s)' % (self.__class__.__name__, self.name, self.dbus_type)
615	615
616		class Property(DBusConstruct, Typed):
617		ACCESS_READ = 1
618		ACCESS_WRITE = 2
619
620		ACCESS_READWRITE = ACCESS_READ \| ACCESS_WRITE
621
	616	class HasEmitsChangedAnnotation(object):
622	617	EMITS_CHANGED_UNKNOWN = 0
623	618	EMITS_CHANGED_NONE = 1
624	619	EMITS_CHANGED_UPDATES = 2
625	620	EMITS_CHANGED_INVALIDATES = 3
	621
	622	# According to the D-Bus specification, EmitsChangedSignal defaults
	623	# to true, but - realistically - this cannot be assumed for old specs.
	624	# As a result, we treat the absence of the annotation as "unknown".
	625	__MAPPING = { None: EMITS_CHANGED_UNKNOWN,
	626	'false': EMITS_CHANGED_NONE,
	627	'invalidates': EMITS_CHANGED_INVALIDATES,
	628	'true': EMITS_CHANGED_UPDATES,
	629	}
	630
	631	__ANNOTATION = 'org.freedesktop.DBus.Property.EmitsChangedSignal'
	632
	633	def _get_emits_changed(self, dom):
	634	emits_changed = getAnnotationByName(dom, self.__ANNOTATION)
	635
	636	try:
	637	return self.__MAPPING[emits_changed]
	638	except KeyError:
	639	print >> sys.stderr, """
	640	WARNING: <annotation name='%s'/> has unknown value '%s'
	641	(in %s)
	642	""".strip() % (self.__ANNOTATION, emits_changed, self)
	643	return self.EMITS_CHANGED_UNKNOWN;
	644
	645	class Property(DBusConstruct, Typed, HasEmitsChangedAnnotation):
	646	ACCESS_READ = 1
	647	ACCESS_WRITE = 2
	648
	649	ACCESS_READWRITE = ACCESS_READ \| ACCESS_WRITE
626	650
627	651	def __init__(self, parent, namespace, dom):
628	652	super(Property, self).__init__(parent, namespace, dom)

648	672	self.requestable = requestable != ''
649	673	self.sometimes_requestable = requestable == 'sometimes'
650	674
651		# According to the D-Bus specification, EmitsChangedSignal defaults
652		# to true, but - realistically - this cannot be assumed for old specs.
653		# As a result, we treat the absence of the annotation as "unknown".
654		emits_changed = getAnnotationByName(dom, 'org.freedesktop.DBus.Property.EmitsChangedSignal')
655		if emits_changed is None:
656		emits_changed = getAnnotationByName(dom.parentNode, 'org.freedesktop.DBus.Property.EmitsChangedSignal')
657		if emits_changed == 'true':
658		self.emits_changed = self.EMITS_CHANGED_UPDATES;
659		elif emits_changed == 'invalidates':
660		self.emits_changed = self.EMITS_CHANGED_INVALIDATES;
661		elif emits_changed == 'false':
662		self.emits_changed = self.EMITS_CHANGED_NONE;
663		else:
664		self.emits_changed = self.EMITS_CHANGED_UNKNOWN;
	675	self.emits_changed = self._get_emits_changed(dom)
	676
	677	if self.emits_changed == self.EMITS_CHANGED_UNKNOWN:
	678	# If the <property> doesn't have the annotation, grab it from the
	679	# interface.
	680	self.emits_changed = parent.emits_changed
665	681
666	682	def get_access(self):
667	683	if self.access & self.ACCESS_READ and self.access & self.ACCESS_WRITE:

687	703	return ', '.join(descriptions)
688	704
689	705	class AwkwardTelepathyProperty(Typed):
	706	def __init__(self, parent, namespace, dom):
	707	Typed.__init__(self, parent, namespace, dom)
	708
	709	print >> sys.stderr, """
	710	WARNING: Old-style Telepathy properties are deprecated!
	711	(<tp:property> in %s)
	712	""".strip() % (parent)
	713
690	714	def get_type_name(self):
691	715	return 'Telepathy Property'
692	716

744	768	def __repr__(self):
745	769	return '%s(%s)' % (self.__class__.__name__, self.name)
746	770
747		class Interface(Base):
	771	class Interface(Base, HasEmitsChangedAnnotation):
748	772	def __init__(self, parent, namespace, dom, spec_namespace):
749	773	super(Interface, self).__init__(parent, namespace, dom)
750	774

777	801	.replace('.Connection.', '.Conn.')
778	802	.replace('.Type.', '.T.')[1:]
779	803	)
	804
	805	self.emits_changed = self._get_emits_changed(dom)
780	806
781	807	# build lists of methods, etc., in this interface
782	808	self.methods = build_list(self, Method, self.name,