Commit 296d0120d7d0bdf3bff789c4763a4b8f67cee84b - telepathy-spec

+131

-0

ChangeLog less more

	0	Thu Apr 3 17:02:27 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	1	tagged telepathy-spec 0.17.3
	2
	3	Thu Apr 3 16:58:35 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	4	* Adjust whitespace in expected `make check` output
	5
	6	Thu Apr 3 16:04:33 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	7	* Revert marking Hold as API-stable - it's not ready right now
	8
	9	Thu Apr 3 15:28:18 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	10	* Prepare for a 0.17.3 release
	11
	12	Thu Apr 3 15:28:10 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	13	* Update NEWS
	14
	15	Thu Apr 3 15:20:50 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	16	* Mark Hold as stable
	17
	18	Thu Mar 20 16:26:44 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	19	* Say that contacts on hold do not receive media, not streams
	20
	21	Thu Mar 20 16:26:31 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	22	* Call_State_Held should be 4, this is a bitfield
	23
	24	Thu Mar 20 16:06:53 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	25	* StreamHandler: rename UnholdFailed to UnholdFailure to be consistent with Error
	26
	27	Thu Mar 20 16:05:32 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	28	* Simplify the Hold interface by only having it manipulate whether we have put the channel on hold: whether others have put us on hold is now a call-state
	29
	30	Thu Mar 20 16:05:06 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	31	* Indicate whether other people have put us on hold as a call state
	32
	33	Wed Mar 19 13:50:04 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	34	* StreamHandler: add SetStreamHeld, HoldState, UnholdFailure
	35
	36	Wed Mar 19 16:51:00 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	37	* Say Handle_Type_None instead of 0
	38
	39	Wed Mar 19 16:49:51 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	40	* Connection: tidy up wording of handle, handle type in NewChannel signal
	41
	42	Wed Mar 19 16:49:41 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	43	* Connection: re-wrap long line
	44
	45	Wed Mar 19 16:21:55 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	46	* Capabilities: add whitespace between children of <interface>
	47
	48	Wed Mar 19 16:02:20 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	49	* Capabilities: move docstring, Connection_Capability_Flags to the top (moving the latter inside the <interface> in the process). Rewrap the docstring
	50
	51	Wed Mar 19 17:09:26 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	52	* Update NEWS for merges of tp-spec-smcv-hold, tp-spec-smcv-unbonging
	53
	54	Tue Mar 18 14:56:23 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	55	* Remove never-implemented legacy interfaces from all.xml so they don't end up in the spec HTML
	56
	57	Tue Mar 18 16:06:28 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	58	* Update NEWS with merged changes so far in 0.17.3
	59
	60	Tue Mar 18 13:37:49 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	61	* Move Handle, Contact_Handle, etc. from generic-types to Connection (since that's their scope)
	62
	63	Tue Mar 18 13:36:16 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	64	* ConnectionManager: annotate bus name returned from RequestChannel as a DBus_Bus_Name
	65
	66	Tue Mar 18 13:35:52 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	67	* ConnectionManager: remove remnant of inline list of protocols in ListProtocols (it's now documented under Protocol)
	68
	69	Tue Mar 18 13:35:26 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	70	* ConnectionManager: add some whitespace
	71
	72	Tue Mar 18 13:52:50 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	73	* Clarify interaction between ListPendingMessages(clear=true) and AcknowledgePendingMessages
	74
	75	Tue Mar 18 13:52:38 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	76	* Clarify exact meaning of AcknowledgePendingMessages
	77
	78	Mon Mar 17 17:32:07 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	79	* Deprecate clear=true argument to ListPendingMessages
	80
	81	Mon Mar 17 17:31:39 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	82	* Let AcknowledgePendingMessages raise NetworkError (in case it's actually sending acks on the network)
	83
	84	Mon Mar 17 17:31:11 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	85	* In AcknowledgePendingMessages, mark up interpretation of InvalidArgument so it displays in the HTML
	86
	87	Mon Mar 17 17:28:09 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	88	* Clarify that AcknowledgePendingMessages is the way to send message acknowledgements, in protocols that can
	89
	90	Thu Mar 13 18:46:45 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	91	* Channel_Type_Text: explain the Action message type better
	92
	93	Wed Mar 12 17:38:37 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	94	* Amend Text interface so Send emits Sent at the time that it returns, and SendError can only be emitted later.
	95	This directly contradicts the interface docstring in previous spec versions
	96	(up to 0.17.2), but agrees with what Gabble and Haze implement in practice.
	97
	98	Wed Mar 12 11:47:21 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	99	* Allow arrays of mappings
	100
	101	Wed Mar 12 11:47:01 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	102	* Allow rationale to be mixed in with HTML in docstrings
	103
	104	Wed Mar 12 11:20:08 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	105	* Channel_Type_Text: clarify semantics of Send, Sent, SendError based on Rob's explanation
	106
	107	Tue Mar 18 13:28:22 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	108	* Connection.GetSelfHandle: annotate return type as Contact_Handle
	109
	110	Tue Mar 18 13:28:08 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	111	* Connection.GetProtocol: annotate return type as Protocol
	112
	113	Tue Mar 18 13:33:31 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	114	* Connection: remove some trailing whitespace
	115
	116	Wed Mar 12 11:27:05 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	117	* Remove unnecessary textual type annotations (now obsoleted by markup)
	118
	119	Wed Mar 12 11:26:30 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	120	* Annotate Pending_Text_Message::Unix_Timestamp as type Unix_Timestamp
	121
	122	Wed Mar 12 11:19:49 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	123	* Channel_Type_Text: we like the whitespace
	124
	125	Mon Feb 25 19:08:30 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	126	* Add some whitespace to Channel_Type_Contact_List
	127
	128	Thu Mar 6 14:51:47 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
	129	* Bump nano version
	130
0	131	Thu Mar 6 14:45:00 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
1	132	tagged telepathy-spec 0.17.2
2	133

+50

-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 "darcs changes" in Darcs
2	2	checkouts.
	3
	4	telepathy-spec 0.17.3 (2008-04-03)
	5	==================================
	6
	7	The "please hold" release.
	8
	9	API changes:
	10
	11	* Change documented semantics of SendError to match what Gabble and Haze
	12	have always done: Send emits Sent when the message is submitted, or no
	13	signal on failure, and SendError is emitted after Sent if an error is
	14	detected later
	15
	16	* Explain that AcknowledgePendingMessages is where "message received"
	17	acknowledgements should be sent
	18
	19	* Some interfaces we've never actually implemented, which we do not believe
	20	are necessarily very well thought-out, have been removed from the HTML
	21	specification to reduce confusion:
	22	- ContactInfo (XML vCards over D-Bus... what were we thinking?)
	23	- ContactSearch (server-side searches like XEP-0055)
	24	- Forwarding (an incomplete implementation of call-forwarding in telephony)
	25	- Privacy (a much more complex version of the 'block' API)
	26	- Transfer (transferring contacts between calls in telephony)
	27
	28	* Whether other people have put us on hold is now signalled as a call state
	29
	30	* The scope of the Hold interface has been reduced; it now only manipulates
	31	whether we have put the call on hold, not whether other people have put
	32	us on hold (note that the Hold interface is still considered experimental,
	33	and it's likely to change in the next release)
	34
	35	API additions:
	36
	37	* Media.StreamHandler now has a SetStreamHeld signal to ask streaming clients
	38	(stream-engine) to release or acquire the necessary resources for media
	39	streaming, and HoldState and UnholdFailure methods so the streaming client
	40	can indicate success or failure; these can be used to implement the
	41	Hold interface
	42
	43	Deprecations:
	44
	45	* Passing clear=TRUE to ListPendingMessages (the client cannot guarantee that
	46	the messages will actually be shown to the user or logged, if this is done)
	47
	48	Tools changes:
	49
	50	* Allow arrays of mappings
	51
	52	* Allow rationale to be interleaved with HTML in docstrings
3	53
4	54	telepathy-spec 0.17.2 (2008-03-06)
5	55	==================================

+8

-0

spec/Channel_Interface_Call_State.xml less more

91	91	in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).
92	92	</tp:docstring>
93	93	</tp:flag>
	94
	95	<tp:flag suffix="Held" value="4">
	96	<tp:docstring>
	97	The contact has placed the call on hold, and will not receive
	98	media from the local user or any other participants until they
	99	unhold the call again.
	100	</tp:docstring>
	101	</tp:flag>
94	102	</tp:flags>
95	103
96	104	</interface>

+11

-48

spec/Channel_Interface_Hold.xml less more

23	23	<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
24	24
25	25	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26		<p>Interface for channels where you or other members may put
27		the channel on hold. This only makes sense for channels where
	26	<p>Interface for channels where you may put the channel on hold.
	27	This only makes sense for channels where
28	28	you are streaming media to or from the members.</p>
29
30		<p>If you are placed on hold, this indicates that some or all members
31		of the channel will no longer be receiving media streams from you.
32		If the channel has the MediaSignalling interface, client applications
33		should stop sending media to all members of the channel.</p>
34
35		<p>Depending on the protocol, it might not be possible to tell that
36		you're on hold, in which case the connection manager should always
37		indicate that you're not on hold unless it finds out otherwise.</p>
38	29
39	30	<p>If you place a channel on hold, this indicates that you do not wish
40	31	to be sent media streams by any of its members and will be ignoring

45	36	another call).</p>
46	37	</tp:docstring>
47	38
48		<tp:enum name="Channel_Hold_State" type="u">
49		<tp:docstring>
50		The possible hold states of a call.
51		</tp:docstring>
52		<tp:enumvalue suffix="None" value="0">
	39	<method name="GetHoldState">
	40	<arg name="Held" direction="out" type="b">
53	41	<tp:docstring>
54		Neither the local user nor a remote member have placed the call on
55		hold.
56		</tp:docstring>
57		</tp:enumvalue>
58		<tp:enumvalue suffix="Local" value="1">
59		<tp:docstring>
60		The local user has put the call on hold.
61		</tp:docstring>
62		</tp:enumvalue>
63		<tp:enumvalue suffix="Remote" value="2">
64		<tp:docstring>
65		The call has been put on hold by a remote member.
66		</tp:docstring>
67		</tp:enumvalue>
68		<tp:enumvalue suffix="Both" value="3">
69		<tp:docstring>
70		The local user and a remote member have both placed the call
71		on hold.
72		</tp:docstring>
73		</tp:enumvalue>
74		</tp:enum>
75
76		<method name="GetHoldState">
77		<arg direction="out" type="u" tp:type="Channel_Hold_State">
78		<tp:docstring>
79		The channel's current hold state
	42	True if the local user has placed the channel on hold.
80	43	</tp:docstring>
81	44	</arg>
82	45	<tp:docstring>
83		Return the channel's current hold state.
	46	Return whether the local user has placed the channel on hold.
84	47	</tp:docstring>
85	48	</method>
86	49
87	50	<signal name="HoldStateChanged">
88		<arg name="state" type="u" tp:type="Channel_Hold_State">
	51	<arg name="Held" type="b">
89	52	<tp:docstring>
90		An integer representing the new hold state
	53	True if the local user has placed the channel on hold.
91	54	</tp:docstring>
92	55	</arg>
93	56	<tp:docstring>
94	57	Emitted to indicate that the hold state has changed for this channel.
95	58	This may occur as a consequence of you requesting a change with
96		RequestHold, or the state changing as a result of a request from a
97		remote member or another process.
	59	RequestHold, or the state changing as a result of a request from
	60	another process.
98	61	</tp:docstring>
99	62	</signal>
100	63
101	64	<method name="RequestHold">
102		<arg direction="in" name="hold" type="b">
	65	<arg direction="in" name="Hold" type="b">
103	66	<tp:docstring>
104	67	A boolean indicating whether or not the channel should be on hold
105	68	</tp:docstring>

+2

-0

spec/Channel_Type_Contact_List.xml less more

20	20	<interface name="org.freedesktop.Telepathy.Channel.Type.ContactList">
21	21	<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
22	22	<tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
	23
23	24	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
24	25	<p>A channel type for representing a list of people on the server which is
25	26	not used for communication. This is intended for use with the interface

63	64	server, so disconnecting from the server and reconnecting might cause
64	65	empty groups to vanish.</p>
65	66	</tp:docstring>
	67
66	68	</interface>
67	69	</node>
68	70	<!-- vim:set sw=2 sts=2 et ft=xml: -->

+51

-18

spec/Channel_Type_Text.xml less more

29	29	on the Text channel type. The arguments of the Received signal
30	30	also match this struct's signature.</tp:docstring>
31	31	<tp:member type="u" tp:type="Message_ID" name="Identifier"/>
32		<tp:member type="u" name="Unix_Timestamp"/>
	32	<tp:member type="u" tp:type="Unix_Timestamp" name="Unix_Timestamp"/>
33	33	<tp:member type="u" tp:type="Contact_Handle" name="Sender"/>
34	34	<tp:member type="u" tp:type="Channel_Text_Message_Type"
35	35	name="Message_Type"/>

46	46	<tp:docstring>
47	47	Inform the channel that you have handled messages by displaying them to
48	48	the user (or equivalent), so they can be removed from the pending queue.
	49	If appropriate, the connection manager SHOULD send an acknowledgement
	50	of receipt of the messages to the server when the client calls this
	51	method.
49	52	</tp:docstring>
50	53	<tp:possible-errors>
51	54	<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
52		A given message ID was not found, so no action was taken
	55	<tp:docstring>
	56	A given message ID was not found, so no action was taken
	57	</tp:docstring>
53	58	</tp:error>
	59	<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
54	60	</tp:possible-errors>
55	61	</method>
	62
56	63	<method name="GetMessageTypes">
57	64	<arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]">
58	65	<tp:docstring>

64	71	channel.
65	72	</tp:docstring>
66	73	</method>
	74
67	75	<method name="ListPendingMessages">
68	76	<arg direction="in" name="clear" type="b">
69	77	<tp:docstring>
70		If true, remove all messages from the queue
	78	If true, behave as if AcknowledgePendingMessages had also been
	79	called. Setting this to true is NOT RECOMMENDED for clients that
	80	have some sort of persistent message storage - clients SHOULD only
	81	acknowledge messages after they have actually stored them, which is
	82	impossible if this flag is true.
71	83	</tp:docstring>
72	84	</arg>
73	85	<arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]">

88	100	remove then all.
89	101	</tp:docstring>
90	102	</method>
	103
91	104	<signal name="LostMessage">
92	105	<tp:docstring>
93	106	This signal is emitted to indicate that an incoming message was

95	108	due to lack of memory.
96	109	</tp:docstring>
97	110	</signal>
	111
98	112	<signal name="Received">
99	113	<arg name="id" type="u">
100	114	<tp:docstring>

113	127	</arg>
114	128	<arg name="type" type="u" tp:type="Channel_Text_Message_Type">
115	129	<tp:docstring>
116		The type of the message (normal, action, notice, etc), from
117		ChannelTextMessageType
	130	The type of the message (normal, action, notice, etc.)
118	131	</tp:docstring>
119	132	</arg>
120	133	<arg name="flags" type="u" tp:type="Channel_Text_Message_Flags">
121	134	<tp:docstring>
122		A bitwise OR of the message flags as defined by ChannelTextMessageFlags
	135	A bitwise OR of the message flags
123	136	</tp:docstring>
124	137	</arg>
125	138	<arg name="text" type="s">

135	148	AcknowledgePendingMessage method.
136	149	</tp:docstring>
137	150	</signal>
	151
138	152	<method name="Send">
139	153	<arg direction="in" name="type" type="u" tp:type="Channel_Text_Message_Type">
140	154	<tp:docstring>
141		An integer indicating the type of the message, from
142		ChannelTextMessageType
	155	An integer indicating the type of the message
143	156	</tp:docstring>
144	157	</arg>
145	158	<arg direction="in" name="text" type="s">

148	161	</tp:docstring>
149	162	</arg>
150	163	<tp:docstring>
151		Request that a message be sent on this channel. The Sent signal will be
152		emitted when the message has been sent, and this method will return.
	164	Request that a message be sent on this channel. When the message has
	165	been submitted for delivery, this method will return and the Sent
	166	signal will be emitted. If the message cannot be submitted for
	167	delivery, the method returns an error and no signal is emitted.
153	168	</tp:docstring>
154	169	<tp:possible-errors>
155	170	<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>

158	173	<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
159	174	</tp:possible-errors>
160	175	</method>
	176
161	177	<tp:enum name="Channel_Text_Send_Error" type="u">
162	178	<tp:enumvalue suffix="Unknown" value="0">
163	179	<tp:docstring>

191	207	</tp:docstring>
192	208	</tp:enumvalue>
193	209	</tp:enum>
	210
194	211	<signal name="SendError">
195	212	<arg name="error" type="u">
196	213	<tp:docstring>

212	229	The text of the message
213	230	</tp:docstring>
214	231	</arg>
215		<tp:docstring>
216		Signals that an outgoing message has failed to send. The error
217		will be one of the values from ChannelTextSendError.
	232	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	233	<p>Signals that an outgoing message has failed to send. The error
	234	will be one of the values from ChannelTextSendError.</p>
	235
	236	<p>This signal should only be emitted for messages for which
	237	Sent has already been emitted and Send has already returned
	238	success.</p>
218	239	</tp:docstring>
219	240	</signal>
	241
220	242	<signal name="Sent">
221	243	<arg name="timestamp" type="u" tp:type="Unix_Timestamp">
222	244	<tp:docstring>

235	257	</tp:docstring>
236	258	</arg>
237	259	<tp:docstring>
238		Signals that a message has been sent on this channel.
	260	Signals that a message has been submitted for sending.
239	261	</tp:docstring>
240	262	</signal>
	263
241	264	<tp:enum name="Channel_Text_Message_Type" type="u">
242	265	<tp:enumvalue suffix="Normal" value="0">
243	266	<tp:docstring>

247	270	<tp:enumvalue suffix="Action" value="1">
248	271	<tp:docstring>
249	272	An action which might be presented to the user as
250		"* <sender> <action>"
	273	"* <sender> <action>", such as an IRC CTCP
	274	ACTION (typically selected by the "/me" command). For example, the
	275	text of the message might be "drinks more coffee".
251	276	</tp:docstring>
252	277	</tp:enumvalue>
253	278	<tp:enumvalue suffix="Notice" value="2">

261	286	</tp:docstring>
262	287	</tp:enumvalue>
263	288	</tp:enum>
	289
264	290	<tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u">
265	291	<tp:flag suffix="Truncated" value="1">
266	292	<tp:docstring>

269	295	</tp:docstring>
270	296	</tp:flag>
271	297	</tp:flags>
	298
272	299	<tp:property name="anonymous" type="b">
273	300	<tp:docstring>
274	301	True if people may join the channel without other members being made

344	371	A unix timestamp indicating when the subject was last modified.
345	372	</tp:docstring>
346	373	</tp:property>
	374
347	375	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
348	376	<p>A channel type for sending and receiving messages in plain text,
349		with no formatting.</p>
	377	with no formatting. In future specifications, channels for sending
	378	and receiving messages that can be reduced to plain text (i.e.
	379	formatted text) should also have this type.</p>
350	380
351	381	<p>When a message is received, an identifier is assigned and a
352	382	Received signal emitted, and the message placed in a pending queue

364	394	flags given in ChannelTextMessageFlags.</p>
365	395
366	396	<p>Sending messages can be requested using the Send method, which will
367		return and cause the Sent signal to be emitted when the message has
368		been delivered to the server, or SendError if there is a failure.</p>
	397	return successfully and emit the Sent signal when the message has
	398	been delivered to the server, or return an error with no signal
	399	emission if there is a failure. If a message is sent but delivery
	400	of the message later fails, this is indicated with the SendError
	401	signal.</p>
369	402
370	403	<p>On protocols where additional contacts cannot be invited into
371	404	a one-to-one chat, or where a one-to-one chat is just a series of

+40

-9

spec/Connection.xml less more

17	17
18	18	<p>You should have received a copy of the GNU Lesser General Public
19	19	License along with this library; if not, write to the Free Software
20		Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
	20	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
	21	USA.</p>
21	22	</tp:license>
22	23	<interface name="org.freedesktop.Telepathy.Connection">
23	24

33	34	</tp:member>
34	35	<tp:member type="u" tp:type="Handle_Type" name="Handle_Type">
35	36	<tp:docstring>The type of the handle that the channel communicates
36		with, or 0 if there is no associated handle</tp:docstring>
	37	with, or Handle_Type_None if there is no associated
	38	handle</tp:docstring>
37	39	</tp:member>
38	40	<tp:member type="u" tp:type="Handle" name="Handle">
39	41	<tp:docstring>The handle that the channel communicates with,

80	82	</method>
81	83
82	84	<method name="GetProtocol">
83		<arg direction="out" type="s">
	85	<arg direction="out" type="s" tp:type="Protocol">
84	86	<tp:docstring>
85	87	A string identifier for the protocol
86	88	</tp:docstring>

92	94	</method>
93	95
94	96	<method name="GetSelfHandle">
95		<arg direction="out" type="u">
	97	<arg direction="out" type="u" tp:type="Contact_Handle">
96	98	<tp:docstring>
97	99	An integer handle representing the user
98	100	</tp:docstring>

230	232
231	233	<arg name="handle_type" type="u" tp:type="Handle_Type">
232	234	<tp:docstring>
233		An integer representing the type of handle this channel communicates with, which is zero if no handle is specified
	235	An integer representing the type of handle this channel
	236	communicates with, or Handle_Type_None if no handle is specified
234	237	</tp:docstring>
235	238	</arg>
236	239
237	240	<arg name="handle" type="u" tp:type="Handle">
238	241	<tp:docstring>
239		A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel
	242	A handle indicating the specific contact, room or list this
	243	channel communicates with, or zero if no handle is specified
240	244	</tp:docstring>
241	245	</arg>
242	246

297	301
298	302	<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
299	303	<tp:docstring>
300		An integer representing the handle type, or zero if no handle is being specified
	304	An integer representing the handle type, or Handle_Type_None if
	305	no handle is specified
301	306	</tp:docstring>
302	307	</arg>
303	308
304	309	<arg direction="in" name="handle" type="u" tp:type="Handle">
305	310	<tp:docstring>
306	311	A nonzero integer handle representing a contact, room, list etc.
307		according to handle_type, or zero if the handle_type is zero
	312	according to handle_type, or zero if the handle_type is
	313	Handle_Type_None
308	314	</tp:docstring>
309	315	</arg>
310	316

405	411	</tp:docstring>
406	412	</tp:enumvalue>
407	413	</tp:enum>
	414
	415	<tp:simple-type name="Handle" type="u">
	416	<tp:docstring>An unsigned 32-bit integer representing a
	417	handle</tp:docstring>
	418	</tp:simple-type>
	419
	420	<tp:simple-type name="Contact_Handle" type="u">
	421	<tp:docstring>An unsigned 32-bit integer representing a handle of type
	422	Handle_Type_Contact</tp:docstring>
	423	</tp:simple-type>
	424
	425	<tp:simple-type name="Room_Handle" type="u">
	426	<tp:docstring>An unsigned 32-bit integer representing a handle of type
	427	Handle_Type_Room</tp:docstring>
	428	</tp:simple-type>
	429
	430	<tp:simple-type name="List_Handle" type="u">
	431	<tp:docstring>An unsigned 32-bit integer representing a handle of type
	432	Handle_Type_List</tp:docstring>
	433	</tp:simple-type>
	434
	435	<tp:simple-type name="Group_Handle" type="u">
	436	<tp:docstring>An unsigned 32-bit integer representing a handle of type
	437	Handle_Type_Group</tp:docstring>
	438	</tp:simple-type>
408	439
409	440	<method name="RequestHandles">
410	441	<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">

589	620
590	621	<p>Zero as a handle value is sometimes used as a "null" value to mean
591	622	the absence of a contact, room, etc.</p>
592
	623
593	624	<p>Handles have per-type uniqueness, meaning that
594	625	every (handle type, handle number) tuple is guaranteed to be unique within
595	626	a connection and that a handle alone (without its type) is meaningless or

+47

-38

spec/Connection_Interface_Capabilities.xml less more

19	19	</tp:license>
20	20	<interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities">
21	21	<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
	22
	23	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	24	<p>An interface for connections where it is possible to know what channel
	25	types may be requested before the request is made to the connection
	26	object. Each capability represents a commitment by the connection
	27	manager that it will ordinarily be able to create a channel when given
	28	a request with the given type and handle.</p>
	29
	30	<p>Capabilities can pertain to a certain contact handle, representing
	31	activities such as having a text chat or a voice call with the user, or
	32	can be on the connection itself (where the handle will be zero), where
	33	they represent the ability to create channels for chat rooms or
	34	activities such as searching and room listing. The activities are
	35	represented by the D-Bus interface name of the channel type for that
	36	activity.</p>
	37
	38	<p>The generic capability flags are defined by
	39	Connection_Capability_Flags.</p>
	40
	41	<p>In addition, channel types may have type specific capability flags of
	42	their own, which are described in the documentation for each channel
	43	type.</p>
	44
	45	<p>This interface also provides for user interfaces notifying the
	46	connection manager of what capabilities to advertise for the user. This
	47	is done by using the AdvertiseCapabilities method, and deals with the
	48	interface names of channel types and the type specific flags pertaining
	49	to them which are implemented by available client processes.</p>
	50	</tp:docstring>
	51
	52	<tp:flags name="Connection_Capability_Flags"
	53	value-prefix="Connection_Capability_Flag" type="u">
	54	<tp:flag suffix="Create" value="1">
	55	<tp:docstring>
	56	The given channel type and handle can be given to RequestChannel to
	57	create a new channel of this type.
	58	</tp:docstring>
	59	</tp:flag>
	60	<tp:flag suffix="Invite" value="2">
	61	<tp:docstring>
	62	The given contact can be invited to an existing channel of this type.
	63	</tp:docstring>
	64	</tp:flag>
	65	</tp:flags>
22	66
23	67	<tp:struct name="Capability_Pair" array-name="Capability_Pair_List">
24	68	<tp:docstring>A pair (channel type, type-specific flags) as passed to

102	146	<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
103	147	</tp:possible-errors>
104	148	</method>
	149
105	150	<signal name="CapabilitiesChanged">
106	151	<arg name="caps" type="a(usuuuu)" tp:type="Capability_Change[]">
107	152	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">

121	166	given handle, or on the connection itself if the handle is zero.
122	167	</tp:docstring>
123	168	</signal>
	169
124	170	<method name="GetCapabilities">
125	171	<arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
126	172	<tp:docstring>

153	199	<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
154	200	</tp:possible-errors>
155	201	</method>
156		<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
157		<p>An interface for connections where it is possible to know what channel
158		types may be requested before the request is made to the connection object.
159		Each capability represents a commitment by the connection manager that it
160		will ordinarily be able to create a channel when given a request with the
161		given type and handle.</p>
162
163		<p>Capabilities can pertain to a certain contact handle, representing
164		activities such as having a text chat or a voice call with the user, or can
165		be on the connection itself (where the handle will be zero), where they
166		represent the ability to create channels for chat rooms or activities such
167		as searching and room listing. The activities are represented by the D-Bus
168		interface name of the channel type for that activity.</p>
169
170		<p>The generic capability flags are defined by ConnectionCapabilityFlag.</p>
171
172		<p>In addition, channel types may have type specific capability flags of their
173		own, which are described in the documentation for each channel type.</p>
174
175		<p>This interface also provides for user interfaces notifying the connection
176		manager of what capabilities to advertise for the user. This is done by
177		using the AdvertiseCapabilities method, and deals with the interface names
178		of channel types and the type specific flags pertaining to them which are
179		implemented by available client processes.</p>
180		</tp:docstring>
	202
181	203	</interface>
182		<tp:flags name="Connection_Capability_Flags" value-prefix="Connection_Capability_Flag" type="u">
183		<tp:flag suffix="Create" value="1">
184		<tp:docstring>
185		The given channel type and handle can be given to RequestChannel to
186		create a new channel of this type.
187		</tp:docstring>
188		</tp:flag>
189		<tp:flag suffix="Invite" value="2">
190		<tp:docstring>
191		The given contact can be invited to an existing channel of this type.
192		</tp:docstring>
193		</tp:flag>
194		</tp:flags>
195	204	</node>
196	205	<!-- vim:set sw=2 sts=2 et ft=xml: -->

+8

-4

spec/Connection_Manager.xml less more

111	111	</tp:docstring>
112	112	</tp:flag>
113	113	</tp:flags>
	114
114	115	<method name="GetParameters">
115	116	<arg direction="in" name="proto" type="s" tp:type="Protocol">
116	117	<tp:docstring>

134	135	</tp:error>
135	136	</tp:possible-errors>
136	137	</method>
	138
137	139	<method name="ListProtocols">
138	140	<arg direction="out" type="as" tp:type="Protocol[]">
139	141	<tp:docstring>
140	142	A array of string protocol identifiers supported by this manager
141	143	</tp:docstring>
142	144	</arg>
143		<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
	145	<tp:docstring>
144	146	Get a list of protocol identifiers that are implemented by this
145		connection manager. The following well-known values should be used
146		when applicable:
	147	connection manager.
147	148	</tp:docstring>
148	149	</method>
	150
149	151	<signal name="NewConnection">
150	152	<arg name="bus_name" type="s" tp:type="DBus_Bus_Name">
151	153	<tp:docstring>

166	168	Emitted when a new Connection object is created.
167	169	</tp:docstring>
168	170	</signal>
	171
169	172	<method name="RequestConnection">
170	173	<arg direction="in" name="proto" type="s" tp:type="Protocol">
171	174	<tp:docstring>

178	181	A dictionary mapping parameter name to the variant boxed value
179	182	</tp:docstring>
180	183	</arg>
181		<arg direction="out" type="s">
	184	<arg direction="out" type="s" tp:type="DBus_Bus_Name">
182	185	<tp:docstring>
183	186	A D-Bus service name where the new Connection object can be found
184	187	</tp:docstring>

288	291	</tp:error>
289	292	</tp:possible-errors>
290	293	</method>
	294
291	295	<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
292	296	<p>A D-Bus service which allows connections to be created. The manager
293	297	processes are intended to be started by D-Bus service activation.</p>

+35

-0

spec/Media_Stream_Handler.xml less more

310	310	and those supported by the peer.
311	311	</tp:docstring>
312	312	</method>
	313
	314	<signal name="SetStreamHeld">
	315	<tp:docstring>
	316	Emitted when the connection manager wishes to place the stream on
	317	hold (so the streaming client should free hardware or software
	318	resources) or take the stream off hold (so the streaming client should
	319	reacquire the necessary resources).
	320	</tp:docstring>
	321	<arg name="Held" type="b">
	322	<tp:docstring>
	323	If true, the stream is to be placed on hold.
	324	</tp:docstring>
	325	</arg>
	326	</signal>
	327
	328	<method name="HoldState">
	329	<tp:docstring>
	330	Notify the connection manager that the stream's hold state has
	331	been changed successfully in response to SetStreamHeld.
	332	</tp:docstring>
	333	<arg direction="in" name="Held" type="b">
	334	<tp:docstring>
	335	If true, the stream is now on hold.
	336	</tp:docstring>
	337	</arg>
	338	</method>
	339
	340	<method name="UnholdFailure">
	341	<tp:docstring>
	342	Notify the connection manager that an attempt to reacquire the
	343	necessary hardware or software resources to unhold the stream,
	344	in response to SetStreamHeld, has failed.
	345	</tp:docstring>
	346	</method>
	347
313	348	<tp:docstring>
314	349	Handles signalling the information pertaining to a specific media stream.
315	350	A client should provide information to this handler as and when it is

+11

-6

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.2</tp:version>
	5	<tp:version>0.17.3</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>

29	29	<xi:include href="Connection_Interface_Aliasing.xml"/>
30	30	<xi:include href="Connection_Interface_Avatars.xml"/>
31	31	<xi:include href="Connection_Interface_Capabilities.xml"/>
32		<xi:include href="Connection_Interface_Contact_Info.xml"/>
33		<xi:include href="Connection_Interface_Forwarding.xml"/>
	32	<!-- Never implemented, is a terrible API
	33	<xi:include href="Connection_Interface_Contact_Info.xml"/> -->
	34	<!-- Never implemented, insufficient (needs conditions)
	35	<xi:include href="Connection_Interface_Forwarding.xml"/> -->
34	36	<xi:include href="Connection_Interface_Presence.xml"/>
35		<xi:include href="Connection_Interface_Privacy.xml"/>
	37	<!-- Never implemented, vague
	38	<xi:include href="Connection_Interface_Privacy.xml"/> -->
36	39	<xi:include href="Connection_Interface_Renaming.xml"/>
37	40
38	41	<xi:include href="Channel.xml"/>
39	42	<xi:include href="Channel_Type_Contact_List.xml"/>
40		<xi:include href="Channel_Type_Contact_Search.xml"/>
	43	<!-- Never implemented, can't be implemented with current dbus-glib, vague
	44	<xi:include href="Channel_Type_Contact_Search.xml"/> -->
41	45	<xi:include href="Channel_Type_Streamed_Media.xml"/>
42	46	<xi:include href="Channel_Type_Room_List.xml"/>
43	47	<xi:include href="Channel_Type_Text.xml"/>

50	54	<xi:include href="Channel_Interface_Group.xml"/>
51	55	<xi:include href="Channel_Interface_Hold.xml"/>
52	56	<xi:include href="Channel_Interface_Password.xml"/>
53		<xi:include href="Channel_Interface_Transfer.xml"/>
	57	<!-- Causes havoc, never implemented, unclear requirements
	58	<xi:include href="Channel_Interface_Transfer.xml"/> -->
54	59	<xi:include href="Channel_Interface_Media_Signalling.xml"/>
55	60
56	61	<xi:include href="Media_Session_Handler.xml"/>

+0

-24

spec/generic-types.xml less more

2	2
3	3	<tp:simple-type name="Unix_Timestamp" type="u">
4	4	<tp:docstring>An unsigned 32-bit integer representing time since 1970</tp:docstring>
5		</tp:simple-type>
6
7		<tp:simple-type name="Handle" type="u">
8		<tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring>
9		</tp:simple-type>
10
11		<tp:simple-type name="Contact_Handle" type="u">
12		<tp:docstring>An unsigned 32-bit integer representing a handle of type
13		Handle_Type_Contact</tp:docstring>
14		</tp:simple-type>
15
16		<tp:simple-type name="Room_Handle" type="u">
17		<tp:docstring>An unsigned 32-bit integer representing a handle of type
18		Handle_Type_Room</tp:docstring>
19		</tp:simple-type>
20
21		<tp:simple-type name="List_Handle" type="u">
22		<tp:docstring>An unsigned 32-bit integer representing a handle of type
23		Handle_Type_List</tp:docstring>
24		</tp:simple-type>
25
26		<tp:simple-type name="Group_Handle" type="u">
27		<tp:docstring>An unsigned 32-bit integer representing a handle of type
28		Handle_Type_Group</tp:docstring>
29	5	</tp:simple-type>
30	6
31	7	<tp:simple-type name="DBus_Bus_Name" type="s">

+3

-3

test/expected/spec.html.canon less more

137	137	org.freedesktop.DBus.Properties interface.</p><dl><dt><a id="org.freedesktop.Telepathy.SpecAutoGenTest.Introspective" name="org.freedesktop.Telepathy.SpecAutoGenTest.Introspective" shape="rect"><code>Introspective</code></a> - <code>b</code>, read-only</dt><dd>
138	138	True if the badger is introspective.
139	139
140
141		<div class="rationale">
	140	<div class="rationale">
142	141	Goths can be mistaken for badgers in poor lighting conditions.
143		</div></dd></dl><h2>Enumerated types:</h2><h3><a id="type-Adjective" name="type-Adjective" shape="rect">Adjective</a></h3>Adjectives which may be applied to a specification<dl><dt><code>Adjective_Leveraging = 0</code></dt><dd>
	142	</div>
	143	</dd></dl><h2>Enumerated types:</h2><h3><a id="type-Adjective" name="type-Adjective" shape="rect">Adjective</a></h3>Adjectives which may be applied to a specification<dl><dt><code>Adjective_Leveraging = 0</code></dt><dd>
144	144	Can leverage synergy
145	145	</dd><dt><code>Adjective_Synergistic = 1</code></dt><dd>
146	146	Can synergize with leverage

+10

-5

tools/doc-generator.xsl less more

39	39	</xsl:template>
40	40
41	41	<xsl:template match="tp:docstring">
42		<xsl:apply-templates select="text() \| html:*" mode="html"/>
43		<xsl:apply-templates select="tp:rationale"/>
44		</xsl:template>
45
46		<xsl:template match="tp:rationale">
	42	<xsl:apply-templates select="text() \| html:* \| tp:rationale" mode="html"/>
	43	</xsl:template>
	44
	45	<xsl:template match="tp:rationale" mode="html">
47	46	<div xmlns="http://www.w3.org/1999/xhtml" class="rationale">
48	47	<xsl:apply-templates select="node()" mode="html"/>
49	48	</div>

309	308	</h3>
310	309	<div class="docstring">
311	310	<xsl:apply-templates select="tp:docstring"/>
	311	<xsl:if test="string(@array-name) != ''">
	312	<p>In bindings that need a separate name, arrays of
	313	<xsl:value-of select="@name"/> should be called
	314	<xsl:value-of select="@array-name"/>.</p>
	315	</xsl:if>
312	316	</div>
313	317	<div>
314	318	<h4>Members</h4>

475	479	<xsl:when test="//tp:simple-type[@name=$tp-type]" />
476	480	<xsl:when test="//tp:simple-type[concat(@name, '[]')=$tp-type]" />
477	481	<xsl:when test="//tp:struct[concat(@name, '[]')=$tp-type][string(@array-name) != '']" />
	482	<xsl:when test="//tp:mapping[concat(@name, '[]')=$tp-type][string(@array-name) != '']" />
478	483	<xsl:when test="//tp:struct[@name=$tp-type]" />
479	484	<xsl:when test="//tp:enum[@name=$tp-type]" />
480	485	<xsl:when test="//tp:enum[concat(@name, '[]')=$tp-type]" />