Codebase list telepathy-spec / 79d2f44
Imported Upstream version 0.17.5 Simon McVittie 15 years ago
22 changed file(s) with 1685 addition(s) and 32 deletion(s). Raw diff Collapse all Expand all
+284
-0
ChangeLog less more
0 Wed May 21 16:28:12 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
1 tagged telepathy-spec 0.17.5
2
3 Wed May 21 16:27:58 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
4 * Fix expected test output for additions to the stylesheet
5
6 Wed May 21 16:18:12 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
7 * Version 0.17.5
8
9 Wed May 21 16:16:37 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
10 * Update NEWS with Messages etc. API
11
12 Wed May 21 16:02:45 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
13 * Remove rationale that no longer applies from "ignore parts with no type", but keep the requirement for possible future expansion
14
15 Wed May 21 16:02:28 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
16 * Upgrade inability to send delivery reports via SendMessage from a SHOULD NOT to a MUST NOT
17
18 Wed May 21 16:01:34 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
19 * Don't let the CM generate its own human-readable delivery reports - we don't want to encourage that sort of behaviour, and Haze can stay spec-incompliant for now until we work out a better way
20
21 Wed May 21 11:07:55 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
22 * Add reason to SendDeliveryReport as per Rob's review
23
24 Tue May 20 09:58:38 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
25 * Forbid sending delivery reports using SendMessage
26
27 Tue May 20 09:57:52 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
28 * Add examples to DeliveryReporting
29
30 Tue May 20 09:57:26 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
31 * Clarify what complexity I'm talking about when saying that delivery-echo should include all possible content
32
33 Mon May 19 15:23:50 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
34 * Improve wording of GetPendingMessageContent
35
36 Tue May 6 13:22:38 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
37 * Fix unbalanced element
38
39 Tue May 6 13:21:46 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
40 * DeliveryReporting: adapt for assumption that the first Message_Part is purely a header
41
42 Tue May 6 13:21:22 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
43 * Add error conditions to GetPendingMessageContent (assumes header refactoring)
44
45 Tue May 6 13:21:02 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
46 * Add error conditions to SendMessage
47
48 Tue May 6 13:20:33 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
49 * Give headers their own part, rather than merging them into part 0
50
51 Tue May 6 11:14:39 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
52 * Add a FIXME comment: perhaps PendingMessagesRemoved should be on the Text interface?
53
54 Tue May 6 11:14:35 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
55 * Adjust DeliveryReporting spec for Messages refactoring
56
57 Tue May 6 11:14:14 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
58 * Adjust rationale for Delivery_Reporting_Support_Flags
59
60 Tue May 6 11:12:53 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
61 * Redefine Messages spec so the first content part also contains "headers" for the entire message
62
63 Tue May 6 11:12:29 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
64 * Add rationale for the message part support flags being flags when an enum would currently be enough
65
66 Tue May 6 10:33:04 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
67 * Explicitly say that success from Messages.SendMessage must emit Text.Sent
68
69 Tue May 6 10:32:43 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
70 * Move comment about lack of definition of "sufficiently small to include" to an XML comment
71
72 Tue Apr 22 11:10:16 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
73 * Messages: stop referring to the MessageParts interface (now renamed to Messages)
74
75 Tue Apr 22 11:09:20 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
76 * HTML: reference the Messages interface, not the MessageParts interface
77
78 Tue Apr 22 11:09:00 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
79 * DeliveryReporting: set type of Status argument to SendDeliveryReport
80
81 Mon Apr 21 15:59:34 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
82 * Mark Non_Text_Content docstring as XHTML
83
84 Mon Apr 21 13:38:21 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
85 * DeliveryReporting: update for current Messages spec
86
87 * Deliver reports via the Messages interface, so that minimal Text clients
88 will at least signal "unknown message type" and ack them
89 * Add capability discovery for whether messages can be positively or negatively
90 acknowledged
91 * Add the ability to send positive or negative acknowledgement
92
93 Mon Apr 21 13:37:23 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
94 * Text: tighten up wording of Non_Text_Content
95
96 Mon Apr 21 13:36:52 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
97 * Text: add Channel_Text_Message_Type_Delivery_Report
98
99 Mon Apr 21 13:36:30 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
100 * Text: clarify handling of unknown message types
101
102 Mon Apr 21 13:36:01 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
103 * Text: annotate Channel_Text_Message_Type with a basic docstring
104
105 Mon Apr 21 13:35:25 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
106 * Messages: recommend 'interface' key in message parts for interface-specific parts
107
108 Mon Apr 21 13:35:10 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
109 * Messages: allow the sending contact to be 0 (DeliveryReporting might need this)
110
111 Wed Apr 16 12:44:34 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
112 * Change rationale for PendingMessagesRemoved
113
114 Wed Apr 16 12:39:25 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
115 * Revert a change to Channel.Type.Text: AcknowledgePendingMessages should only affect local state, and should not send a successful delivery report
116
117 This is because it turns out to be really tricky to specify
118 AcknowledgePendingMessages correctly if it can "partially fail". Instead, I
119 plan to add SendDeliveryReport functionality to the DeliveryReporting interface.
120
121 Tue Apr 15 18:36:23 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
122 * Add PendingMessagesRemoved signal
123
124 Tue Apr 15 18:35:08 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
125 * Move Message_Part well-known keys list into main docstring, rather than Key docstring (necessary if we decide to special-case the first dict to be "headers")
126
127 Tue Apr 15 18:34:48 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
128 * Rename Pending_Multiple_Part_Message to just Pending_Message
129
130 Tue Apr 15 18:34:37 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
131 * Re-word Messages spec
132
133 Tue Apr 15 18:33:45 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
134 * Rewrap long line
135
136 Tue Apr 15 18:33:39 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
137 * Rename Channel_Interface_Message_Parts to Channel_Interface_Messages
138
139 Fri Apr 11 14:21:04 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
140 * HTML requires MessageParts
141
142 Fri Apr 11 14:19:29 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
143 * Add a placeholder version of Channel.Interface.HTML to indicate how formatted text will work
144
145 Thu Apr 10 20:37:31 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
146 * Bring message-with-photo example up to date
147
148 Thu Apr 10 20:26:53 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
149 * Add .DRAFT to name of DeliveryReporting interface
150
151 Thu Apr 10 20:22:22 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
152 * Use 'alternative' instead of 'identifier' to group alternatives, and give it a dual purpose as the Content-ID of the (virtual) message/alternative structure
153 This is for compatibility with MIME (we might as well be compatible).
154
155 Thu Apr 10 20:20:54 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
156 * Add Channel_Text_Message_Flag_Non_Text_Content, which indicates that the received message in a Text channel has had non-text content removed
157 This may be useful for minimal clients to interoperate with MessageParts
158 implementations - at least they can tell the user something is missing, even if
159 they can't tell what.
160
161 Thu Apr 10 20:20:41 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
162 * Document Message_ID a bit
163
164 Thu Apr 10 20:16:11 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
165 * Emit Text.Sent, Text.Received even for non-text messages on Channel.Interface.MessageParts.
166 This means that Text-only clients can acknowledge messages received with no
167 text content (they will probably appear empty, but this is about the best
168 we can do - if you've received the non-textual message, then capability
169 advertisement has already failed).
170
171 This avoids a problem with the previous draft, where non-Text messages
172 (messages on the MessageParts interface that have no text/plain content and so
173 were not signalled on the Text channel) could never be acknowledged or removed
174 by Text-only clients, and would build up in memory indefinitely.
175
176 Thu Apr 10 13:54:47 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
177 * Add .DRAFT to MessageParts interface name
178
179 Thu Apr 10 13:54:17 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
180 * MessageParts: document flaw in current design
181
182 Thu Apr 10 13:54:07 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
183 * DeliveryReporting: add 'recipient' well-known key
184
185 Tue Apr 8 18:20:02 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
186 * Add message ID to received multi-part messages
187
188 Mon Apr 7 17:46:05 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
189 * Add missing value to delivery report mapping
190
191 Tue Mar 18 14:47:23 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
192 * MessageParts: make it clearer that clients listening for MessageSent and MessageReceived (where supported) should ignore Sent and Received
193
194 Tue Mar 18 14:46:58 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
195 * DeliveryReporting: make it clearer that clients listening for DeliveryReport (where supported) should ignore SendError
196
197 Mon Mar 17 17:50:57 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
198 * Remove stray references to more previous names for DeliveryReporting (DeliveryReports, DeliveryNotification)
199
200 Mon Mar 17 17:49:41 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
201 * Remove a couple of stray references to MessageStatus (a previous name for the DeliveryReporting interface)
202
203 Mon Mar 17 17:38:13 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
204 * Add the actual delivery reporting to DeliveryReporting
205
206 Mon Mar 17 17:37:50 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
207 * Add types for DeliveryReporting
208
209 Mon Mar 17 17:37:02 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
210 * Add skeletal DeliveryReporting interface
211
212 Mon Mar 17 17:36:04 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
213 * MessageParts: add API to receive messages
214
215 Mon Mar 17 17:35:21 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
216 * MessageParts: add API to send messages
217
218 Mon Mar 17 17:34:23 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
219 * MessageParts: add Multiple_Part_Message struct
220
221 Mon Mar 17 17:33:41 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
222 * MessageParts: indicate level of support for attachments
223
224 Mon Mar 17 17:32:28 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
225 * Add skeleton of MessageParts interface (basically Channel.Type.Text 2.0)
226
227 Wed May 21 15:58:35 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
228 * Update NEWS
229
230 Wed May 21 11:33:08 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
231 * Connection: talk about incoming calls, not incoming channels
232
233 Tue May 20 14:56:07 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
234 * doc-generator: remove support for <tp:since>, we already had <tp:added> that didn't do anything. Add <tp:changed> too
235
236 Tue May 20 14:55:59 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
237 * StreamHandler: add version annotations
238
239 Tue May 20 14:55:40 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
240 * ConnectionManager: add version annotations
241
242 Tue May 20 14:55:29 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
243 * Presence type Busy was new in 0.17.0
244
245 Tue May 20 14:55:19 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
246 * Text: improve change annotations
247
248 Tue May 20 14:55:07 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
249 * StreamedMedia: improve change annotation
250
251 Tue May 20 14:54:58 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
252 * Hold was first stable in 0.17.4
253
254 Tue May 20 14:54:27 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
255 * CallState was added in 0.17.2
256
257 Tue May 20 14:54:18 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
258 * CallMerging was added in 0.17.1
259
260 Tue May 20 14:53:56 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
261 * Reformat ChannelHandler interface, mark as new in 0.17.0
262
263 Tue May 20 14:53:36 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
264 * AccountManager was added in 0.17.2
265
266 Tue May 20 14:52:35 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
267 * Account was added in 0.17.2
268
269 Tue May 20 12:26:03 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
270 * Add support for tp:since and tp:deprecated (at the same levels as tp:docstring)
271
272 Thu May 15 12:58:30 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
273 * Channel.Interface.Group: whitespace, whitespace, whitespace!
274
275 Wed Mar 19 16:58:38 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
276 * Clarify suppress_handler to make it completely clear that it does not mean incoming vs outgoing
277
278 Thu Feb 21 18:16:27 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
279 * Add a Server property to RoomList
280
281 Fri May 9 12:31:49 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
282 * Nano version 0.17.4.1
283
0284 Fri May 9 11:26:40 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk>
1285 tagged telepathy-spec 0.17.4
2286
+24
-0
NEWS less more
00 This file contains the same edited highlights as the announcement emails.
11 For full details, see the ChangeLog in tarballs, or "darcs changes" in Darcs
22 checkouts.
3
4 telepathy-spec 0.17.5 (2008-05-21)
5 ==================================
6
7 The "Channel.Type.Text 2.0 (beta)" release.
8
9 New experimental APIs:
10
11 * Channel.Interface.Messages: extensible version of Text with support for
12 MIME-style attachments, alternatives, etc. and extensible metadata
13 * Channel.Interface.HTML: a brief sketch of how we intend to use Messages
14 to get formatted message support in future (unfinished!)
15 * Channel.Interface.DeliveryReporting: an enhanced version of the Text
16 interface's rather simplistic SendError signal
17
18 Clarifications:
19
20 * Make it completely clear that suppress_handler does NOT mean incoming vs
21 outgoing channels
22 * Annotate a lot of changes with the version in which they were introduced
23
24 Tools changes:
25
26 * Show when things were added/changed/deprecated in the HTML spec
327
428 telepathy-spec 0.17.4 (2008-05-09)
529 ==================================
+2
-0
spec/Account.xml less more
7171
7272 </tp:docstring>
7373
74 <tp:added version="0.17.2"/>
75
7476 <!-- Missing functionality compared with NMC 4.x account + profile,
7577 apart from as listed above:
7678
+1
-0
spec/Account_Manager.xml less more
2929 /org/freedesktop/Telepathy/AccountManager object with the
3030 AccountManager interface.</p>
3131 </tp:docstring>
32 <tp:added version="0.17.2"/>
3233
3334 <!-- Missing functionality compared with NMC 4.x:
3435 * look up accounts by conditions (can be done client-side, less
+19
-8
spec/Channel_Handler.xml less more
00 <?xml version="1.0" ?>
11 <node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright>Copyright (C) 2007 Collabora Limited</tp:copyright>
2 <tp:copyright>Copyright (C) 2007-2008 Collabora Limited</tp:copyright>
33 <tp:license xmlns="http://www.w3.org/1999/xhtml">
44 <p>This library is free software; you can redistribute it and/or
55 modify it under the terms of the GNU Lesser General Public
1717 </tp:license>
1818 <interface name="org.freedesktop.Telepathy.ChannelHandler">
1919
20 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
21 <p>An interface exported by client applications which are able to
22 handle incoming channels.</p>
23 </tp:docstring>
24 <tp:added version="0.17.0"/>
25
2026 <method name="HandleChannel">
27 <tp:docstring>
28 Called when a channel handler should handle a new channel.
29 </tp:docstring>
30 <tp:added version="0.17.0"/>
31
2132 <arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name">
2233 <tp:docstring>
2334 The bus name of the connection and channel
2435 </tp:docstring>
2536 </arg>
37
2638 <arg direction="in" type="o" name="Connection">
2739 <tp:docstring>
2840 The object-path of the connection that owns the channel
2941 </tp:docstring>
3042 </arg>
43
3144 <arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type">
3245 <tp:docstring>
3346 The channel type
3447 </tp:docstring>
3548 </arg>
49
3650 <arg direction="in" type="o" name="Channel">
3751 <tp:docstring>
3852 The object-path of the channel
3953 </tp:docstring>
4054 </arg>
55
4156 <arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type">
4257 <tp:docstring>The type of the handle that the channel communicates
4358 with, or 0 if there is no associated handle</tp:docstring>
4459 </arg>
60
4561 <arg direction="in" type="u" tp:type="Handle" name="Handle">
4662 <tp:docstring>The handle that the channel communicates with,
4763 or 0 if there is no associated handle</tp:docstring>
4864 </arg>
49 <tp:docstring>
50 Called when a channel handler should handle a new channel.
51 </tp:docstring>
65
5266 <!-- FIXME: possible errors? -->
5367 </method>
54 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
55 <p>An interface exported by client applications which are able to
56 handle incoming channels.</p>
57 </tp:docstring>
68
5869 </interface>
5970 </node>
6071 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+1
-0
spec/Channel_Interface_Call_Merging.xml less more
2121 <interface name="org.freedesktop.Telepathy.Channel.Interface.CallMerging"
2222 tp:causes-havoc='not yet API-stable'>
2323 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
24 <tp:added version="0.17.1"/>
2425
2526 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
2627 <p>Interface for streamed media channels that can be merged and split
+1
-0
spec/Channel_Interface_Call_State.xml less more
2626 implementations are not guaranteed to generate status 180 Ringing,
2727 so a call can be accepted without the Ringing flag ever having been set).
2828 </tp:docstring>
29 <tp:added version="0.17.2"/>
2930
3031 <method name="GetCallStates">
3132 <tp:docstring>
+440
-0
spec/Channel_Interface_Delivery_Reporting.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Channel_Interface_Delivery_Reporting"
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>
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 02110-1301, USA.</p>
19 </tp:license>
20 <interface
21 name="org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting.DRAFT">
22 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
23 <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
24
25 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26 <p>This interface extends the Text and Messages interfaces with improved
27 sent-message status reporting.</p>
28
29 <p>This interface replaces Text.SendError, adding support for protocols
30 where the message content is not echoed back to the sender on
31 failure. It also adds support for receiving positive
32 acknowledgements, and uses the Messages queue for state-recovery
33 (ensuring that incoming delivery reports are not lost if there is not
34 currently a process handling them).</p>
35
36 <p>If this interface and the Messages interface are both present,
37 clients that support it SHOULD listen for the MessageReceived signal
38 to get delivery reports, and ignore the SendError signal on the Text
39 interface.</p>
40
41 <p>Delivery reports appear as messages of type
42 Channel_Text_Message_Type_Delivery_Report in the Text and Messages
43 interfaces. The message in the Text interface SHOULD have the
44 Non_Text_Content flag.</p>
45
46 <p>Whenever a message of type Channel_Text_Message_Type_Delivery_Report
47 is signalled for a delivery error report, Channel.Type.Text.SendError
48 SHOULD also be emitted; whenever Channel.Type.Text.SendError is
49 emitted by a channel which supports this interface, a message of type
50 Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>
51
52 <p>The corresponding message in the Messages interface MUST contain
53 "headers" for the delivery report, as specified below, in its
54 first Message_Part.</p>
55
56 <dl>
57 <dt>interface (s - DBus_Interface, as defined in the Messages
58 interface)</dt>
59 <dd>MUST be the name of this interface.</dd>
60
61 <dt>message-sender (u - Contact_Handle, as defined in the Messages
62 interface)</dt>
63 <dd>MUST be the intended recipient of the original message, if
64 available (zero or omitted otherwise), even if the delivery report
65 actually came from an intermediate server.</dd>
66
67 <dt>message-type (u - Channel_Text_Message_Type, as defined in the
68 Messages interface)</dt>
69 <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
70
71 <dt>delivery-status (u - Delivery_Status)</dt>
72 <dd>The status of the message. All delivery reports MUST contain
73 this key in the first Message_Part.</dd>
74
75 <dt>delivery-token (s - Sent_Message_Token)</dt>
76
77 <dd>
78 <p>An identifier for the message to which this delivery report
79 refers. MUST NOT be an empty string. Omitted if not
80 available.</p>
81
82 <p>Clients may match this against the token produced by the
83 SendMessage method and MessageSent signal on the Messages
84 interface. A status report with no token could match any sent
85 message, and a sent message with an empty token could match
86 any status report. If multiple sent messages match, clients
87 SHOULD use some reasonable heuristic.</p>
88
89 <tp:rationale>
90 In an ideal world, we could unambiguously match reports
91 against messages; however, deployed protocols are not ideal,
92 and not all reports and messages can be matched.
93 </tp:rationale>
94 </dd>
95
96 <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
97 <dd>
98 The reason for the failure. MUST be omitted if this was a
99 successful delivery; SHOULD be omitted if it would be
100 Channel_Text_Send_Error_Unknown.
101 </dd>
102
103 <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
104 <dd>
105 <p>The message content, as defined by the Messages interface.
106 Omitted if no content is available. Content MAY have been
107 truncated, message parts MAY have been removed, and message
108 parts MAY have had their content removed (i.e. the message part
109 metadata is present, but the 'content' key is not).</p>
110
111 <tp:rationale>
112 Some protocols, like XMPP, echo the failing message back to
113 the sender. This is sometimes the only way to match it
114 against the sent message, so we include it here.
115 </tp:rationale>
116
117 <p>Unlike in the Messages interface, content not visible
118 in the value for this key cannot be retrieved by another
119 means, so the connection manager SHOULD be more
120 aggressive about including (possibly truncated) message
121 content in the 'content' key.</p>
122
123 <tp:rationale>
124 The Messages interface needs to allow all content to be
125 retrieved, but in this interface, the content we provide is
126 merely a hint; so some is better than none, and it doesn't
127 seem worth providing an API as complex as Messages'
128 GetPendingMessageContent for the echoed message.
129 </tp:rationale>
130 </dd>
131
132 </dl>
133
134 <p>The second and subsequent Message_Part dictionaries, if present,
135 are a human-readable report from the IM service.</p>
136
137 <p>It is an error for this interface to appear on channels of type
138 other than Text, or on Text channels without the Messages interface.
139 Clients MUST recover from this error by ignoring the presence
140 of the DeliveryReporting interface.</p>
141
142 <p>Some example delivery reports in a Python-like syntax (in which
143 arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
144 follow.</p>
145
146 <dl>
147 <dt>A minimal delivery report indicating permanent failure of the
148 sent message whose token was
149 <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
150 reason</dt>
151 <dd><pre>
152 [{
153 # header
154 'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
155 'message-sender': 123,
156 'message-type': Channel_Text_Message_Type_Delivery_Report,
157 'delivery-status': Delivery_Status_Permanently_Failed,
158 'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
159 }
160 # no body
161 ]
162 </pre></dd>
163
164 <dt>A delivery report where the failed message is echoed back to the
165 sender rather than being referenced by ID, and the failure reason
166 is that this protocol cannot send messages to offline contacts
167 such as the contact with handle 123</dt>
168 <dd><pre>
169 [{ # header
170 'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
171 'message-sender': 123,
172 'message-type': Channel_Text_Message_Type_Delivery_Report,
173 'delivery-status': Delivery_Status_Temporarily_Failed,
174 'delivery-error': Channel_Text_Send_Error_Offline,
175 'delivery-echo':
176 [{ # header of original message
177 'message-sender': 1,
178 'message-sent': 1210067943,
179 },
180 { # body of original message
181 'type': 'text/plain',
182 'content': 'Hello, world!',
183 }]
184 ],
185
186 # no body
187 ]
188 </pre></dd>
189
190 <dt>A maximally complex delivery report: the server reports a bilingual
191 human-readable failure message because the user sent a message
192 "Hello, world!" with token
193 <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
194 with handle 123, but that handle represents a contact who does not
195 actually exist</dt>
196 <dd><pre>
197 [{ # header
198 'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
199 'message-sender': 123,
200 'message-type': Channel_Text_Message_Type_Delivery_Report,
201 'delivery-status': Delivery_Status_Permanently_Failed,
202 'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
203 'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
204 'delivery-echo':
205 [{ # header of original message
206 'message-sender': 1,
207 'message-sent': 1210067943,
208 },
209 { # body of original message
210 'type': 'text/plain',
211 'content': 'Hello, world!',
212 }]
213 ],
214 },
215 { # message from server (alternative in English)
216 'alternative': '404',
217 'type': 'text/plain',
218 'lang': 'en',
219 'content': 'I have no contact with that name',
220 },
221 { # message from server (alternative in German)
222 'alternative': '404'.
223 'type': 'text/plain',
224 'lang': 'de',
225 'content', 'Ich habe keinen Kontakt mit diesem Namen',
226 }
227 ]
228 </pre></dd>
229
230 <dt>A minimal delivery report indicating successful delivery
231 of the sent message whose token was
232 <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
233 <dd><pre>
234 [{
235 # header
236 'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
237 'message-sender': 123,
238 'message-type': Channel_Text_Message_Type_Delivery_Report,
239 'delivery-status': Delivery_Status_Delivered,
240 'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
241 }
242 # no body
243 ]
244 </pre></dd>
245
246 </dl>
247 </tp:docstring>
248
249 <tp:enum name="Delivery_Status" value-prefix="Delivery_Status">
250 <tp:docstring>
251 <p>The status of a message as indicated by a delivery report.</p>
252
253 <p>If this enum is extended in future specifications, this should
254 only be to add new, non-overlapping conditions (i.e. all failures
255 should still be signalled as either Temporarily_Failed
256 or Permanently_Failed). If additional detail is required (e.g.
257 distinguishing between the various types of permanent failure) this
258 will be done using additional keys in the Message_Part.</p>
259 </tp:docstring>
260
261 <tp:enumvalue suffix="Unknown" value="0">
262 <tp:docstring>
263 The message's disposition is unknown.
264 Clients SHOULD consider all messages to have status
265 Delivery_Status_Unknown unless otherwise specified; connection
266 managers SHOULD NOT signal this delivery status explicitly.
267 </tp:docstring>
268 </tp:enumvalue>
269
270 <tp:enumvalue suffix="Delivered" value="1">
271 <tp:docstring>
272 The message has been delivered to the intended recipient.
273 </tp:docstring>
274 </tp:enumvalue>
275
276 <tp:enumvalue suffix="Temporarily_Failed" value="2">
277 <tp:docstring>
278 Delivery of the message has failed. Clients SHOULD notify the user,
279 but MAY automatically try sending another copy of the message.
280
281 <tp:rationale>
282 Similar to errors with type="wait" in XMPP; analogous to
283 4xx errors in SMTP.
284 </tp:rationale>
285 </tp:docstring>
286 </tp:enumvalue>
287
288 <tp:enumvalue suffix="Permanently_Failed" value="3">
289 <tp:docstring>
290 Delivery of the message has failed. Clients SHOULD NOT try again
291 unless by specific user action. If the user does not modify the
292 message or alter configuration before re-sending, this error is
293 likely to happen again.
294
295 <tp:rationale>
296 Similar to errors with type="cancel", type="modify"
297 or type="auth" in XMPP; analogous to 5xx errors in SMTP.
298 </tp:rationale>
299 </tp:docstring>
300 </tp:enumvalue>
301 </tp:enum>
302
303 <tp:flags name="Delivery_Reporting_Support_Flags"
304 value-prefix="Delivery_Reporting_Support_Flag">
305 <tp:docstring>
306 Flags indicating the level of support for delivery reporting on this
307 channel. Any future flags added to this set will conform to the
308 convention that the presence of an extra flag implies that
309 more operations will succeed.
310 </tp:docstring>
311
312 <tp:flag suffix="Receive_Failures" value="1">
313 <tp:docstring>
314 Clients MAY expect to receive negative delivery reports if
315 Message_Sending_Flag_Report_Delivery is specified when sending.
316
317 <tp:rationale>
318 If senders want delivery reports, they should ask for them.
319 If they don't want delivery reports, they can just ignore them,
320 so there's no need to have capability discovery for what will
321 happen if a delivery report isn't requested.
322 </tp:rationale>
323 </tp:docstring>
324 </tp:flag>
325
326 <tp:flag suffix="Receive_Successes" value="2">
327 <tp:docstring>
328 Clients MAY expect to receive positive delivery reports if
329 Message_Sending_Flag_Report_Delivery is specified when sending.
330
331 <tp:rationale>
332 Same rationale as Receive_Failures.
333 </tp:rationale>
334 </tp:docstring>
335 </tp:flag>
336
337 <tp:flag suffix="Send_Failures" value="4">
338 <tp:docstring>
339 Clients MAY expect that sending a negative delivery report will
340 succeed, and will actually get a message to the sender.
341 </tp:docstring>
342 </tp:flag>
343
344 <tp:flag suffix="Send_Successes" value="8">
345 <tp:docstring>
346 Clients MAY expect that sending a positive delivery report will
347 succeed, and will actually get a message to the sender.
348 </tp:docstring>
349 </tp:flag>
350
351 </tp:flags>
352
353 <property name="DeliveryReportingSupport" access="read"
354 tp:type="Delivery_Reporting_Support_Flags" type="u">
355 <tp:docstring>
356 A bitfield indicating features supported by this channel.
357 </tp:docstring>
358 </property>
359
360 <method name="SendDeliveryReport">
361 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
362 <p>Request that a delivery report is sent for the specified pending
363 incoming message. Delivery reports cannot currently be sent for
364 messages that have already been acknowledged.</p>
365
366 <tp:rationale>
367 <p>The only use-case I can see for delivery reports on non-pending
368 messages is a "read receipt" like in email's RFC 3798. Delivery
369 reports on non-pending messages will also need a more complex
370 API.</p>
371
372 <p>If they turn out to be needed, we can add a method like
373 SendDeliveryReportByContent(aa{sv}: message) and add a flag to
374 Delivery_Reporting_Support_Flags indicating that this method is
375 implemented.</p>
376 </tp:rationale>
377
378 <p>Clients SHOULD NOT attempt to send delivery reports that are
379 not indicated to be supported using the DeliveryReportingSupport
380 property.</p>
381
382 <p>Clients MUST NOT attempt to send delivery reports using the
383 SendMessage method in the Messages API, and connection managers
384 MUST NOT allow this to be done.</p>
385 </tp:docstring>
386
387 <arg name="Messages" type="au" tp:type="Message_ID[]" direction="in">
388 <tp:docstring>
389 The IDs of one or more unacknowledged messages.
390 </tp:docstring>
391 </arg>
392
393 <arg name="Status" direction="in" type="u" tp:type="Delivery_Status">
394 <tp:docstring>
395 The status to be reported.
396 </tp:docstring>
397 </arg>
398
399 <arg name="Reason" direction="in" type="u"
400 tp:type="Channel_Text_Send_Error">
401 <tp:docstring>
402 If the status to be reported is a failure, the reason for that
403 failure. If the status to be reported is not an error, this MUST be
404 Channel_Text_Send_Error_Unknown.
405 </tp:docstring>
406 </arg>
407
408 <tp:possible-errors>
409 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
410 </tp:error>
411
412 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
413 <tp:docstring>
414 One of the specified message IDs was invalid. No delivery reports
415 were sent.
416 </tp:docstring>
417 </tp:error>
418
419 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
420 <tp:docstring>
421 The requested message status could not be reported to the sender
422 (for instance, this will be raised if a positive delivery report
423 is requested on a protocol that only supports negative delivery
424 reports). Clients MUST treat this error as non-fatal.
425 </tp:docstring>
426 </tp:error>
427
428 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
429 <tp:docstring>
430 This channel cannot report message status back to the sender
431 at all. Do not call this method on this channel again.
432 </tp:docstring>
433 </tp:error>
434 </tp:possible-errors>
435 </method>
436
437 </interface>
438 </node>
439 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+15
-0
spec/Channel_Interface_Group.xml less more
6666 <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
6767 </tp:possible-errors>
6868 </method>
69
6970 <method name="GetAllMembers">
7071 <arg direction="out" type="au" tp:type="Contact_Handle[]">
7172 <tp:docstring>
9192 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
9293 </tp:possible-errors>
9394 </method>
95
9496 <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u">
9597 <tp:flag suffix="Can_Add" value="1">
9698 <tp:docstring>
175177 </tp:docstring>
176178 </tp:flag>
177179 </tp:flags>
180
178181 <method name="GetGroupFlags">
179182 <arg direction="out" type="u" tp:type="Channel_Group_Flags">
180183 <tp:docstring>
191194 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
192195 </tp:possible-errors>
193196 </method>
197
194198 <method name="GetHandleOwners">
195199 <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
196200 <tp:docstring>
230234 </tp:error>
231235 </tp:possible-errors>
232236 </method>
237
233238 <method name="GetLocalPendingMembers">
234239 <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
235240 <tp:docstring>
241246 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
242247 </tp:possible-errors>
243248 </method>
249
244250 <method name="GetLocalPendingMembersWithInfo">
245251 <tp:added version="0.15.0" />
246252 <tp:docstring>
275281 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
276282 </tp:possible-errors>
277283 </method>
284
278285 <method name="GetMembers">
279286 <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
280287 <tp:docstring>
285292 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
286293 </tp:possible-errors>
287294 </method>
295
288296 <method name="GetRemotePendingMembers">
289297 <arg direction="out" type="au" tp:type="Contact_Handle[]"/>
290298 <tp:docstring>
296304 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
297305 </tp:possible-errors>
298306 </method>
307
299308 <method name="GetSelfHandle">
300309 <arg direction="out" type="u" tp:type="Contact_Handle"/>
301310 <tp:docstring>
311320 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
312321 </tp:possible-errors>
313322 </method>
323
314324 <signal name="GroupFlagsChanged">
315325 <arg name="added" type="u" tp:type="Channel_Group_Flags">
316326 <tp:docstring>
327337 The user interface should be updated as appropriate.
328338 </tp:docstring>
329339 </signal>
340
330341 <tp:enum name="Channel_Group_Change_Reason" type="u">
331342 <tp:enumvalue suffix="None" value="0">
332343 <tp:docstring>
414425 </tp:docstring>
415426 </tp:enumvalue>
416427 </tp:enum>
428
417429 <signal name="MembersChanged">
418430 <arg name="message" type="s">
419431 <tp:docstring>
460472 displayed to the user if desired.
461473 </tp:docstring>
462474 </signal>
475
463476 <method name="RemoveMembers">
464477 <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
465478 <tp:docstring>
489502 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
490503 </tp:possible-errors>
491504 </method>
505
492506 <method name="RemoveMembersWithReason">
493507 <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
494508 <tp:docstring>
525539 </tp:error>
526540 </tp:possible-errors>
527541 </method>
542
528543 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
529544 <p>Interface for channels which have multiple members, and where the members
530545 of the channel can change during its lifetime. Your presence in the channel
+79
-0
spec/Channel_Interface_HTML.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Channel_Interface_HTML"
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>
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 02110-1301, USA.</p>
19 </tp:license>
20 <interface
21 name="org.freedesktop.Telepathy.Channel.Interface.HTML.DRAFT"
22 tp:causes-havoc="unfinished">
23 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
24 <tp:requires
25 interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
26
27 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28 <p>This interface extends the Messages interface to support
29 capability discovery, so clients can decide what subset of HTML
30 is supported.</p>
31
32 <p>(However, the capability discovery mechanism has not been written
33 yet, so this interface MUST NOT be used. It exists only to
34 indicate what direction we intend to go in.)</p>
35
36 <tp:rationale>
37 <p>XMPP supports all of XHTML-IM, and SIP (at least theoretically)
38 supports all of XHTML. However, many protocols are more limited -
39 for instance, in MSN you can only set font properties for a
40 whole message at a time. We should not mislead users into thinking
41 they can send MSN messages where individual words are emphasized.</p>
42 </tp:rationale>
43
44 <p>If this interface is present, clients MAY send XHTML formatted text
45 in message parts with type "text/html", and SHOULD interpret
46 "text/html" message parts received in reply.</p>
47
48 <p>Client authors SHOULD pay careful attention to the security
49 considerations in XEP-0071, "XHTML-IM", to avoid exposing client users
50 to security risks.
51 (FIXME: or should the presence of this interface act as a guarantee
52 that the CM will perform filtering on "text/html" parts? In practice
53 that would mean all CMs had to link against a tag-soup parser like
54 libxml2)</p>
55
56 <p>To avoid misleading users, clients SHOULD only present UI for the
57 subset of HTML that is indicated to be supported by this
58 interface. It follows that clients SHOULD NOT send unsupported
59 markup to the connection manager. However, even if the connection
60 manager cannot send arbitrary XHTML, it MUST cope gracefully
61 with being given arbitrary XHTML by a client.</p>
62
63 <tp:rationale>
64 <p>Connection managers should be lenient in what they receive.</p>
65 </tp:rationale>
66
67 <p>Clients MUST NOT send HTML that is not well-formed XML, but
68 connection managers MAY signal HTML that is malformed or invalid.
69 Clients SHOULD attempt to parse messages as XHTML, but fall back
70 to using a permissive "tag-soup" HTML parser if that fails.
71 (FIXME: or should the presence of this interface imply that the
72 CM filters and fixes up "text/html"? In practice that would result
73 in all the CMs having to link against libxml2 or something)</p>
74 </tp:docstring>
75
76 </interface>
77 </node>
78 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+1
-0
spec/Channel_Interface_Hold.xml less more
2020
2121 <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold">
2222 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
23 <tp:changed version="0.17.4">first API-stable version</tp:changed>
2324
2425 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
2526 <p>Interface for channels where you may put the channel on hold.
+631
-0
spec/Channel_Interface_Messages.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Channel_Interface_Messages"
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>
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 02110-1301,
19 USA.</p>
20 </tp:license>
21 <interface
22 name="org.freedesktop.Telepathy.Channel.Interface.Messages.DRAFT">
23 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
24
25 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26 <p>This interface extends the Text interface to support more general
27 messages, including:</p>
28
29 <ul>
30 <li>messages with attachments (like MIME multipart/mixed)</li>
31 <li>groups of alternatives (like MIME multipart/alternative)</li>
32 <li>delivery reports</li>
33 <li>any extra types of message we need in future</li>
34 </ul>
35
36 <p>It also provides a hook for improved sent
37 message status notification, to be used by the DeliveryReporting
38 interface.</p>
39
40 <p>Although this specification supports formatted (rich-text)
41 messages with unformatted alternatives, implementations SHOULD NOT
42 attempt to send formatted messages until the Telepathy specification
43 has also been extended to cover capability discovery for message
44 formatting.</p>
45
46 <tp:rationale>
47 We intend to expose all rich-text messages as XHTML-IM, but on some
48 protocols, formatting is an extremely limited subset of that format
49 (e.g. there are protocols where foreground/background colours, font
50 and size can be set, but only for entire messages).
51 Until we can tell UIs what controls to offer to the user, it's
52 unfriendly to offer the user controls that may have no effect.
53 </tp:rationale>
54
55 <p>If this interface is present, clients that support it SHOULD
56 listen for the MessageSent and MessageReceived signals, and
57 ignore the Sent and Received signal on the Text interface
58 (which are guaranteed to duplicate signals from this interface).</p>
59 </tp:docstring>
60
61 <property name="SupportedContentTypes" type="as" access="read">
62 <tp:docstring>
63 A list of MIME types supported by this channel, with more preferred
64 MIME types appearing earlier in the list. The list MAY include "*/*"
65 to indicate that attachments with arbitrary MIME types can be sent.
66 If the list is empty, this indicates that messages may only include
67 a single "text/plain" part.
68 </tp:docstring>
69 </property>
70
71 <property name="MessagePartSupportFlags" type="u"
72 tp:type="Message_Part_Support_Flags"
73 access="read">
74 <tp:docstring>
75 Flags indicating the level of support for message parts on this
76 channel.
77 </tp:docstring>
78 </property>
79
80 <tp:flags name="Message_Part_Support_Flags"
81 value-prefix="Message_Part_Support_Flag">
82 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
83 <p>Flags indicating the level of support for message parts on this
84 channel. They are designed such that setting more flags always
85 implies that the channel has more capabilities.</p>
86
87 <p>It is assumed that messages containing a textual message body
88 (only), like the messages the Text interface was designed for, are
89 always supported.</p>
90
91 <p>There is no flag indicating support for alternatives. This is
92 because the SendMessage implementation can always accept messages
93 containing alternatives, even if the underlying protocol does not,
94 by deleting all alternatives except the first (most preferred)
95 that is supported.</p>
96
97 <tp:rationale>
98 Each of the flags 1, 2, 4 implies the previous flag, so we could
99 have used a simple enumeration here; however, we've defined
100 the message-part support indicator as a flag set for future
101 expansion.
102 </tp:rationale>
103 </tp:docstring>
104
105 <tp:flag suffix="Data_Only" value="1">
106 <tp:docstring>
107 SendMessage will accept messages containing a single part of any
108 type listed in the SupportedContentTypes property, with no
109 accompanying text.
110 </tp:docstring>
111 </tp:flag>
112 <tp:flag suffix="One_Attachment" value="2">
113 <tp:docstring>
114 SendMessage will accept messages containing a textual message body,
115 plus a single attachment of any type listed in the
116 SupportedContentTypes property. It does not make sense for this
117 flag to be set if Message_Part_Support_Flag_Data_Only is not also set
118 (because the connection manager can trivially provide an empty text
119 part if necessary).
120 </tp:docstring>
121 </tp:flag>
122 <tp:flag suffix="Multiple_Attachments" value="4">
123 <tp:docstring>
124 SendMessage will accept messages containing a textual message body,
125 plus an arbitrary number of attachments of any type listed in the
126 SupportedContentTypes property. It does not make sense for this
127 flag to be set if Message_Part_Support_Flag_One_Attachment is not
128 also set.
129 </tp:docstring>
130 </tp:flag>
131 </tp:flags>
132
133 <tp:mapping name="Message_Part" array-name="Message_Part_List">
134 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
135 <p>Part of a message's content. In practice, this mapping never
136 appears in isolation - messages are represented by a list of
137 Message_Part mappings.</p>
138
139 <p>An example of how a message might
140 look, in a Python-like syntax:</p>
141
142 <pre>
143 [
144 {
145 'message-sender': 42,
146 'message-sent': 1210067943,
147 'message-received': 1210067947,
148 'message-type': 0,
149 'pending-message-id': 437,
150 },
151 { 'alternative': 'main',
152 'type': 'text/html',
153 'content': 'Here is a photo of my cat:&lt;br /&gt;' +
154 '&lt;img src="cid:catphoto" alt="lol!" /&gt;' +
155 '&lt;br /&gt;Isn't it cute?',
156 },
157 { 'alternative': 'main',
158 'type': 'text/plain',
159 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
160 },
161 { 'identifier': 'catphoto',
162 'type': 'image/jpeg',
163 'size': 101000,
164 'needs-retrieval': True,
165 },
166 ]
167 </pre>
168
169 <div>
170 <p>The first part of the message contains "headers" which refer
171 to the entire message.</p>
172
173 <p>It is an error for a connection manager to put keys referring
174 to the message as a whole in the second or subsequent
175 Message_Part, but clients MUST recover from this error by ignoring
176 these keys in the second and subsequent parts.</p>
177
178 <p>Well-known keys for the message as a whole, and the corresponding
179 value types, include:</p>
180
181 <dl>
182 <!-- FIXME: if needed we could add:
183 <dt>message-identifier (s)</dt>
184 <dd>An opaque, globally-unique identifier for the entire message.
185 This MAY be treated as if it were a MIME Message-ID, e.g. for
186 the mid: and cid: URI schemes. If omitted, there is no suitable
187 identifier.</dd>
188 -->
189
190 <dt>message-sent (u - Unix_Timestamp)</dt>
191 <dd>The time the message was sent (if unavailable, the time
192 it arrived at a central server MAY be used). Omitted if no
193 reasonable approximation is available</dd>
194
195 <dt>message-received (u - Unix_Timestamp)</dt>
196 <dd>The time the message was received locally. SHOULD always
197 be present.</dd>
198
199 <dt>message-sender (u - Contact_Handle)</dt>
200 <dd>The contact who sent the message. If 0 or omitted, the contact
201 who sent the message could not be determined.</dd>
202
203 <dt>message-type (u - Channel_Text_Message_Type)</dt>
204 <dd>The type of message; if omitted,
205 Channel_Text_Message_Type_Normal MUST be assumed. SHOULD
206 be omitted for normal chat messages.</dd>
207
208 <dt>pending-message-id (u - Message_ID)</dt>
209 <dd>The incoming message ID. This MUST NOT be present on outgoing
210 messages. Clients SHOULD NOT store this key - it is only valid
211 for as long as the message remains unacknowledged.</dd>
212
213 <dt>interface (s - DBus_Interface_Name)</dt>
214 <dd>This message is specific to the given interface, which is
215 neither Text nor Messages. It SHOULD be ignored if that
216 interface is not supported. (Note that an 'interface' key
217 can also appear on the second and subsequent parts, where
218 it indicates that that part (only) should be ignored if
219 unsupported.)</dd>
220 </dl>
221 </div>
222
223 <div>
224 <p>The second and subsequent parts contain the message's
225 content, including plain text, formatted text and/or attached
226 files.</p>
227
228 <p>In any group of parts with the same non-empty value for the
229 "alternative" key (which represent alternative versions of the
230 same content), more faithful versions of the intended message MUST
231 come before less faithful versions (note that this order is the
232 opposite of MIME "multipart/alternative" parts). Clients SHOULD
233 display the first alternative that they understand.</p>
234
235 <tp:rationale>
236 Specifying the preference order means that if the underlying
237 protocol doesn't support alternatives, the CM can safely delete
238 everything apart from the first supported alternative when sending
239 messages.
240 </tp:rationale>
241
242 <p>Clients SHOULD present all parts that are not redundant
243 alternatives in the order they appear in this array, possibly
244 excluding parts that are referenced by another displayed part.
245 It is implementation-specific how the parts are presented to the
246 user.</p>
247
248 <tp:rationale>
249 <p>This allows CMs to assume that all parts are actually shown to
250 the user, even if they are not explicitly referenced - we do
251 not yet recommend formatted text, and there is no way for
252 plain text to reference an attachment since it has no concept of
253 markup or references. This also forces clients to do something
254 sensible with messages that consist entirely of "attachments",
255 with no "body" at all.</p>
256
257 <p>For instance, when displaying the above example, a client that
258 understands the HTML part should display the JPEG image once,
259 between the two lines "Here is a photo of my cat:" and
260 "Isn't it cute?"; it may additionally present the image in some
261 way for a second time, after "Isn't it cute?", or may choose
262 not to.</p>
263
264 <p>A client that does not understand HTML, displaying the same
265 message, should display the plain-text part, followed by the JPEG
266 image.</p>
267 </tp:rationale>
268
269 <p>Well-known keys for the second and subsequent parts, and the
270 corresponding value types, include:</p>
271
272 <dl>
273 <dt>identifier (s)</dt>
274 <dd>An opaque identifier for this part.
275 Parts of a message MAY reference other parts by treating
276 this identifier as if it were a MIME Content-ID and using
277 the cid: URI scheme.</dd>
278
279 <dt>alternative (s)</dt>
280 <dd>
281 <p>If present, this part of the message is an alternative for
282 all other parts with the same value for "alternative".
283 Clients SHOULD only display one of them (this is expected to
284 be used for XHTML messages in a future version of this
285 specification).</p>
286
287 <p>If omitted, this part is not an alternative for any other
288 part.</p>
289
290 <p>Parts of a message MAY reference the group of alternatives
291 as a whole (i.e. a reference to whichever of them is chosen)
292 by treating this identifier as if it were the MIME Content-ID
293 of a multipart/alternative part, and using the cid: URI
294 scheme.</p>
295 </dd>
296
297 <dt>type (s)</dt>
298 <dd>
299 <p>The MIME type of this part. See the documentation
300 for ReceivedMessage for notes on the special status of
301 "text/plain" parts.</p>
302
303 <p>Connection managers MUST NOT signal parts without a 'type'
304 key; if a protocol provides no way to determine the MIME type,
305 the connection manager is responsible for guessing it, but
306 MAY fall back to "text/plain" for text and
307 "application/octet-stream" for non-text.</p>
308
309 <p>Clients MUST ignore parts without a 'type' key, which are
310 reserved for future expansion.</p>
311 </dd>
312
313 <dt>lang (s)</dt>
314 <dd>The natural language of this part, identified by a
315 RFC 3066 language tag.
316
317 <tp:rationale>
318 XMPP allows alternative-selection by language as well as
319 by content-type.
320 </tp:rationale>
321 </dd>
322
323 <dt>size (u)</dt>
324 <dd>The size in bytes (if needs-retrieval is true, this MAY be an
325 estimated or approximate size). SHOULD be omitted if 'content'
326 is provided.
327
328 <tp:rationale>
329 There's no point in providing the size if you're already
330 providing all the content.
331 </tp:rationale>
332 </dd>
333
334 <dt>needs-retrieval (b)</dt>
335 <dd>If false or omitted, the connection
336 manager already holds this part in memory. If present and true,
337 this part will be retrieved on demand (like MIME's
338 message/external-body), so clients should expect retrieval to
339 take time; if this specification is later extended to provide a
340 streaming version of GetPendingMessageContent, clients should
341 use it for parts with this flag.</dd>
342
343 <dt>truncated (b)</dt>
344 <dd>The content available via the 'content' key or
345 GetPendingMessageContent has been truncated by the server
346 or connection manager (equivalent to
347 Channel_Text_Message_Flag_Truncated in the Text interface).
348 </dd>
349
350 <dt>content (s or ay)</dt>
351 <dd>The part's content, if it is available and
352 sufficiently small to include here (implies that
353 'needs-retrieval' is false or omitted). Otherwise, omitted.
354 If the part is human-readable text or HTML, the value for this
355 key MUST be a UTF-8 string (D-Bus signature 's').
356 If the part is not text, the value MUST be a byte-array
357 (D-Bus signature 'ay'). If the part is a text-based format
358 that is not the main body of the message (e.g. an iCalendar
359 or an attached XML document), the value SHOULD be a UTF-8 string,
360 transcoding from another charset to UTF-8 if necessary, but
361 MAY be a byte-array (of unspecified character set) if
362 transcoding fails or the source charset is not known.</dd>
363
364 <!-- FIXME: "sufficiently small to include" is not currently
365 defined; we should add some API so clients can tell the
366 CM how large a message it should emit in the signal.-->
367
368 <dt>interface (s - DBus_Interface_Name)</dt>
369 <dd>This part is specific to the given interface, which is
370 neither Text nor Messages. It SHOULD be ignored if that
371 interface is not supported. (Note that an 'interface' key
372 can also appear on the first part, where it indicates that the
373 entire message should be ignored if unsupported.)</dd>
374 </dl>
375
376 <p>It is an error for a connection manager to put these keys
377 in the first Message_Part, but clients MUST be able to recover
378 from this error by ignoring these keys in the first part.</p>
379
380 </div>
381 </tp:docstring>
382
383 <tp:member name="Key" type="s">
384 <tp:docstring>
385 A key, which SHOULD be one of the well-known keys specified, if
386 possible.
387 </tp:docstring>
388 </tp:member>
389
390 <tp:member name="Value" type="v">
391 <tp:docstring>
392 The value corresponding to the given key, which must be of one of
393 the types indicated.
394 </tp:docstring>
395 </tp:member>
396 </tp:mapping>
397
398
399 <tp:simple-type type="s" name="Sent_Message_Token">
400 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
401 <p>An opaque token used to identify sent messages. As a special case,
402 the empty string indicates that there is no particular
403 identification for a message.</p>
404
405 <p>CM implementations SHOULD use an identifier expected to be unique,
406 such as a UUID, if possible.</p>
407
408 <p>Some protocols can only track a limited number of sent messages
409 in a small message-ID space. As a result, clients MUST NOT assume
410 that message tokens will not be re-used, and SHOULD use some
411 reasonable heuristic to assign delivery reports to messages, such
412 as matching on message content or timestamp (if available), or
413 assuming that the delivery report refers to the most recent message
414 with that ID.</p>
415
416 <tp:rationale>
417 <p>This is a hook for the DeliveryReporting interface,
418 to avoid having to introduce a
419 SendMultiPartMessageAndReturnToken method in that interface.</p>
420 </tp:rationale>
421 </tp:docstring>
422 </tp:simple-type>
423
424 <method name="SendMessage">
425 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
426 <p>Submit a message to the server for sending.
427 If this method returns successfully, the message has been submitted
428 to the server and the MessageSent signal is emitted. A corresponding
429 Sent signal on the Text interface MUST also be emitted.</p>
430
431 <p>If this method fails, message submission to the server has failed
432 and no signal on this interface (or the Text interface) is
433 emitted.</p>
434 </tp:docstring>
435
436 <arg direction="in" type="aa{sv}" tp:type="Message_Part[]"
437 name="Message">
438 <tp:docstring>
439 The message content, including any attachments or alternatives
440 </tp:docstring>
441 </arg>
442 <arg direction="in" name="Flags" type="u"
443 tp:type="Message_Sending_Flags">
444 <tp:docstring>
445 Flags affecting how the message is sent.
446 </tp:docstring>
447 </arg>
448
449 <arg direction="out" type="s" tp:type="Sent_Message_Token">
450 <tp:docstring>
451 An opaque token used to match any incoming delivery or failure
452 reports against this message, or an empty string if the message
453 is not readily identifiable.
454 </tp:docstring>
455 </arg>
456
457 <tp:possible-errors>
458 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
459 <tp:docstring>
460 The requested message is malformed and cannot be sent.
461 </tp:docstring>
462 </tp:error>
463 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
464 <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
465 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
466 </tp:possible-errors>
467 </method>
468
469 <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag">
470 <tp:docstring>
471 Flags altering the way a message is sent. The "most usual" action
472 should always be to have these flags unset.
473 </tp:docstring>
474
475 <tp:flag suffix="Report_Delivery" value="1">
476 <tp:docstring>
477 Provide a delivery report via the DeliveryReporting interface, if
478 possible, even if this is not the default for this protocol.
479 Ignored if delivery reports are not possible on this protocol.
480
481 <tp:rationale>
482 In some protocols, like XMPP, it is not conventional to request
483 or send delivery notifications.
484 </tp:rationale>
485 </tp:docstring>
486 </tp:flag>
487 </tp:flags>
488
489 <signal name="MessageSent">
490 <tp:docstring>
491 Signals that a message has been submitted for sending. This
492 MUST be emitted exactly once per emission of the Sent signal on the
493 Text interface.
494
495 <tp:rationale>
496 This signal allows a process that is not the caller of
497 SendMessage to log sent messages. The double signal-emission
498 means that clients can safely follow the following rule:
499 if the channel has the Messages interface, listen for
500 Messages.MessageSent only; otherwise, listen for Text.Sent only.
501 </tp:rationale>
502 </tp:docstring>
503
504 <arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
505 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
506 The message content (see Message_Part for full
507 details). If the message that was passed to SendMessage has a
508 formatted text part that the connection manager recognises, but no
509 text/plain alternative, the CM MUST use the formatted text part to
510 generate a text/plain alternative which is also included in this
511 signal argument.
512 </tp:docstring>
513 </arg>
514
515 <arg name="Message_Token" type="s" tp:type="Sent_Message_Token">
516 <tp:docstring>
517 An opaque token used to match any incoming delivery or failure
518 reports against this message, or an empty string if the message
519 is not readily identifiable.
520 </tp:docstring>
521 </arg>
522 </signal>
523
524 <property name="PendingMessages" type="aaa{sv}" access="read"
525 tp:type="Message_Part[][]">
526 <tp:docstring>
527 A list of incoming messages that have neither been acknowledged nor
528 rejected. This list is a superset of the one returned by
529 ListPendingMessages on the Text interface; its items can be removed
530 using AcknowledgePendingMessages on that interface.
531 </tp:docstring>
532 </property>
533
534 <!-- FIXME: should we add this signal to the Text interface instead? -->
535 <signal name="PendingMessagesRemoved">
536 <tp:docstring>
537 The messages with the given IDs have been removed from the
538 PendingMessages list. Clients SHOULD NOT attempt to acknowledge
539 those messages.
540
541 <tp:rationale>
542 This completes change notification for the PendingMessages property
543 (previously, there was change notification when pending messages
544 were added, but not when they were removed).
545 </tp:rationale>
546 </tp:docstring>
547
548 <arg name="Message_IDs" type="au" tp:type="Message_ID[]">
549 <tp:docstring>
550 The messages that have been removed from the pending message list.
551 </tp:docstring>
552 </arg>
553 </signal>
554
555 <method name="GetPendingMessageContent">
556 <tp:docstring>
557 Retrieve the content of one or more parts of a pending message.
558 Note that this function may take a considerable amount of time
559 to return if the part's 'needs-retrieval' flag is true; consider
560 extending the default D-Bus method call timeout. Additional API is
561 likely to be added in future, to stream large message parts.
562 </tp:docstring>
563
564 <arg name="Message_ID" type="u" tp:type="Message_ID" direction="in">
565 <tp:docstring>
566 The ID of a pending message
567 </tp:docstring>
568 </arg>
569
570 <arg name="Parts" type="au" direction="in">
571 <tp:docstring>
572 The desired entries in the array of message parts, identified by
573 their position. The "headers" part (which is not a valid argument
574 to this method) is considered to be part 0, so the valid part
575 numbers start at 1 (for the second Message_Part).
576 </tp:docstring>
577 </arg>
578
579 <arg name="Content" type="a{uv}" direction="out">
580 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
581 <p>The content of the requested parts. The keys in this mapping
582 are positions in the array of message parts; the values are
583 either of type 's' or 'ay' (UTF-8 text string, or byte array),
584 following the same rules as for the value of the 'content' key in
585 the Message_Part mappings.</p>
586
587 <p>If the one of the requested part numbers was greater than zero
588 but referred to a part that had no content (i.e. it had no 'type'
589 key or no 'content' key), it is simply omitted from this mapping;
590 this is not considered to be an error condition.</p>
591 </tp:docstring>
592 </arg>
593
594 <tp:possible-errors>
595 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
596 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
597 Either there is no pending message with the given message ID,
598 or one of the part numbers given was 0 or too large.
599 </tp:docstring>
600 </tp:error>
601 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
602 <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
603 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
604 </tp:possible-errors>
605 </method>
606
607 <signal name="MessageReceived">
608 <tp:docstring>
609 Signals that a message has been received and added to the pending
610 messages queue. This MUST be emitted exactly once per emission of the
611 Received signal on the Text interface.
612
613 <tp:rationale>
614 The double signal-emission means that clients can safely follow
615 the following rule: if the channel has the Messages interface,
616 listen for Messages.MessageReceived only; otherwise, listen for
617 Text.Received only.
618 </tp:rationale>
619 </tp:docstring>
620
621 <arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
622 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
623 The message content, including any attachments or alternatives
624 </tp:docstring>
625 </arg>
626 </signal>
627
628 </interface>
629 </node>
630 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+12
-0
spec/Channel_Type_Room_List.xml less more
2626 <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/>
2727 </tp:struct>
2828
29 <property name="Server" type="s" access="read">
30 <tp:docstring>
31 <p>For protocols with a concept of chatrooms on multiple servers
32 with different DNS names (like XMPP), the DNS name of the server
33 whose rooms are listed by this channel, e.g. "conference.jabber.org".
34 Otherwise, the empty string.</p>
35
36 <p>This property cannot change during the lifetime of the channel.</p>
37 </tp:docstring>
38 </property>
39
2940 <method name="GetListingRooms">
3041 <arg direction="out" type="b">
3142 <tp:docstring>
3748 on this channel.
3849 </tp:docstring>
3950 </method>
51
4052 <signal name="GotRooms">
4153 <arg name="rooms" type="a(usa{sv})" tp:type="Room_Info[]">
4254 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+6
-4
spec/Channel_Type_Streamed_Media.xml less more
197197 them), the StreamDirectionChanged signal will be emitted with the
198198 MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
199199 with the flag cleared when the remote end has replied.</p>
200
201 <p>As of version 0.17.2, it is valid to use a handle which is neither
200 </tp:docstring>
201 <tp:changed version="0.17.2">
202 <p>It is valid to use a handle which is neither
202203 a current nor pending member in this channel's Group interface. If
203204 so, that handle will be added to the remote-pending set only when
204205 an attempt has actually been made to contact them. For further
205206 call-state notification, use the CallState interface, if
206 supported.</p>
207 </tp:docstring>
207 supported. This usage was not allowed in spec versions below
208 0.17.2.</p>
209 </tp:changed>
208210 <tp:possible-errors>
209211 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
210212 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+50
-12
spec/Channel_Type_Text.xml less more
2020 <interface name="org.freedesktop.Telepathy.Channel.Type.Text">
2121 <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
2222
23 <tp:simple-type name="Message_ID" type="u"/>
23 <tp:simple-type name="Message_ID" type="u">
24 <tp:docstring>
25 A unique-per-channel identifier for an incoming message. These
26 SHOULD be allocated in a way that minimizes collisions (in particular,
27 message IDs SHOULD NOT be re-used until all of the 32-bit integer
28 space has already been used).
29 </tp:docstring>
30 </tp:simple-type>
2431
2532 <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List">
2633 <tp:docstring>A struct (message ID, timestamp in seconds since
4653 <tp:docstring>
4754 Inform the channel that you have handled messages by displaying them to
4855 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.
5256 </tp:docstring>
5357 <tp:possible-errors>
5458 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
5660 A given message ID was not found, so no action was taken
5761 </tp:docstring>
5862 </tp:error>
59 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
6063 </tp:possible-errors>
6164 </method>
6265
7679 <arg direction="in" name="clear" type="b">
7780 <tp:docstring>
7881 If true, behave as if AcknowledgePendingMessages had also been
79 called. Setting this to true is NOT RECOMMENDED for clients that
82 called.
83 </tp:docstring>
84 <tp:deprecated since="0.17.3">
85 Setting this to true is NOT RECOMMENDED for clients that
8086 have some sort of persistent message storage - clients SHOULD only
8187 acknowledge messages after they have actually stored them, which is
82 impossible if this flag is true.
83 </tp:docstring>
88 impossible if this flag is true.</tp:deprecated>
8489 </arg>
8590 <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]">
8691 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
237242 Sent has already been emitted and Send has already returned
238243 success.</p>
239244 </tp:docstring>
245 <tp:changed version="0.17.3">older spec versions claimed that SendError
246 was emitted <em>instead of</em> Sent, rather than <em>in addition
247 to</em> Sent. However, the 0.17.3+ semantics were what we'd always
248 actually implemented.</tp:changed>
240249 </signal>
241250
242251 <signal name="Sent">
262271 </signal>
263272
264273 <tp:enum name="Channel_Text_Message_Type" type="u">
274 <tp:docstring>
275 The type of message.
276 </tp:docstring>
277
265278 <tp:enumvalue suffix="Normal" value="0">
266279 <tp:docstring>
267 A standard message
268 </tp:docstring>
269 </tp:enumvalue>
280 An ordinary chat message. Unknown types SHOULD be treated like this.
281 </tp:docstring>
282 </tp:enumvalue>
283
270284 <tp:enumvalue suffix="Action" value="1">
271285 <tp:docstring>
272286 An action which might be presented to the user as
275289 text of the message might be "drinks more coffee".
276290 </tp:docstring>
277291 </tp:enumvalue>
292
278293 <tp:enumvalue suffix="Notice" value="2">
279294 <tp:docstring>
280295 A one-off or automated message not necessarily expecting a reply
281296 </tp:docstring>
282297 </tp:enumvalue>
298
283299 <tp:enumvalue suffix="Auto_Reply" value="3">
284300 <tp:docstring>
285 An automatically-generated reply message
301 An automatically-generated reply message.
302 </tp:docstring>
303 </tp:enumvalue>
304
305 <tp:enumvalue suffix="Delivery_Report" value="4">
306 <tp:docstring>
307 This message type MUST NOT appear unless the channel supports the
308 DeliveryReporting interface. The message MUST be as defined by
309 the DeliveryReporting interface.
286310 </tp:docstring>
287311 </tp:enumvalue>
288312 </tp:enum>
292316 <tp:docstring>
293317 The incoming message was truncated to a shorter length by the
294318 server or the connection manager.
319 </tp:docstring>
320 </tp:flag>
321
322 <tp:flag suffix="Non_Text_Content" value="2">
323 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
324 <p>The incoming message contained non-text content which cannot be
325 represented by this interface, but has been signalled
326 in the Messages interface.</p>
327
328 <p>Connection managers SHOULD only set this flag if the non-text
329 content appears to be relatively significant (exactly how
330 significant is up to the implementor). The intention is that
331 if this flag is set, clients using this interface SHOULD inform
332 the user that part of the message was not understood.</p>
295333 </tp:docstring>
296334 </tp:flag>
297335 </tp:flags>
+17
-5
spec/Connection.xml less more
245245 </arg>
246246
247247 <arg name="suppress_handler" type="b">
248 <tp:docstring>
249 A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched
248 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
249 <p>If true, the channel was requested by a client that intends to
250 present it to the user itself (i.e. it passed suppress_handler=TRUE
251 to the RequestChannel method), so no other handler should be
252 launched.</p>
253
254 <p>If false, either the channel was created due to incoming
255 information from the service, or the channel was requested by
256 a local client that does not intend to handle the channel itself
257 (a typical use-case is an address-book viewer that does not itself
258 implement chat or VoIP functionality, starting a channel that
259 will be handled by the same user interface that would handle
260 incoming channels).</p>
261
262 <p>Clients MUST NOT assume that only incoming channels will have
263 this flag set to false.</p>
250264 </tp:docstring>
251265 </arg>
252266
253267 <tp:docstring>
254268 Emitted when a new Channel object is created, either through user
255 request or incoming information from the service. The suppress_handler
256 boolean indicates if the channel was requested by an existing client,
257 or is an incoming communication and needs to have a handler launched.
269 request or incoming information from the service.
258270 </tp:docstring>
259271 </signal>
260272
+1
-0
spec/Connection_Interface_Presence.xml less more
345345 </tp:docstring>
346346 </tp:enumvalue>
347347 <tp:enumvalue suffix="Busy" value="6">
348 <tp:added version="0.17.0"/>
348349 <tp:docstring>
349350 Busy, Do Not Disturb.
350351 </tp:docstring>
+8
-0
spec/Connection_Manager.xml less more
2828 prefix removed, and any hyphen/minus signs replaced by
2929 underscores.
3030 </tp:docstring>
31 <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
32 characters were not specified</tp:changed>
3133 </tp:simple-type>
3234
3335 <tp:simple-type name="Protocol" type="s">
5759 <li>zephyr - Zephyr</li>
5860 </ul>
5961 </tp:docstring>
62 <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
63 characters were not specified</tp:changed>
6064 </tp:simple-type>
6165
6266 <tp:struct name="Param_Spec" array-name="Param_Spec_List">
109113 any parameter whose name contains "password" as though it had this
110114 flag.)</p>
111115 </tp:docstring>
116 <tp:added version="0.17.2"/>
112117 </tp:flag>
113118 </tp:flags>
114119
398403 well-known bus name, causing a new connection manager to be activated when
399404 somebody attempts to make a new connection.</p>
400405 </tp:docstring>
406
407 <tp:changed version="0.17.2">Prior to version 0.17.2, support for
408 CMs with no .manager file was not explicitly required.</tp:changed>
401409 </interface>
402410 </node>
403411 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+4
-0
spec/Media_Stream_Handler.xml less more
337337 contact will never even be told that we tried to acquire it.</p>
338338 </tp:rationale>
339339 </tp:docstring>
340 <tp:added version="0.17.3"/>
341
340342 <arg name="Held" type="b">
341343 <tp:docstring>
342344 If true, the stream is to be placed on hold.
349351 Notify the connection manager that the stream's hold state has
350352 been changed successfully in response to SetStreamHeld.
351353 </tp:docstring>
354 <tp:added version="0.17.3"/>
352355 <arg direction="in" name="Held" type="b">
353356 <tp:docstring>
354357 If true, the stream is now on hold.
362365 necessary hardware or software resources to unhold the stream,
363366 in response to SetStreamHeld, has failed.
364367 </tp:docstring>
368 <tp:added version="0.17.3"/>
365369 </method>
366370
367371 <tp:docstring>
+4
-1
spec/all.xml less more
22 xmlns:xi="http://www.w3.org/2001/XInclude">
33
44 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
5 <tp:version>0.17.4</tp:version>
5 <tp:version>0.17.5</tp:version>
66
77 <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
88 <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
5050 <xi:include href="Channel_Interface_Call_Merging.xml"/>
5151 <xi:include href="Channel_Interface_Call_State.xml"/>
5252 <xi:include href="Channel_Interface_Chat_State.xml"/>
53 <xi:include href="Channel_Interface_Delivery_Reporting.xml"/>
5354 <xi:include href="Channel_Interface_DTMF.xml"/>
5455 <xi:include href="Channel_Interface_Group.xml"/>
5556 <xi:include href="Channel_Interface_Hold.xml"/>
57 <xi:include href="Channel_Interface_HTML.xml"/>
5658 <xi:include href="Channel_Interface_Password.xml"/>
5759 <!-- Causes havoc, never implemented, unclear requirements
5860 <xi:include href="Channel_Interface_Transfer.xml"/> -->
5961 <xi:include href="Channel_Interface_Media_Signalling.xml"/>
62 <xi:include href="Channel_Interface_Messages.xml"/>
6063
6164 <xi:include href="Media_Session_Handler.xml"/>
6265 <xi:include href="Media_Stream_Handler.xml"/>
+9
-0
test/expected/spec.html.canon less more
9797 padding-left: 0.5em;
9898 }
9999
100 .added {
101 color: #006600;
102 background: #ffffff;
103 }
104 .deprecated {
105 color: #ff0000;
106 background: #ffffff;
107 }
108
100109 </style></head><body><h1 class="topbox">telepathy-spec tools test case</h1><h2>Version 0.1.2</h2><div>Copyright (C) 2006 Collabora Limited</div><p>This library is free software; you can redistribute it and/or
101110 modify it under the terms of the GNU Lesser General Public
102111 License as published by the Free Software Foundation; either
+76
-2
tools/doc-generator.xsl less more
4242 <xsl:apply-templates select="text() | html:* | tp:rationale" mode="html"/>
4343 </xsl:template>
4444
45 <xsl:template match="tp:added">
46 <p class="added">Added in version <xsl:value-of select="@version"/>.
47 <xsl:apply-templates select="node()" mode="html"/></p>
48 </xsl:template>
49
50 <xsl:template match="tp:changed">
51 <xsl:choose>
52 <xsl:when test="node()">
53 <p class="changed">Changed in version <xsl:value-of select="@version"/>:
54 <xsl:apply-templates select="node()" mode="html"/></p>
55 </xsl:when>
56 <xsl:otherwise>
57 <p class="changed">Changed in version
58 <xsl:value-of select="@version"/></p>
59 </xsl:otherwise>
60 </xsl:choose>
61 </xsl:template>
62
63 <xsl:template match="tp:deprecated">
64 <p class="deprecated">Deprecated since version
65 <xsl:value-of select="@version"/>.
66 <xsl:apply-templates select="node()" mode="html"/></p>
67 </xsl:template>
68
4569 <xsl:template match="tp:rationale" mode="html">
4670 <div xmlns="http://www.w3.org/1999/xhtml" class="rationale">
4771 <xsl:apply-templates select="node()" mode="html"/>
93117 <xsl:template match="tp:error">
94118 <h2 xmlns="http://www.w3.org/1999/xhtml"><a name="{concat(../@namespace, '.', translate(@name, ' ', ''))}"></a><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></h2>
95119 <xsl:apply-templates select="tp:docstring"/>
120 <xsl:apply-templates select="tp:added"/>
121 <xsl:apply-templates select="tp:changed"/>
122 <xsl:apply-templates select="tp:deprecated"/>
96123 </xsl:template>
97124
98125 <xsl:template match="/tp:spec/tp:copyright">
130157 </xsl:if>
131158
132159 <xsl:apply-templates select="tp:docstring" />
160 <xsl:apply-templates select="tp:added"/>
161 <xsl:apply-templates select="tp:changed"/>
162 <xsl:apply-templates select="tp:deprecated"/>
133163
134164 <xsl:choose>
135165 <xsl:when test="method">
193223 </a>
194224 </h3>
195225 <xsl:apply-templates select="tp:docstring" />
226 <xsl:apply-templates select="tp:added"/>
227 <xsl:apply-templates select="tp:changed"/>
228 <xsl:apply-templates select="tp:deprecated"/>
196229 <dl xmlns="http://www.w3.org/1999/xhtml">
197230 <xsl:variable name="value-prefix">
198231 <xsl:choose>
208241 <dt xmlns="http://www.w3.org/1999/xhtml"><code><xsl:value-of select="concat($value-prefix, '_', @suffix)"/> = <xsl:value-of select="@value"/></code></dt>
209242 <xsl:choose>
210243 <xsl:when test="tp:docstring">
211 <dd xmlns="http://www.w3.org/1999/xhtml"><xsl:apply-templates select="tp:docstring" /></dd>
244 <dd xmlns="http://www.w3.org/1999/xhtml">
245 <xsl:apply-templates select="tp:docstring" />
246 <xsl:apply-templates select="tp:added"/>
247 <xsl:apply-templates select="tp:changed"/>
248 <xsl:apply-templates select="tp:deprecated"/>
249 </dd>
212250 </xsl:when>
213251 <xsl:otherwise>
214252 <dd xmlns="http://www.w3.org/1999/xhtml">(Undocumented)</dd>
225263 </a>
226264 </h3>
227265 <xsl:apply-templates select="tp:docstring" />
266 <xsl:apply-templates select="tp:added"/>
267 <xsl:apply-templates select="tp:changed"/>
268 <xsl:apply-templates select="tp:deprecated"/>
228269 <dl xmlns="http://www.w3.org/1999/xhtml">
229270 <xsl:variable name="value-prefix">
230271 <xsl:choose>
240281 <dt xmlns="http://www.w3.org/1999/xhtml"><code><xsl:value-of select="concat($value-prefix, '_', @suffix)"/> = <xsl:value-of select="@value"/></code></dt>
241282 <xsl:choose>
242283 <xsl:when test="tp:docstring">
243 <dd xmlns="http://www.w3.org/1999/xhtml"><xsl:apply-templates select="tp:docstring" /></dd>
284 <dd xmlns="http://www.w3.org/1999/xhtml">
285 <xsl:apply-templates select="tp:docstring" />
286 <xsl:apply-templates select="tp:added"/>
287 <xsl:apply-templates select="tp:changed"/>
288 <xsl:apply-templates select="tp:deprecated"/>
289 </dd>
244290 </xsl:when>
245291 <xsl:otherwise>
246292 <dd xmlns="http://www.w3.org/1999/xhtml">(Undocumented)</dd>
277323 </dt>
278324 <dd xmlns="http://www.w3.org/1999/xhtml">
279325 <xsl:apply-templates select="tp:docstring"/>
326 <xsl:apply-templates select="tp:added"/>
327 <xsl:apply-templates select="tp:changed"/>
328 <xsl:apply-templates select="tp:deprecated"/>
280329 </dd>
281330 </xsl:template>
282331
289338 </dt>
290339 <dd xmlns="http://www.w3.org/1999/xhtml">
291340 <xsl:apply-templates select="tp:docstring"/>
341 <xsl:apply-templates select="tp:added"/>
342 <xsl:apply-templates select="tp:changed"/>
343 <xsl:apply-templates select="tp:deprecated"/>
292344 </dd>
293345 </xsl:template>
294346
339391 </h3>
340392 <div class="docstring">
341393 <xsl:apply-templates select="tp:docstring"/>
394 <xsl:apply-templates select="tp:added"/>
395 <xsl:apply-templates select="tp:changed"/>
396 <xsl:apply-templates select="tp:deprecated"/>
342397 </div>
343398 </div>
344399 </xsl:template>
384439 </h3>
385440 <div class="docstring">
386441 <xsl:apply-templates select="tp:docstring"/>
442 <xsl:apply-templates select="tp:added"/>
443 <xsl:apply-templates select="tp:changed"/>
444 <xsl:apply-templates select="tp:deprecated"/>
387445 </div>
388446 <xsl:choose>
389447 <xsl:when test="string(@array-name) != ''">
428486 </h3>
429487 <div xmlns="http://www.w3.org/1999/xhtml" class="docstring">
430488 <xsl:apply-templates select="tp:docstring" />
489 <xsl:apply-templates select="tp:added"/>
490 <xsl:apply-templates select="tp:changed"/>
491 <xsl:apply-templates select="tp:deprecated"/>
431492 </div>
432493
433494 <xsl:if test="arg[@direction='in']">
567628 <xsl:if test="position() != last()">, </xsl:if>
568629 </xsl:for-each>
569630 )</h3>
631
570632 <div xmlns="http://www.w3.org/1999/xhtml" class="docstring">
571633 <xsl:apply-templates select="tp:docstring"/>
634 <xsl:apply-templates select="tp:added"/>
635 <xsl:apply-templates select="tp:changed"/>
636 <xsl:apply-templates select="tp:deprecated"/>
572637 </div>
573638
574639 <xsl:if test="arg">
695760 font-style: italic;
696761 border-left: 0.25em solid #808080;
697762 padding-left: 0.5em;
763 }
764
765 .added {
766 color: #006600;
767 background: #ffffff;
768 }
769 .deprecated {
770 color: #ff0000;
771 background: #ffffff;
698772 }
699773
700774 </style>