Commit 40ae64a7f87e3b516dce5c691e3b2ca33250f128 - telepathy-spec

Imported Upstream version 0.17.17 Simon McVittie 15 years ago

11 changed file(s) with 489 addition(s) and 59 deletion(s). Raw diff Collapse all Expand all

+251

-0

ChangeLog less more

	0	commit 993a81189d0b790458a8798493d6cca630721a46
	1	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	2	Date: 2009-01-06 19:50:39 +0000
	3
	4	Fix malformed XML in .Group
	5
	6	spec/Channel_Interface_Group.xml \| 1 -
	7	1 files changed, 0 insertions(+), 1 deletions(-)
	8
	9	commit 1b1ca138be59dda4723046e1c86f725827054090
	10	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	11	Date: 2009-01-06 19:38:39 +0000
	12
	13	Prepare version 0.17.17
	14
	15	NEWS \| 32 ++++++++++++++++++++++++++++++--
	16	spec/Channel_Interface_Group.xml \| 2 +-
	17	spec/Channel_Interface_Messages.xml \| 2 ++
	18	spec/all.xml \| 2 +-
	19	4 files changed, 34 insertions(+), 4 deletions(-)
	20
	21	commit e2ad62af7a23e944556119ae195a29eda15006a3
	22	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	23	Date: 2009-01-06 19:34:58 +0000
	24
	25	It's 2009, update copyright on things altered recently
	26
	27	Also, bump copyright year to 2008 on some things altered in recent releases
	28
	29	spec/Account_Manager.xml \| 4 ++--
	30	spec/Channel_Interface_Group.xml \| 4 ++--
	31	spec/Channel_Interface_Messages.xml \| 4 ++--
	32	spec/Connection.xml \| 4 ++--
	33	spec/Connection_Interface_Avatars.xml \| 4 ++--
	34	spec/Connection_Manager.xml \| 4 ++--
	35	spec/Media_Stream_Handler.xml \| 4 ++--
	36	7 files changed, 14 insertions(+), 14 deletions(-)
	37
	38	commit e948a0091203625965a39b277e14da8848eb077a
	39	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	40	Date: 2009-01-06 19:19:45 +0000
	41
	42	Rename member-ids to contact-ids and clarify that it's only an optimization
	43
	44	The contacts aren't necessarily all members of the group (in XMPP you
	45	can be kicked by someone not currently in the chatroom) so member-ids was
	46	a misleading name.
	47
	48	In addition, we explicitly allow the CM to include and exclude arbitrary
	49	handle/ID pairs in the mapping, or omit it entirely; clients must have a
	50	fallback path anyway, so this doesn't make clients any more complicated.
	51
	52	spec/Channel_Interface_Group.xml \| 18 +++++++++++++-----
	53	1 files changed, 13 insertions(+), 5 deletions(-)
	54
	55	commit d83b5c3be9dfce9b6ccad20e2c9b40db41b7636b
	56	Merge: 886078f... 68f5317...
	57	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	58	Date: 2009-01-06 19:01:56 +0000
	59
	60	Merge commit 'wjt/trivia'
	61
	62	commit 886078f0593d1af9bbfebfa5efafdf99967f00d0
	63	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	64	Date: 2009-01-06 18:09:34 +0000
	65
	66	Messages: name the Message_Part_Content_Map type
	67
	68	Documenting it properly requires inventing a Message_Part_Index type,
	69	so add that too.
	70
	71	This is needed because Telepathy-Qt4 can't cope with unnamed container
	72	types, apart from the few that QtDBus special-cases. It also improves
	73	our documentation.
	74
	75	Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
	76
	77	spec/Channel_Interface_Messages.xml \| 36 +++++++++++++++++++++++++++++++++-
	78	1 files changed, 34 insertions(+), 2 deletions(-)
	79
	80	commit 2e5912061bdf06bbf5db847c67156e5a069d30d5
	81	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	82	Date: 2009-01-06 18:07:30 +0000
	83
	84	Message_Part: add array-depth
	85
	86	Unlike telepathy-glib, telepathy-qt needs named types for (almost)
	87	every type used in generated code. In this case we need to have a name
	88	for an array of arrays of mappings (aaa{sv}). array²-name was proposed,
	89	but is not well-formed XML :-( and doesn't scale if we ever need
	90	an array of arrays of arrays of mappings (etc.).
	91
	92	The semantics of array-depth are:
	93	* if array-depth is omitted, its value defaults to 1 if there is an
	94	array-name, or 0 otherwise
	95	* if array-depth >= 1, an array-name must be given
	96	* a number of array types equal to array-depth is generated
	97	* the first array type is named using array-name
	98	* subsequent array types are named in an implementation-dependent way:
	99	currently TelepathyQt4 just appends "List" repeatedly
	100
	101	Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
	102
	103	spec/Channel_Interface_Messages.xml \| 3 ++-
	104	1 files changed, 2 insertions(+), 1 deletions(-)
	105
	106	commit d90ca875715b3317938eec8ef0ffe76a83d1502f
	107	Author: George Goldberg <grundleborg@googlemail.com>
	108	Date: 2009-01-05 19:45:27 +0000
	109
	110	Add tp:rationale explaining the changes to Display_Name documentation.
	111
	112	spec/Account_Manager.xml \| 16 +++++++++++++++-
	113	1 files changed, 15 insertions(+), 1 deletions(-)
	114
	115	commit a357ebf4b33316e00d6871c9846531cc2a469a1e
	116	Author: George Goldberg <grundleborg@googlemail.com>
	117	Date: 2009-01-05 19:00:18 +0000
	118
	119	Improve wording of Display_Name parameter of CreateAccount method.
	120
	121	spec/Account_Manager.xml \| 5 ++---
	122	1 files changed, 2 insertions(+), 3 deletions(-)
	123
	124	commit 9535fc64aab3540d62ee50fc83c7c7cccf863054
	125	Author: George Goldberg <grundleborg@googlemail.com>
	126	Date: 2009-01-05 18:59:07 +0000
	127
	128	Clarify explanation of Display_Name parameter on CreateAccount method of AccountManager interface.
	129
	130	spec/Account_Manager.xml \| 9 ++++++---
	131	1 files changed, 6 insertions(+), 3 deletions(-)
	132
	133	commit 68f5317b20127f8b5d78743c29df9c7d0174b9a7
	134	Author: Will Thompson <will.thompson@collabora.co.uk>
	135	Date: 2009-01-03 13:23:33 +0000
	136
	137	Handle_Identifier_Map: tidy documentation of value
	138
	139	spec/Channel_Interface_Group.xml \| 2 +-
	140	1 files changed, 1 insertions(+), 1 deletions(-)
	141
	142	commit 17b7f336a59fd6f007e79c58dd9de8481224eede
	143	Author: Will Thompson <will.thompson@collabora.co.uk>
	144	Date: 2009-01-03 13:21:02 +0000
	145
	146	MembersChangedDetailed: include actor's id in member-ids
	147
	148	Perhaps the detail should be called something other than member-ids,
	149	given that the actor may not be in the channel?
	150
	151	spec/Channel_Interface_Group.xml \| 6 +++---
	152	1 files changed, 3 insertions(+), 3 deletions(-)
	153
	154	commit e48b924fe1f3dfd4f789da2d316a650ebb6c9fd0
	155	Author: Will Thompson <will.thompson@collabora.co.uk>
	156	Date: 2009-01-02 19:34:35 +0000
	157
	158	Group: MembersChangedDetailed flag's state must not change
	159
	160	It may in retrospect have been a mistake to use a group flag to signal
	161	that the MembersChangedDetailed signal will be emitted, since groups'
	162	flags can change over their lifetime so a channel might start and stop
	163	emitting the new signal. So... let's define that not to happen. :-)
	164
	165	spec/Channel_Interface_Group.xml \| 11 ++++++++++-
	166	1 files changed, 10 insertions(+), 1 deletions(-)
	167
	168	commit 6dbd96ce32dfcdac2913ae719cbcce2159f076e2
	169	Author: Will Thompson <will.thompson@collabora.co.uk>
	170	Date: 2009-01-02 18:04:52 +0000
	171
	172	Channel.Requested does not make sense in channel requests
	173
	174	spec/Channel.xml \| 6 ++++++
	175	1 files changed, 6 insertions(+), 0 deletions(-)
	176
	177	commit 5f11fa65a2dc89975ebda52b895532f3111855c9
	178	Author: Will Thompson <will.thompson@collabora.co.uk>
	179	Date: 2009-01-02 17:50:55 +0000
	180
	181	Add cross-reference links to Connection.
	182
	183	In the process, fix a reference to an alleged "GetHandle()" method on
	184	channels, and several references to ReleaseHandle (singular).
	185
	186	spec/Connection.xml \| 48 ++++++++++++++++++++++++++++++++----------------
	187	1 files changed, 32 insertions(+), 16 deletions(-)
	188
	189	commit 1ac74d3ef9889840cbb9dcb47f8254152f900a83
	190	Author: Will Thompson <will.thompson@collabora.co.uk>
	191	Date: 2009-01-02 17:39:28 +0000
	192
	193	Let RequestHandles raise NotImplemented
	194
	195	telepathy-glib's implementation currently raises NotAvailable if a given
	196	handle type is unimplemented, with a FIXME that this change should be
	197	made to the spec to allow it to raise NotImplemented.
	198
	199	spec/Connection.xml \| 7 +++++++
	200	1 files changed, 7 insertions(+), 0 deletions(-)
	201
	202	commit 19452bf88fb8ef0ed80f33a1575222779a25be2a
	203	Author: George Goldberg <grundleborg@googlemail.com>
	204	Date: 2009-01-01 13:29:20 +0000
	205
	206	Clarify the tp:rationale for AccountManager interface's AccountRemoved() signal.
	207
	208	spec/Account_Manager.xml \| 3 ++-
	209	1 files changed, 2 insertions(+), 1 deletions(-)
	210
	211	commit 65692daa7bcc2906baa7e16ab4c2d53cf0aad536
	212	Author: Will Thompson <will.thompson@collabora.co.uk>
	213	Date: 2008-12-18 12:31:36 +0000
	214
	215	MembersChangedDetailed: add member-ids detail
	216
	217	spec/Channel_Interface_Group.xml \| 17 +++++++++++++++++
	218	1 files changed, 17 insertions(+), 0 deletions(-)
	219
	220	commit 7b2ebb9d87f4230469920b5d95306c90911a0eb6
	221	Author: Will Thompson <will.thompson@collabora.co.uk>
	222	Date: 2008-12-18 12:27:55 +0000
	223
	224	Add a handle -> identifier map type
	225
	226	spec/Channel_Interface_Group.xml \| 20 ++++++++++++++++++++
	227	1 files changed, 20 insertions(+), 0 deletions(-)
	228
	229	commit d72330742b47ca428389fd127b0857f68b1bc9eb
	230	Author: Will Thompson <will.thompson@collabora.co.uk>
	231	Date: 2008-12-11 15:41:32 +0000
	232
	233	Document definition of Media_Stream_Handler_Codec
	234
	235	Previously, the documentation was a big mess of unformatted text on one method
	236	that happens to use this type. Now, it's on the struct's definition.
	237
	238	spec/Media_Stream_Handler.xml \| 52 +++++++++++++++++++++++++---------------
	239	1 files changed, 32 insertions(+), 20 deletions(-)
	240
	241	commit f2cb049d4026db8e2f671457f174438212a15bfc
	242	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
	243	Date: 2008-12-12 17:40:10 +0000
	244
	245	Bump version number
	246
	247	NEWS \| 5 +++++
	248	spec/all.xml \| 2 +-
	249	2 files changed, 6 insertions(+), 1 deletions(-)
	250
0	251	commit 3a27bc4466b47396ad699c7b20a2809c307e814f
1	252	Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
2	253	Date: 2008-12-12 17:38:00 +0000

+33

-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.17.17 (2009-01-06)
	5	===================================
	6
	7	The "why is ³ a NameChar, but not ²?" release.
	8
	9	New API:
	10
	11	* Added Handle_Identifier_Map, an a{us} mapping handles to identifiers, and
	12	a "contact-ids" detail of that type in the MembersChangedDetailed signal
	13	(for round-trip reduction)
	14
	15	* In the Messages interface, Message_Part_Index and Message_Part_Content_Map
	16	now have explicit types
	17
	18	* RequestHandles can now raise NotImplemented
	19
	20	Spec markup enhancements:
	21
	22	* Container types have an array-depth attribute indicating how deeply nested
	23	an array of arrays ... of the type can sensibly be; the only use so far
	24	is Message_Part, which can have an array depth of 2 (Message_Part[][])
	25
	26	Clarifications:
	27
	28	* The Requested property MUST NOT be accepted by CreateChannel, EnsureChannel
	29	(it would make no sense)
	30
	31	* The Members_Changed_Detailed flag on groups MUST NOT change during the
	32	channel's lifetime
	33
	34	* clarify the role of the Display_Name parameter to
	35	AccountManager.CreateAccount
3	36
4	37	telepathy-spec 0.17.16 (2008-12-12)
5	38	===================================

+23

-6

spec/Account_Manager.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Account_Manager"
2	2	xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3		<tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
4		<tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
	3	<tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
	4	<tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or
7	7	modify it under the terms of the GNU Lesser General Public

88	88
89	89	<tp:rationale>
90	90	This is effectively change notification for the valid and invalid
91		accounts lists.
	91	accounts lists. On emission of this signal, the Account indicated
	92	will no longer be present in either of the lists.
92	93	</tp:rationale>
93	94	</tp:docstring>
94	95

147	148	<arg name="Display_Name" direction="in" type="s">
148	149	<tp:docstring>The initial value of the new account's <tp:dbus-ref
149	150	namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
150		property. The account manager MAY modify this to make it unique,
151		for instance by appending a number or the 'account'
152		parameter.</tp:docstring>
	151	property. The account manager SHOULD modify this to make it unique if
	152	an Account already exists with the same display name, for instance by
	153	appending a number or the 'account' parameter. Account manager
	154	implementations SHOULD accept an empty string but account editing user
	155	interfaces should avoid passing an empty string for this parameter.
	156
	157	<tp:rationale>
	158	<p>The account creation UI may ask the user for a name for the new
	159	account. If the author of the UI chooses not to do this, the
	160	account creation UI is better able to suggest a default display
	161	name because it has protocol-specific knowledge which the account
	162	manager does not.</p>
	163
	164	<p>The account manager always knows the complete list of accounts so
	165	it can easily tell whether it should append something to the
	166	display name to avoid presenting two identically-named accounts to
	167	the user.</p>
	168	</tp:rationale>
	169	</tp:docstring>
153	170	</arg>
154	171
155	172	<arg name="Parameters" direction="in" type="a{sv}">

-0

spec/Channel.xml less more

338	338	dispatcher that channels with suppress_handler false are
339	339	indeed unrequested.</p>
340	340	</tp:rationale>
	341
	342	<p>It does not make sense for this property to be in channel
	343	requests—it will always be true for channels returned by
	344	CreateChannel, and callers of EnsureChannel cannot control whether an
	345	existing channel was originally requested locally—so it MUST NOT
	346	be accepted.</p>
341	347	</tp:docstring>
342	348	</property>
343	349

+56

-3

spec/Channel_Interface_Group.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2		<tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
3		<tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
	2	<tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
	3	<tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright>
4	4	<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or

225	225	Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref>
226	226	will be emitted for changes to this group's members in addition to
227	227	<tp:member-ref>MembersChanged</tp:member-ref>.
228		Clients can then connect to the former and ignore emission of the latter.
	228	Clients can then connect to the former and ignore emission of the
	229	latter. This flag's state MUST NOT change over the lifetime of a
	230	channel.
	231
	232	<tp:rationale>
	233	If it were allowed to change, client bindings would have to always
	234	connect to MembersChanged just in case the flag ever went away (and
	235	generally be unnecessarily complicated), which would mostly negate
	236	the point of having this flag in the first place.
	237	</tp:rationale>
229	238	</tp:docstring>
230	239	</tp:flag>
231	240	</tp:flags>

697	706	</tp:docstring>
698	707	</signal>
699	708
	709	<tp:mapping name="Handle_Identifier_Map">
	710	<tp:docstring>
	711	A map from handles to the corresponding normalized string identifier.
	712	</tp:docstring>
	713	<tp:added version="0.17.17"/>
	714
	715	<tp:member type="u" name="Handle" tp:type="Contact_Handle">
	716	<tp:docstring>
	717	A nonzero handle
	718	</tp:docstring>
	719	</tp:member>
	720	<tp:member type="s" name="Identifier">
	721	<tp:docstring>
	722	The same string that would be returned by <tp:dbus-ref
	723	namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
	724	for this handle.
	725	</tp:docstring>
	726	</tp:member>
	727	</tp:mapping>
	728
700	729	<signal name="MembersChangedDetailed"
701	730	tp:name-for-bindings="Members_Changed_Detailed">
702	731	<arg name="Added" type="au" tp:type="Contact_Handle[]">

731	760
732	761	<dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt>
733	762	<dd>A reason for the change.</dd>
	763
	764	<dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt>
	765	<dd>
	766	<p>The string identifiers for handles mentioned in this signal, to
	767	give clients the minimal information necessary to react to the
	768	event without waiting for round-trips. Connection managers
	769	SHOULD include the identifiers for members added to the group and
	770	for the actor (if any); they MAY omit the identifiers for handles
	771	which have been removed from the group.</p>
	772
	773	<tp:rationale>
	774	<p>On IRC, an event such as a netsplit could cause the vast
	775	majority of a channel to leave. Given that clients should
	776	already know the identifiers of a channel's members, including
	777	potentially hundreds of strings in the netsplit signal is
	778	unnecessary.</p>
	779	</tp:rationale>
	780
	781	<p>Clients MUST NOT assume that the presence or absence of a
	782	handle in this mapping is meaningful. This mapping is merely
	783	an optimization for round-trip reduction, and connection
	784	managers MAY add additional handles, omit some handles, or
	785	omit the mapping completely.</p>
	786	</dd>
734	787
735	788	<dt>message (s)</dt>
736	789	<dd>A string message from the server regarding the change</dd>

+40

-5

spec/Channel_Interface_Messages.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Channel_Interface_Messages"
2	2	xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3		<tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
4		<tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
	3	<tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
	4	<tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or
7	7	modify it under the terms of the GNU Lesser General Public

177	177	</tp:flag>
178	178	</tp:flags>
179	179
180		<tp:mapping name="Message_Part" array-name="Message_Part_List">
	180	<tp:mapping name="Message_Part" array-name="Message_Part_List"
	181	array-depth="2">
181	182	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
182	183	<p>Part of a message's content. In practice, this mapping never
183	184	appears in isolation - messages are represented by a list of

704	705	</tp:member>
705	706	</tp:mapping>
706	707
	708	<tp:simple-type type="u" name="Message_Part_Index">
	709	<tp:added version="0.17.17"/>
	710	<tp:docstring>
	711	The index of a message part within a message.
	712	</tp:docstring>
	713	</tp:simple-type>
	714
	715	<tp:mapping name="Message_Part_Content_Map">
	716	<tp:added version="0.17.17"/>
	717	<tp:docstring>
	718	A mapping from message part indexes to their content, as returned by
	719	<tp:member-ref>GetPendingMessageContent</tp:member-ref>.
	720	</tp:docstring>
	721
	722	<tp:member type="u" tp:type="Message_Part_Index" name="Part">
	723	<tp:docstring>
	724	Indexes into the array of <tp:type>Message_Part</tp:type>s that
	725	represents a message. The "headers" part (which is not a valid
	726	argument to GetPendingMessageContent) is considered to be part 0,
	727	so the valid part numbers start at 1 (for the second message part).
	728	</tp:docstring>
	729	</tp:member>
	730
	731	<tp:member type="v" name="Content">
	732	<tp:docstring>
	733	The message part's content. The variant MUST contain either type
	734	's' or 'ay' (UTF-8 text string, or byte array), following the
	735	same rules as for the value of the 'content' key in
	736	the <tp:type>Message_Part</tp:type> mappings.
	737	</tp:docstring>
	738	</tp:member>
	739	</tp:mapping>
707	740
708	741	<tp:simple-type type="s" name="Sent_Message_Token">
709	742	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">

913	946	</tp:docstring>
914	947	</arg>
915	948
916		<arg name="Parts" type="au" direction="in">
	949	<arg name="Parts" type="au" direction="in"
	950	tp:type="Message_Part_Index[]">
917	951	<tp:docstring>
918	952	The desired entries in the array of message parts, identified by
919	953	their position. The "headers" part (which is not a valid argument

922	956	</tp:docstring>
923	957	</arg>
924	958
925		<arg name="Content" type="a{uv}" direction="out">
	959	<arg name="Content" type="a{uv}" direction="out"
	960	tp:type="Message_Part_Content_Map">
926	961	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
927	962	<p>The content of the requested parts. The keys in this mapping
928	963	are positions in the array of message parts; the values are

+41

-18

spec/Connection.xml less more

1	1	<node name="/Connection"
2	2	xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
3	3	>
4		<tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright>
5		<tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
	4	<tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
	5	<tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright>
6	6	<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
7	7	<tp:license xmlns="http://www.w3.org/1999/xhtml">
8	8	<p>This library is free software; you can redistribute it and/or

46	46	<method name="Connect" tp:name-for-bindings="Connect">
47	47	<tp:docstring>
48	48	Request that the connection be established. This will be done
49		asynchronously and errors will be returned by emitting StatusChanged
50		signals.
	49	asynchronously and errors will be returned by emitting
	50	<tp:member-ref>StatusChanged</tp:member-ref> signals.
51	51	</tp:docstring>
52	52
53	53	<tp:possible-errors>

123	123	<signal name="SelfHandleChanged"
124	124	tp:name-for-bindings="Self_Handle_Changed">
125	125	<tp:docstring>
126		Emitted whenever the SelfHandle property changes. If the connection
	126	Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
	127	changes. If the connection
127	128	is not yet in the CONNECTED state, this signal is not guaranteed
128	129	to be emitted.
129	130	</tp:docstring>

143	144	<tp:docstring>
144	145	The handle which represents the user on this connection, which will
145	146	remain valid for the lifetime of this connection, or until a change
146		in the user's identifier is signalled by the SelfHandleChanged signal.
	147	in the user's identifier is signalled by the
	148	<tp:member-ref>SelfHandleChanged</tp:member-ref> signal.
147	149	If the connection is not yet in the CONNECTED state, the value of
148	150	this property MAY be zero.
149	151	</tp:docstring>
150	152	<tp:added version="0.17.10">For compatibility with older
151		versions, clients should fall back to calling the GetSelfHandle
	153	versions, clients should fall back to calling the
	154	<tp:member-ref>GetSelfHandle</tp:member-ref>
152	155	method.</tp:added>
153	156	</property>
154	157
155	158	<method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
156	159	<arg direction="out" type="u" tp:type="Contact_Handle">
157	160	<tp:docstring>
158		The value of the SelfHandle property
	161	The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
159	162	</tp:docstring>
160	163	</arg>
161	164

180	183	</arg>
181	184
182	185	<tp:docstring>
183		Get the current status as defined in the StatusChanged signal.
	186	Get the current status as defined in the
	187	<tp:member-ref>StatusChanged</tp:member-ref> signal.
184	188	</tp:docstring>
185	189	</method>
186	190

200	204	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
201	205	<p>Notify the connection manger that your client is holding a copy
202	206	of handles which may not be in use in any existing channel or
203		list, and were not obtained by using the RequestHandles method. For
	207	list, and were not obtained by using the
	208	<tp:member-ref>RequestHandles</tp:member-ref> method. For
204	209	example, a handle observed in an emitted signal, or displayed
205	210	somewhere in the UI that is not associated with a channel. The
206	211	connection manager must not deallocate a handle where any clients
207		have used this method to indicate it is in use until the ReleaseHandle
	212	have used this method to indicate it is in use until the
	213	<tp:member-ref>ReleaseHandles</tp:member-ref>
208	214	method is called, or the clients disappear from the bus.</p>
209	215
210	216	<p>Note that HoldHandles is idempotent - calling it multiple times

308	314	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
309	315	<p>If true, the channel was requested by a client that intends to
310	316	present it to the user itself (i.e. it passed suppress_handler=TRUE
311		to the RequestChannel method), so no other handler should be
	317	to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no
	318	other handler should be
312	319	launched. Clients MAY assume that channels where this is true
313	320	were created by a user request.</p>
314	321

444	451
445	452	<p>If a channel to a contact, room etc. is requested, on success, the
446	453	returned channel may either be a new or existing channel to
447		the requested entity (i.e. its GetHandle() returns the
	454	the requested entity (i.e. its
	455	<tp:dbus-ref
	456	namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
	457	and <tp:dbus-ref
	458	namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
	459	properties are the
448	460	requested handle type and handle), or a newly created "anonymous"
449	461	channel associated with the requested handle in some
450	462	implementation-specific way.</p>

560	572	number of contacts, rooms or server-stored lists on the service. The
561	573	connection manager should record that these handles are in use by the
562	574	client who invokes this method, and must not deallocate the handles
563		until the client disconnects from the bus or calls the ReleaseHandle
	575	until the client disconnects from the bus or calls the
	576	<tp:member-ref>ReleaseHandles</tp:member-ref>
564	577	method. Where the name refers to an entity that already has a handle
565	578	in this connection manager, this handle should be returned instead.
566	579	The handle number 0 must not be returned by the connection manager.

576	589	<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
577	590	<tp:docstring>
578	591	The given name is not a valid entity of the given type
	592	</tp:docstring>
	593	</tp:error>
	594	<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
	595	<tp:docstring>
	596	The given handle type is valid, but not implemented on this
	597	connection. For instance, a CM for a protocol that doesn't have
	598	chat rooms would not implement room handles.
579	599	</tp:docstring>
580	600	</tp:error>
581	601	</tp:possible-errors>

762	782	ambiguous. Connection manager implementations should reference count these
763	783	handles to determine if they are in use either by any active clients or any
764	784	open channels, and may deallocate them when this ceases to be true. Clients
765		may request handles of a given type and name with the RequestHandles
766		method, inspect the entity name of handles with the InspectHandles method,
767		keep handles from being released with HoldHandles, and notify that they are
768		no longer storing handles with ReleaseHandles.</p>
	785	may request handles of a given type and name with the
	786	<tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
	787	name of handles with the <tp:member-ref>InspectHandles</tp:member-ref>
	788	method, keep handles from being released with
	789	<tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
	790	longer storing handles with
	791	<tp:member-ref>ReleaseHandles</tp:member-ref>.</p>
769	792	</tp:docstring>
770	793
771	794	<tp:changed version="0.17.10">Previously, the account part of

-2

spec/Connection_Interface_Avatars.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Connection_Interface_Avatars" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2		<tp:copyright>Copyright (C) 2005-2007 Collabora Limited</tp:copyright>
3		<tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
	2	<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
	3	<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
4	4	<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or

-2

spec/Connection_Manager.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Connection_Manager" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2		<tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
3		<tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
	2	<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
	3	<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
4	4	<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or

+34

-22

spec/Media_Stream_Handler.xml less more

0	0	<?xml version="1.0" ?>
1	1	<node name="/Media_Stream_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2		<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
3		<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
	2	<tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
	3	<tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
4	4	<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
5	5	<tp:license xmlns="http://www.w3.org/1999/xhtml">
6	6	<p>This library is free software; you can redistribute it and/or

43	43
44	44	<tp:struct name="Media_Stream_Handler_Codec"
45	45	array-name="Media_Stream_Handler_Codec_List">
46		<tp:member type="u" name="Codec_ID"/>
47		<tp:member type="s" name="Name"/>
48		<tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type"/>
49		<tp:member type="u" name="Clock_Rate"/>
50		<tp:member type="u" name="Number_Of_Channels"/>
51		<tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map"/>
	46	<tp:docstring>
	47	Information about a codec supported by a client or a peer's client.
	48	</tp:docstring>
	49
	50	<tp:member type="u" name="Codec_ID">
	51	<tp:docstring>
	52	The codec's payload identifier, as per RFC 3551 (static or dynamic)
	53	</tp:docstring>
	54	</tp:member>
	55	<tp:member type="s" name="Name">
	56	<tp:docstring>The codec's name</tp:docstring>
	57	</tp:member>
	58	<tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type">
	59	<tp:docstring>Type of stream this codec supports</tp:docstring>
	60	</tp:member>
	61	<tp:member type="u" name="Clock_Rate">
	62	<tp:docstring>Sampling frequency in Hertz</tp:docstring>
	63	</tp:member>
	64	<tp:member type="u" name="Number_Of_Channels">
	65	<tp:docstring>Number of supported channels</tp:docstring>
	66	</tp:member>
	67	<tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map">
	68	<tp:docstring>Codec-specific optional parameters</tp:docstring>
	69	</tp:member>
52	70	</tp:struct>
53	71
54	72	<signal name="AddRemoteCandidate"

187	205	<arg direction="in" name="Codecs" type="a(usuuua{ss})"
188	206	tp:type="Media_Stream_Handler_Codec[]">
189	207	<tp:docstring>
190		As for SupportedCodecs.
	208	Locally-supported codecs.
191	209	</tp:docstring>
192	210	</arg>
193	211	<tp:docstring>

199	217	<method name="SetLocalCodecs" tp:name-for-bindings="Set_Local_Codecs">
200	218	<arg name="Codecs" type="a(usuuua{ss})" direction="in"
201	219	tp:type="Media_Stream_Handler_Codec[]">
202		<tp:docstring>Codecs in the same format as for
203		SupportedCodecs, which have the same semantics as the
204		local codecs passed to Ready</tp:docstring>
	220	<tp:docstring>
	221	Locally-supported codecs
	222	</tp:docstring>
205	223	</arg>
206	224	<tp:docstring>
207	225	Used to provide codecs after Ready(), so the media client can go

249	267	<signal name="SetRemoteCodecs" tp:name-for-bindings="Set_Remote_Codecs">
250	268	<arg name="Codecs" type="a(usuuua{ss})"
251	269	tp:type="Media_Stream_Handler_Codec[]">
252		<tp:docstring>As for SupportedCodecs</tp:docstring>
	270	<tp:docstring>
	271	Codecs supported by the remote peer.
	272	</tp:docstring>
253	273	</arg>
254	274	<tp:docstring>
255	275	Signal emitted when the connection manager wishes to inform the

300	320	<arg direction="in" name="Codecs" type="a(usuuua{ss})"
301	321	tp:type="Media_Stream_Handler_Codec[]">
302	322	<tp:docstring>
303		List of codec info structures, each containing:
304		<ul>
305		<li>ID of codec</li>
306		<li>Codec name</li>
307		<li>Media type</li>
308		<li>Clock rate of codec</li>
309		<li>Number of supported channels</li>
310		<li>String key-value pairs for supported optional parameters</li>
311		</ul>
	323	Locally supported codecs.
312	324	</tp:docstring>
313	325	</arg>
314	326	<tp:docstring>

-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.17.16</tp:version>
	5	<tp:version>0.17.17</tp:version>
6	6
7	7	<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
8	8	<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>