Codebase list telepathy-spec / upstream/0.19.6
Imported Upstream version 0.19.6 Simon McVittie 13 years ago
40 changed file(s) with 3371 addition(s) and 2096 deletion(s). Raw diff Collapse all Expand all
+493
-0
ChangeLog less more
0 commit 298402849d58f13f8427821262420e8f8582b842
1 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
2 Date: 2010-05-25 15:26:20 +0100
3
4 Prepare version 0.19.6
5
6 commit f928c12905faa5bc552e69211c643b6ccc9483cd
7 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
8 Date: 2010-05-25 15:25:07 +0100
9
10 Mark ContactList, ContactGroups as experimental
11
12 commit a062422c027861fd47bfc61bcdc5c719c6ad6b09
13 Merge: c7dafd6 7f1f730
14 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
15 Date: 2010-05-25 15:23:31 +0100
16
17 Merge branch 'contact-list'
18
19 Reviewed-by: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
20
21 commit c7dafd67e7849d6a5c5ed47c9356fd7c03008ee8
22 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
23 Date: 2010-05-25 15:13:12 +0100
24
25 Update NEWS
26
27 commit d1f1ecda3dc0a4dd666adde8ef4758b0d56a158b
28 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
29 Date: 2010-05-25 15:11:07 +0100
30
31 Remove trailing whitespace throughout
32
33 commit b1514f50102307285cd4b5ea36ccb663792ba0b0
34 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
35 Date: 2010-05-25 15:03:06 +0100
36
37 HandleWithTime: add version annotation
38
39 commit 9fb35489c299b0b063f93e7d4a9ccf712bb9922e
40 Merge: 4052033 7f224c8
41 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
42 Date: 2010-05-25 14:53:28 +0100
43
44 Merge remote branch 'andrunko/account-changing-presence'
45
46 Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
47 Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
48
49 commit 4052033f98e5357524bbf9ecb352eec0a609b0ca
50 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
51 Date: 2010-05-19 15:52:05 +0200
52
53 add ChannelDispatchOperation.HandleWithTime() (fdo #25183)
54
55 commit 98b8bf4f9c51ab996f439584edf49a00a2b50731
56 Author: Senko Rasic <senko.rasic@collabora.co.uk>
57 Date: 2010-05-21 12:28:46 +0200
58
59 C.I.Anonymity: replace SetAnonymityModes() with newly-writable AnonymityModes property
60
61 commit 7f1f7303bb094f50a931c0ce3505890db06c8066
62 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
63 Date: 2010-05-21 16:14:38 +0100
64
65 ContactList: recommend a longer-than-default timeout for GetContactListAttributes
66
67 commit deff143f2c111abd14471af580e845076303ab0a
68 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
69 Date: 2010-05-21 16:12:19 +0100
70
71 GetContactListAttributes: hyperlink GetContactAttributes
72
73 commit 345f8b5ed9c244dfbfb68f3843b5f26e1cc2360d
74 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
75 Date: 2010-05-21 16:10:10 +0100
76
77 Groups: remove the concept of a default group
78
79 commit e9265f93bafcef8debff9cdff5294605a9279576
80 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
81 Date: 2010-04-19 14:01:51 +0100
82
83 Groups: change renaming/removing groups to emit GroupsChanged too
84
85 Now that GroupsChanged is plural, it's cheap to emit, and it seems easier
86 to write client code if it can ignore the signals it doesn't care about.
87
88 commit a4083166b92452d86f047e4d44ef3e1c26f3d9a9
89 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
90 Date: 2010-04-19 14:01:09 +0100
91
92 Pluralize GroupsChanged (for contacts), GroupsCreated, GroupsRemoved
93
94 commit ef99ec21356b0b0a269394e97185df66424c74bd
95 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
96 Date: 2010-04-12 15:32:49 +0100
97
98 Add Connection.Interface.ContactGroups draft
99
100 commit c1bc11eae28616d8e2565c8929d18da9212237c4
101 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
102 Date: 2010-05-12 16:18:18 +0200
103
104 RequestSubscription: add possible errors
105
106 commit 672907c6e61877d57f940cd0874dc08d6104fb19
107 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
108 Date: 2010-05-12 16:16:29 +0200
109
110 Add possible error to GetContactListAttributes
111
112 commit b9ef6f51f9ee932194b03fb48287b6bcc3ec3ab1
113 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
114 Date: 2010-04-19 14:46:46 +0100
115
116 Add publish-request attribute to ContactList
117
118 commit 779bb23a2f90ed0ee888df23fd1b8672d33f9e97
119 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
120 Date: 2010-04-19 14:22:42 +0100
121
122 ContactList: drop the Contacts property, just have GetContactListAttributes
123
124 A property isn't very suitable for delayed-return, but we don't want to
125 return the contact list on XMPP until the roster has been downloaded.
126
127 commit 6945fbd84df2016790cfb30784ff62dd5aa08020
128 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
129 Date: 2010-04-19 14:03:20 +0100
130
131 Redundantly emit ContactsChanged when the contact list becomes available
132
133 Now that it's plural, a state-dump is cheap to do.
134
135 commit e976d367bb18601d5c86ceefc61a56900f24e0eb
136 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
137 Date: 2010-04-19 13:27:15 +0100
138
139 Make ContactsChanged plural, and make it include ContactsRemoved
140
141 commit d5710bd4a8e63646d7ba5545632b930fa77fbbf9
142 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
143 Date: 2010-05-21 15:37:41 +0100
144
145 Make ContactList reference Aliasing instead of Names for alias-setting
146
147 commit efff3f44abe5cc0bc00756991fc221952ca4667c
148 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
149 Date: 2010-05-21 15:35:01 +0100
150
151 Remove local alias storage from ContactList - it'll be in the Names interface
152
153 commit 172d9e69f25287cf0497247cd4f30d82d70aa718
154 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
155 Date: 2010-04-19 13:16:31 +0100
156
157 RemoveContacts: split out Unsubscribe, Unpublish methods
158
159 commit 5e9dc5bfa49502a98e2995719ecf7438d8346a20
160 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
161 Date: 2010-04-19 13:13:41 +0100
162
163 RemoveContacts, AuthorizePublication: resolve that we don't need a message
164
165 commit 01b193d5a66c293f0e119796fcdc3ee55c1ba347
166 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
167 Date: 2010-04-12 15:32:34 +0100
168
169 Add Connection.Interface.ContactList draft
170
171 commit 0c3f944eb02b2ba206b88444d94caa11284c2418
172 Author: Will Thompson <will.thompson@collabora.co.uk>
173 Date: 2010-05-20 11:41:27 +0100
174
175 Wording tweaks for Observer.Recover
176
177 commit 6e06e3200068571abe165ecad4e499ccd93da287
178 Author: Will Thompson <will.thompson@collabora.co.uk>
179 Date: 2010-05-20 11:41:03 +0100
180
181 Document BypassApproval and Recover in .client files
182
183 commit 21e16bdeaa72b4a5f95dc61f20765f66d428bcd5
184 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
185 Date: 2010-05-19 14:31:01 +0200
186
187 improve User_Action_Timestamp description and add MAX_INT64 special case
188
189 commit 63ab11124cba06f80ca921e90f8741aeeaa9e534
190 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
191 Date: 2010-05-19 14:14:59 +0200
192
193 User_Action_Timestamp: add reference to _NET_WM_USER_TIME
194
195 commit c17a6bdfc928bb0be8394e7ebf936e4df95e2b86
196 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
197 Date: 2010-05-19 14:11:37 +0200
198
199 rename X_Server_Time to User_Action_Timestamp
200
201 commit e67c4be5b75aa1fc087d8cf3852843cba7bf42a8
202 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
203 Date: 2010-05-19 14:04:56 +0200
204
205 ChannelRequest: make UserActionTime of type X_Server_Time
206
207 commit 9f8767d32997508be5167221d81914f397277437
208 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
209 Date: 2010-05-19 14:03:51 +0200
210
211 ChannelDispatcher: make User_Action_Time of type X_Server_Time
212
213 commit 93e70560b07633cd075abea330147e029235060a
214 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
215 Date: 2010-04-22 09:59:29 +0200
216
217 Client.Handler: improve User_Action_Time description
218
219 commit 10ff986f2b5a71d9532edd1e523e88268805f911
220 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
221 Date: 2010-05-19 13:38:15 +0200
222
223 introduce X_Server_Time simple type
224
225 commit a6e26f06122b56a2c09509d2c867f6ce0048d725
226 Merge: f9d0090 eca0455
227 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
228 Date: 2010-05-18 17:45:54 +0100
229
230 Merge branch 'trivia'
231
232 Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
233
234 commit eca0455941c9341495d12cbc12816a66571f8d57
235 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
236 Date: 2010-05-18 17:40:39 +0100
237
238 Put Mail_Address docstring in the XHTML namespace
239
240 commit dce06a54fdd9dab98ec393f4a0eeb5512c391d9c
241 Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
242 Date: 2010-04-19 11:30:00 -0400
243
244 Mail_Address may contain empty string
245
246 Explained that one of the two items (name, address) in Mail_Address
247 structur may be empty string.
248
249 commit c8d089b5180b20a48165a19e96c294a360f9a7bd
250 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
251 Date: 2010-05-18 17:35:07 +0100
252
253 Update NEWS
254
255 commit f9d009099577ce9a0692a8f3c302dc89fc8bc989
256 Author: Will Thompson <will.thompson@collabora.co.uk>
257 Date: 2010-05-13 17:08:54 +0100
258
259 Add a Location_Feature_Can_Set flag.
260
261 Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=28092
262 Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
263
264 commit a71ae30d90bbf5fa3f0a97f3f480dc3a7649b730
265 Author: Senko Rasic <senko.rasic@collabora.co.uk>
266 Date: 2010-05-09 09:41:48 +0200
267
268 adding {Channel,Connection}.Interface.ServicePoint as a draft
269
270 commit 58b84a451347924a3364cf1b2f098405d74c5163
271 Author: Senko Rasic <senko.rasic@collabora.co.uk>
272 Date: 2010-05-10 19:25:35 +0200
273
274 adding Call.Content.Interface.Mute as draft
275
276 commit 4a8ee9f09615583a18fb661140d744b91208e567
277 Author: Senko Rasic <senko.rasic@collabora.co.uk>
278 Date: 2010-05-10 19:24:19 +0200
279
280 Call: add Muted call flag
281
282 Another attribute of a Call; it could be locally muted. Allow the Call
283 channel to specifically track this.
284
285 Written-by: Andres Salomon <dilinger@collabora.co.uk>
286
287 commit e5a5271037922cd5b3adcd5c5ec94d2de1dc4815
288 Author: Senko Rasic <senko.rasic@collabora.co.uk>
289 Date: 2010-05-10 17:14:26 +0200
290
291 adding Connection.Interface.Forwarding as a draft
292
293 commit 2e509665cfa49ff10b5b211120f39972f2f4636d
294 Author: Senko Rasic <senko.rasic@collabora.co.uk>
295 Date: 2010-05-10 17:13:24 +0200
296
297 added Call_State_Change_Reason_Forwarded
298
299 commit 17b03f467e8e6add213201239b05e41f8bd1460e
300 Author: Senko Rasic <senko.rasic@collabora.co.uk>
301 Date: 2010-04-15 16:58:41 +0200
302
303 Channel.Interface.DTMF: support for multiple/precomposed dial strings
304
305 Addition of MultipleTones method, InitialTones requestable propery, and
306 SendingTones and StoppedTones signals.
307
308 commit d5867bd0fe954449fbd82fc9767316c447220c45
309 Author: Senko Rasic <senko.rasic@collabora.co.uk>
310 Date: 2010-05-06 10:06:13 +0200
311
312 adding Connection.Interface.Cellular as a draft
313
314 commit ec35b057e8cc019c513a3b0882b601a25f93b4b4
315 Author: Senko Rasic <senko.rasic@collabora.co.uk>
316 Date: 2010-05-10 15:13:22 +0200
317
318 adding {Connection,Channel}.Interface.Anonymity as drafts
319
320 commit 78d7f21ac55fce0ee6098f0894c2c7d0213ee403
321 Author: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
322 Date: 2010-05-11 15:18:02 +0200
323
324 Client.Interface.Requests.AddRequest: make the 'Account' property mandatory
325
326 MC always sets it any way.
327
328 commit 7f224c8437afcc1f160987cb5ec65b755a23bbd4
329 Author: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
330 Date: 2010-04-29 03:34:10 -0300
331
332 Added Account.ChangingPresence property.
333
334 commit 33b2f298490fcaf9e0b9f1c333477975be64be84
335 Merge: 1059a5c adf4098
336 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
337 Date: 2010-05-06 15:50:57 +0100
338
339 Merge branch 'tools'
340
341 Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
342
343 commit adf4098012e364aa89c90f3111061a93fac13f35
344 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
345 Date: 2010-05-06 15:39:16 +0100
346
347 specparser: fail on unnamed types that telepathy-qt4 can't support
348
349 commit 3e5db4089adcc0c5039cfcf1f0ff3035bd25d4d5
350 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
351 Date: 2010-05-06 15:38:54 +0100
352
353 specparser: fail on missing added/deprecated/changed versions
354
355 commit 43f3b7b62d1382752229bff5a37a2263e3fb0578
356 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
357 Date: 2010-05-06 15:31:17 +0100
358
359 Disallow <arg> with inappropriate direction
360
361 Explicit is better than implicit.
362
363 commit 4197af75d52c003f7fb4ba291eb13ba23f9e8761
364 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
365 Date: 2010-05-06 15:28:42 +0100
366
367 specparser: forbid empty structs
368
369 The D-Bus Specification would also reject them.
370
371 commit afddfa3c8855cf1724df95c69b56b416c7846e21
372 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
373 Date: 2010-04-07 19:28:57 +0100
374
375 Display the errors section's introduction in the HTML
376
377 commit 581ee23c6787ae63098d1d8eec893f0664d9996e
378 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
379 Date: 2010-04-07 19:18:15 +0100
380
381 Sort errors by name in output
382
383 commit f1476559065502fd31ec32092913b6c07e475879
384 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
385 Date: 2009-10-06 21:17:54 +0100
386
387 errors.xml: add an introduction
388
389 commit 26a70b5436d4f1f257e491e7d71b6b1452aff8e2
390 Author: Will Thompson <will.thompson@collabora.co.uk>
391 Date: 2009-11-03 15:56:37 +0000
392
393 Remove make_all_async.py
394
395 I couldn't figure out any way to convince the Makefile to use it, so I
396 figure those sections are vestigial. :-)
397
398 commit 55df1a34ffd306bf4cbce650a7f2375af89673fe
399 Author: Will Thompson <will.thompson@collabora.co.uk>
400 Date: 2009-11-03 15:59:24 +0000
401
402 Remove unused tools
403
404 commit 153ed5c5719bf244c299aa8c953da925770d093c
405 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
406 Date: 2010-05-06 15:22:30 +0100
407
408 List all types in the full index, not just the generic ones
409
410 commit a1154f67f9e7319f8e0d87ad352c7c8161dc85cb
411 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
412 Date: 2010-05-06 15:22:04 +0100
413
414 Name <tp:type>s using their short name
415
416 The named types we use are considered to be a global flat namespace, so
417 the spec HTML should reflect that.
418
419 commit 0b077635485219300c09b6bcea6f9a975c7b1fc9
420 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
421 Date: 2010-05-06 15:10:43 +0100
422
423 fd.o #24085: specparser: check consistency of all typed things' type and tp:type
424
425 commit 1813c95a1436d9e9c9eb213a45cd115d4efc4121
426 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
427 Date: 2010-05-06 15:10:19 +0100
428
429 Correct arity of Capabilities/caps contact attribute's type
430
431 commit 61232eeb09d6c76aa000ff6166f2e20c4dcb7aae
432 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
433 Date: 2010-05-06 15:00:34 +0100
434
435 specparser: check that <tp:mapping> has exactly two <tp:member>s
436
437 commit 1059a5c426aa04efd6277b09c147fcf92ad1d471
438 Author: Will Thompson <will.thompson@collabora.co.uk>
439 Date: 2010-04-30 18:15:45 +0100
440
441 Fix a copy-paste error in ContactInfo/info
442
443 commit 8a033f4af3f28c16e13392af4f0c79b3e58b227b
444 Author: Will Thompson <will.thompson@collabora.co.uk>
445 Date: 2010-04-16 11:15:18 +0100
446
447 Make Spec.license a list of paras, not HTML
448
449 I'm writing a tp-glib generator based on specparser.py and would like it
450 to use the license!
451
452 Reviewed-by: Danielle Madeley <danielle.madeley@collabora.co.uk>
453
454 commit 73737e76ad78ff55783265f621e52efc00b679b4
455 Merge: fd72acd 9dca92e
456 Author: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
457 Date: 2010-04-30 14:04:25 -0300
458
459 Merge branch 'contact-info-attr'
460
461 Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
462
463 commit 9dca92e8e4771cde9e2f3a4c08e69925f198d8e5
464 Author: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
465 Date: 2010-04-30 13:47:58 -0300
466
467 Added /info contact-attribute to ContactInfo interface.
468
469 commit fd72acdad39015aacf84be58174d1a12eb827389
470 Author: Jonny Lamb <jonny.lamb@collabora.co.uk>
471 Date: 2010-04-16 23:30:35 +0100
472
473 messages: add sender-nickname as a well-known key
474
475 Fixes fd.o#27568
476
477 Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
478
479 commit 3015eda2b8b051c73aa595f20871f3713e225ac4
480 Author: Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
481 Date: 2010-04-15 18:45:26 -0300
482
483 Added missing tp:type definitions to make tp-qt4 code generator happy.
484
485 Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
486
487 commit c6f4c8f1a45ddf40abc073a941d5cc89e86b26c4
488 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
489 Date: 2010-04-16 12:44:26 +0100
490
491 Nano version
492
0493 commit c64c59d6993a9d89e49bba86f0850af9b86b029d
1494 Author: Simon McVittie <simon.mcvittie@collabora.co.uk>
2495 Date: 2010-04-15 22:11:43 +0100
+2
-11
Makefile less more
1313 TEMPLATES = $(wildcard doc/templates/*)
1414 INTERFACE_XMLS = $(filter spec/[[:upper:]]%.xml,$(XMLS))
1515 INTROSPECT = $(INTERFACE_XMLS:spec/%.xml=introspect/%.xml)
16 ASYNC_INTROSPECT = $(INTERFACE_XMLS:spec/%.xml=introspect/async/%.xml)
1716 CANONICAL_NAMES = $(INTERFACE_XMLS:spec/%.xml=tmp/%.name)
1817
1918 $(CANONICAL_NAMES): tmp/%.name: spec/%.xml tools/extract-nodename.py
2625 TEST_XMLS = $(wildcard test/input/*.xml)
2726 TEST_INTERFACE_XMLS = test/input/_Test.xml
2827 TEST_INTROSPECT = test/output/_Test.introspect.xml
29 TEST_GENERATED_FILES = \
30 $(TEST_INTROSPECT) $(TEST_ASYNC_INTROSPECT)
28 TEST_GENERATED_FILES = $(TEST_INTROSPECT)
3129
3230 RST = \
3331 doc/cmcaps.txt \
4442 doc/spec.html \
4543 doc/spec/index.html \
4644 doc/telepathy-spec.devhelp2 \
47 $(INTROSPECT) $(ASYNC_INTROSPECT) \
45 $(INTROSPECT) \
4846 $(CANONICAL_NAMES)
4947
5048 doc/spec.html: doc/templates/oldspec.html
6563 $(TEST_INTROSPECT): $(TEST_INTERFACE_XMLS) tools/spec-to-introspect.xsl
6664 @install -d test/output
6765 $(XSLTPROC) tools/spec-to-introspect.xsl $< | $(DROP_NAMESPACE) > $@
68
69 $(ASYNC_INTROSPECT): introspect/async/%.xml: introspect/%.xml tools/make_all_async.py
70 @install -d introspect/async
71 python tools/make_all_async.py $< $@
72 $(TEST_ASYNC_INTROSPECT): $(TEST_INTROSPECT) tools/make_all_async.py
73 @install -d test/output
74 python tools/make_all_async.py $< $@
7566
7667 all: $(GENERATED_FILES)
7768 @echo "Your spec HTML starts at:"
+76
-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 "git log" in Git
22 checkouts.
3
4 telepathy-spec 0.19.6 (2010-05-25)
5 ==================================
6
7 The "minor bun engine" release.
8
9 Changes to stable API:
10
11 * The Account property must be set when calling AddRequest. This was already
12 true whenever Mission Control called this method. (cassidy)
13
14 * The timestamps used for "user action time", which were intended for
15 focus-stealing prevention, turned out not to be suitable for the intended
16 purpose if they were Unix timestamps. Their semantics have been changed to
17 be X server time on X GUI platforms, or undefined otherwise, with 0 and
18 2**31-1 as special values. (cassidy)
19
20 New stable API:
21
22 * fd.o #28092: SupportedLocationFeatures property, with a Can_Set flag (wjt)
23
24 * Contact info is now available as a ".../info" contact attribute (andrunko)
25
26 * support for multiple/precomposed dial strings in the DTMF interface (ptlo)
27
28 * sender-nickname as a key in message headers (jonny)
29
30 * a specified serialization for Recover and BypassApproval in .client files
31 (wjt)
32
33 * Account.ChangingPresence property, which is true when attempts are being
34 made to change the account's presence (andrunko)
35
36 * ChannelDispatchOperation.HandleWithTime method, which is like HandleWith
37 but takes a user action time argument (cassidy)
38
39 New experimental API:
40
41 * ServicePoint interfaces (draft 1) for emergency contact points (dilinger/ptlo)
42
43 * Mute interface (draft 1) for muting calls (dilinger/ptlo)
44
45 * Forwarding interface (draft 1) for call-forwarding (ptlo)
46
47 * Cellular interface (draft 1) for miscellaneous cellular-specific
48 functionality (ptlo)
49
50 * Anonymity interfaces (draft 1) for anonymity enhancements such as disabling
51 caller-ID (ptlo)
52
53 * ContactList and ContactGroups interfaces (draft 1) to replace the ContactList
54 channel type (smcv)
55
56 Fixes:
57
58 * Add some tp:type annotations to Call where needed for telepathy-qt4
59 (andrunko)
60
61 * Annotate the "...Capabilities/caps" contact attribute's tp:type correctly
62 (smcv)
63
64 Tools changes:
65
66 * specparser: numerous extra sanity checks (smcv)
67 - fd.o #24085: check consistency of type and tp:type
68 - require types to be interoperable with telepathy-qt4 (they must either
69 be on the list of types it supports specifically, or have a tp:type)
70 - disallow empty structs, which are not allowed in current D-Bus
71 - disallow unversioned added/deprecated/changed annotations
72 - disallow <arg> with an inappropriate direction
73 - disallow <tp:mapping> with fewer or more than two members
74
75 * specparser: name <tp:type>s with their short name, since conceptually they
76 form a global flat namespace, and list them all in the index (smcv)
77
78 * Remove various tools that are no longer used (wjt)
379
480 telepathy-spec 0.19.5 (2010-04-15)
581 ==================================
+6
-2
doc/templates/errors.html less more
1717 <a name="summary"></a>
1818 <h3>Errors</h3>
1919 <table class="summary">
20 #for $error in $spec.errors.values()
20 #for $error in $spec.sorted_errors
2121 #if $error.deprecated
2222 <tr class="deprecated">
2323 #else
3232 </table>
3333 </div>
3434
35 #if $spec.errors_section
36 $spec.errors_section.get_docstring()
37 #end if
38
3539 <div class="outset errors error">
3640 <a name="errors"></a>
3741 <h1>Errors</h1>
38 #for $error in $spec.errors.values()
42 #for $error in $spec.sorted_errors
3943 <div class="inset error">
4044 <a name="$error.name"></a>
4145 <span class="permalink">(<a href="$error.get_url()">Permalink</a>)</span>
+1
-1
doc/templates/fullindex.html less more
77 </head>
88
99 #set $star = []
10 #for $item in $spec.everything.values() + $spec.errors.values() + $spec.generic_types
10 #for $item in $spec.everything.values() + $spec.errors.values() + $spec.types.values()
1111 #echo $star.append(($item.short_name, $item))
1212 #slurp
1313 #end for
+6
-1
doc/templates/index.html less more
1919 <p class="copyrights">
2020 #echo '<br/>'.join($spec.copyrights)
2121 </p>
22 $spec.license
22
23 <div class="license">
24 #for $para in $spec.license
25 <p>$para</p>
26 #end for
27 </div>
2328
2429 <a name="interfaces"></a>
2530 <h3>Interfaces</h3>
+6
-6
doc/templates/interface.html less more
4444 #end for
4545 </table>
4646 #end if
47
47
4848 #if $interface.signals
4949 <h3>Signals</h3>
5050 <table class="summary">
215215 </ul>
216216 </div>
217217 #end if
218
218
219219 #if $method.out_args
220220 <div class="indent">
221221 <h3>Returns</h3>
233233 </ul>
234234 </div>
235235 #end if
236
236
237237 $method.get_docstring()
238
238
239239 #if $method.possible_errors
240240 <hr/>
241241 <div class="indent">
255255 #end for
256256 </div>
257257 #end if
258
258
259259 #if $interface.signals
260260 <div class="outset signals signal">
261261 <a name="signals"></a>
416416 #end for
417417 </div>
418418 #end if
419
419
420420 </div>
421421
422422 </body>
+38
-0
spec/Account.xml less more
479479 </tp:docstring>
480480 </property>
481481
482 <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence"
483 type="b" access="read">
484 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
485 <p>If true, a change to the presence of this account is
486 in progress.</p>
487
488 <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on
489 an account that could go online, or whenever an account with a
490 non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes
491 able to go online (for instance because
492 <tp:member-ref>Enabled</tp:member-ref> or
493 <tp:member-ref>Valid</tp:member-ref> changes to True),
494 ChangingPresence MUST change to True, and the two property changes MUST
495 be emitted in the same
496 <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the
497 Set method returns.</p>
498
499 <p>When the account manager succeeds or fails in changing the presence,
500 or the connection disconnects due to an error, ChangingPresence MUST
501 change to False as part of the same
502 <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p>
503
504 <tp:rationale>
505 <p>This allows UIs to indicate that a presence change is in progress
506 or has finished, even if the change was initiated by a different
507 UI.</p>
508
509 <p>For instance, Maemo 5 and Empathy indicate a presence change by
510 having the presence indicator alternate between the
511 <tp:member-ref>RequestedPresence</tp:member-ref>
512 and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should
513 start blinking when ChangingPresence becomes true, and stop when it
514 becomes false.</p>
515 </tp:rationale>
516
517 </tp:docstring>
518 </property>
519
482520 <method name="Reconnect" tp:name-for-bindings="Reconnect">
483521 <tp:added version="0.17.24"/>
484522 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+1
-1
spec/Call_Content_Interface_Media.xml less more
6060 </tp:docstring>
6161 </tp:member>
6262
63 <tp:member name="Parameters" type="a{ss}">
63 <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map">
6464 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
6565 Extra parameters for this codec
6666 </tp:docstring>
+83
-0
spec/Call_Content_Interface_Mute.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
3 <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
4 <tp:license xmlns="http://www.w3.org/1999/xhtml">
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 </tp:license>
19
20 <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental">
21 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
22
23 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
24 <p>Interface for calls which may be muted. This only makes sense
25 for channels where audio or video is streaming between members.</p>
26
27 <p>Muting a call content indicates that the user does not wish to send
28 outgoing audio or video.</p>
29
30 <p>Although it's client's responsibility to actually mute the microphone
31 or turn off the camera, using this interface the client can also
32 inform the CM and other clients of that fact.</p>
33 <tp:rationale>
34 <p>For some protocols, the fact that the content is muted needs to be
35 transmitted to the peer; for others, the notification to the peer is
36 only informational (eg. XMPP), and some protocols may have no notion
37 of muting at all.</p>
38 </tp:rationale>
39 </tp:docstring>
40
41 <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed">
42 <tp:docstring>
43 Emitted to indicate that the mute state has changed for this call content.
44 This may occur as a consequence of the client calling
45 <tp:member-ref>Muted</tp:member-ref>, or as an indication that another
46 client has (un)muted the content.
47 </tp:docstring>
48
49 <arg name="MuteState" type="b">
50 <tp:docstring>
51 True if the content is now muted.
52 </tp:docstring>
53 </arg>
54 </signal>
55
56 <property name="MuteState" type="b"
57 access="read" tp:name-for-bindings="Mute_State">
58 <tp:docstring>
59 True if the content is muted.
60 </tp:docstring>
61 </property>
62
63 <method name="Muted" tp:name-for-bindings="Muted">
64 <arg direction="in" name="Muted" type="b">
65 <tp:docstring>
66 True if the client has muted the content.
67 </tp:docstring>
68 </arg>
69
70 <tp:docstring>
71 <p>Inform the CM that the call content has been muted or unmuted by
72 che client.</p>
73
74 <p>It is the client's responsibility to actually mute or unmute the
75 microphone or camera used for the content. However, the client
76 MUST call this whenever it mutes or unmutes the content.</p>
77 </tp:docstring>
78 </method>
79
80 </interface>
81 </node>
82 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+66
-0
spec/Channel_Dispatch_Operation.xml less more
369369 </tp:possible-errors>
370370 </method>
371371
372 <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time">
373 <tp:added version="0.19.6">
374 At the time of writing, no released implementation of the
375 Channel Dispatcher implements this method; clients should fall
376 back to calling <tp:member-ref>HandleWith</tp:member-ref>.
377 </tp:added>
378 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
379 <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the
380 approver to pass an user action time. This timestamp will be passed
381 to the Handler when <tp:dbus-ref
382 namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
383 is called.</p>
384 </tp:docstring>
385
386 <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
387 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
388 <p>The well-known bus name (starting with
389 <code>org.freedesktop.Telepathy.Client.</code>) of the channel
390 handler that should handle the channel, or the empty string
391 if the client has no preferred channel handler.</p>
392 </tp:docstring>
393 </arg>
394
395 <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime">
396 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
397 <p>The time at which user action occurred.</p>
398 </tp:docstring>
399 </arg>
400
401 <tp:possible-errors>
402 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
403 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
404 The selected handler is non-empty, but is not a syntactically
405 correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
406 "<code>org.freedesktop.Telepathy.Client.</code>".
407 </tp:docstring>
408 </tp:error>
409 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
410 <tp:docstring>
411 The selected handler is temporarily unable to handle these
412 channels.
413 </tp:docstring>
414 </tp:error>
415 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
416 <tp:docstring>
417 The selected handler is syntactically correct, but will never
418 be able to handle these channels (for instance because the channels
419 do not match its HandlerChannelFilter, or because HandleChannels
420 raised NotImplemented).
421 </tp:docstring>
422 </tp:error>
423 <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
424 <tp:docstring>
425 At the time that HandleWith was called, this dispatch operation was
426 processing an earlier call to HandleWith. The earlier call has
427 now succeeded, so some Handler nominated by another approver is
428 now responsible for the channels. In this situation, the second
429 call to HandleWith MUST NOT return until the first one has
430 returned successfully or unsuccessfully, and if the first call
431 to HandleChannels fails, the channel dispatcher SHOULD try to obey
432 the choice of Handler made by the second call to HandleWith.
433 </tp:docstring>
434 </tp:error>
435 </tp:possible-errors>
436 </method>
437
372438 <signal name="Finished" tp:name-for-bindings="Finished">
373439 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
374440 <p>Emitted when this dispatch operation finishes. The dispatch
+2
-2
spec/Channel_Dispatcher.xml less more
163163 </arg>
164164
165165 <arg direction="in" name="User_Action_Time" type="x"
166 tp:type="Unix_Timestamp64">
166 tp:type="User_Action_Timestamp">
167167 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
168168 <p>The time at which user action occurred, or 0 if this channel
169169 request is for some reason not involving user action.
304304 </arg>
305305
306306 <arg direction="in" name="User_Action_Time" type="x"
307 tp:type="Unix_Timestamp64">
307 tp:type="User_Action_Timestamp">
308308 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
309309 <p>The time at which user action occurred, or 0 if this channel
310310 request is for some reason not involving user action.</p>
+68
-0
spec/Channel_Interface_Anonymity.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Channel_Interface_Anonymity"
2 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
4 <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
5 <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.</p>
11
12 <p>This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.</p>
16
17 <p>You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20 02110-1301, USA.</p>
21 </tp:license>
22
23 <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity.DRAFT"
24 tp:causes-havoc="experimental">
25 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
26
27 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28 <p>Interface for requesting the anonymity modes of a channel
29 (as defined in Connection.Interface.Anonymity.DRAFT).</p>
30 </tp:docstring>
31
32 <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
33 access="read" tp:name-for-bindings="Anonymity_Modes">
34 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
35 The list of initially requested anonymity modes on the channel. This
36 MUST NOT change, and is Requestable.
37 </tp:docstring>
38 </property>
39
40 <property name="AnonymityMandatory" type="b" access="read"
41 tp:name-for-bindings="Anonymity_Mandatory">
42 <tp:docstring>
43 Whether or not the anonymity settings are required for this channel.
44 This MUST NOT change, and is Requestable.
45 </tp:docstring>
46 </property>
47
48 <property name="AnonymousID" type="s" access="read"
49 tp:name-for-bindings="Anonymous_ID">
50 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
51 <p>This is the ID that the remote user of the channel MAY see
52 (assuming there's a single ID). For example, for SIP connections
53 where the From address has been scrambled by the CM, the scrambled
54 address would be available here for the client to see. This is
55 completely optional, and MAY be an empty string ("") in
56 cases where anonymity modes are not set, or the CM doesn't know
57 what the remote contact will see, or any other case where this
58 doesn't make sense.</p>
59
60 <p>This MAY change over the lifetime of the channel, and SHOULD NOT
61 be used with the Request interface.</p>
62 </tp:docstring>
63 </property>
64
65 </interface>
66 </node>
67 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+233
-108
spec/Channel_Interface_DTMF.xml less more
00 <?xml version="1.0" ?>
11 <node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
3 <tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
4 <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
2 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
3 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
4 <tp:copyright>Copyright © 2006 INdT</tp:copyright>
55 <tp:license xmlns="http://www.w3.org/1999/xhtml">
66 <p>This library is free software; you can redistribute it and/or
77 modify it under the terms of the GNU Lesser General Public
1919 </tp:license>
2020 <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF">
2121 <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
22
23 <method name="StartTone" tp:name-for-bindings="Start_Tone">
24 <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
25 <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
26 </arg>
27 <arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
28 <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
29 </arg>
30 <tp:docstring>
31 Start sending a DTMF tone on this stream. Where possible, the tone
32 will continue until <tp:member-ref>StopTone</tp:member-ref> is called.
33 On certain protocols, it may
34 only be possible to send events with a predetermined length. In this
35 case, the implementation may emit a fixed-length tone, and the StopTone
36 method call should return NotAvailable.
37 </tp:docstring>
38 <tp:possible-errors>
39 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
40 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
41 <tp:docstring>
42 The given stream ID was invalid.
43 </tp:docstring>
44 </tp:error>
45 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
46 <tp:docstring>
47 The requested event is not available on this stream.
48 </tp:docstring>
49 </tp:error>
50 </tp:possible-errors>
51 </method>
52
53 <method name="StopTone" tp:name-for-bindings="Stop_Tone">
54 <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
55 <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
56 </arg>
57 <tp:docstring>
58 Stop sending any DTMF tone which has been started using the
59 <tp:member-ref>StartTone</tp:member-ref>
60 method. If there is no current tone, this method will do nothing.
61 </tp:docstring>
62 <tp:possible-errors>
63 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
64 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
65 <tp:docstring>
66 The given stream ID was invalid.
67 </tp:docstring>
68 </tp:error>
69 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
70 <tp:docstring>
71 Continuous tones are not supported by this stream.
72 </tp:docstring>
73 </tp:error>
74 </tp:possible-errors>
75 </method>
76
77 <tp:enum name="DTMF_Event" type="y">
78 <tp:enumvalue suffix="Digit_0" value="0">
79 <tp:docstring>0</tp:docstring>
80 </tp:enumvalue>
81 <tp:enumvalue suffix="Digit_1" value="1">
82 <tp:docstring>1</tp:docstring>
83 </tp:enumvalue>
84 <tp:enumvalue suffix="Digit_2" value="2">
85 <tp:docstring>2</tp:docstring>
86 </tp:enumvalue>
87 <tp:enumvalue suffix="Digit_3" value="3">
88 <tp:docstring>3</tp:docstring>
89 </tp:enumvalue>
90 <tp:enumvalue suffix="Digit_4" value="4">
91 <tp:docstring>4</tp:docstring>
92 </tp:enumvalue>
93 <tp:enumvalue suffix="Digit_5" value="5">
94 <tp:docstring>5</tp:docstring>
95 </tp:enumvalue>
96 <tp:enumvalue suffix="Digit_6" value="6">
97 <tp:docstring>6</tp:docstring>
98 </tp:enumvalue>
99 <tp:enumvalue suffix="Digit_7" value="7">
100 <tp:docstring>7</tp:docstring>
101 </tp:enumvalue>
102 <tp:enumvalue suffix="Digit_8" value="8">
103 <tp:docstring>8</tp:docstring>
104 </tp:enumvalue>
105 <tp:enumvalue suffix="Digit_9" value="9">
106 <tp:docstring>9</tp:docstring>
107 </tp:enumvalue>
108 <tp:enumvalue suffix="Asterisk" value="10">
109 <tp:docstring>*</tp:docstring>
110 </tp:enumvalue>
111 <tp:enumvalue suffix="Hash" value="11">
112 <tp:docstring>#</tp:docstring>
113 </tp:enumvalue>
114 <tp:enumvalue suffix="Letter_A" value="12">
115 <tp:docstring>A</tp:docstring>
116 </tp:enumvalue>
117 <tp:enumvalue suffix="Letter_B" value="13">
118 <tp:docstring>B</tp:docstring>
119 </tp:enumvalue>
120 <tp:enumvalue suffix="Letter_C" value="14">
121 <tp:docstring>C</tp:docstring>
122 </tp:enumvalue>
123 <tp:enumvalue suffix="Letter_D" value="15">
124 <tp:docstring>D</tp:docstring>
125 </tp:enumvalue>
126 </tp:enum>
12722
12823 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
12924 An interface that gives a Channel the ability to send DTMF events over
13328 listed in the <tp:type>DTMF_Event</tp:type> enumeration.
13429 </tp:docstring>
13530
31 <method name="StartTone" tp:name-for-bindings="Start_Tone">
32 <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
33 <tp:docstring>A stream ID as defined in the StreamedMedia channel
34 type. This argument is included for backwards compatibility and MUST
35 be ignored by the implementations - the tone SHOULD be sent to all
36 eligible streams in the channel.</tp:docstring>
37 </arg>
38 <arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
39 <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
40 </arg>
41
42 <tp:docstring>
43 <p>Start sending a DTMF tone to all eligible streams in the channel.
44 Where possible, the tone will continue until
45 <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols,
46 it may only be possible to send events with a predetermined length. In
47 this case, the implementation MAY emit a fixed-length tone, and the
48 StopTone method call SHOULD return NotAvailable.</p>
49 <tp:rationale>
50 The client may wish to control the exact duration and timing of the
51 tones sent as a result of user's interaction with the dialpad, thus
52 starting and stopping the tone sending explicitly.
53 </tp:rationale>
54
55 <p>Tone overlaping or queueing is not supported, so this method can only
56 be called if no DTMF tones are already being played.</p>
57 </tp:docstring>
58 <tp:possible-errors>
59 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
60 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
61 <tp:docstring>
62 The given stream ID was invalid. Deprecated, since stream IDs
63 are ignored.
64 </tp:docstring>
65 </tp:error>
66 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
67 <tp:docstring>
68 There are no eligible audio streams.
69 </tp:docstring>
70 </tp:error>
71 <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
72 <tp:docstring>
73 DTMF tones are already being played.
74 </tp:docstring>
75 </tp:error>
76 </tp:possible-errors>
77 </method>
78
79 <method name="StopTone" tp:name-for-bindings="Stop_Tone">
80 <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
81 <tp:docstring>A stream ID as defined in the StreamedMedia channel
82 type. This argument is included for backwards compatibility and MUST
83 be ignored by the implementations - the sending SHOULD be stoped in
84 all eligible streams in the channel.</tp:docstring>
85 </arg>
86
87 <tp:docstring>
88 Stop sending any DTMF tones which have been started using the
89 <tp:member-ref>StartTone</tp:member-ref> or
90 <tp:member-ref>MultipleTones</tp:member-ref> methods.
91 If there is no current tone, this method will do nothing.
92 If MultipleTones was used, the client should not assume the
93 sending has stopped immediately; instead, the client should wait
94 for the StoppedTones signal.
95 <tp:rationale>
96 On some protocols it might be impossible to cancel queued tones
97 immediately.
98 </tp:rationale>
99 </tp:docstring>
100 <tp:possible-errors>
101 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
102 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
103 <tp:docstring>
104 The given stream ID was invalid. Deprecated, since stream IDs
105 are ignored.
106 </tp:docstring>
107 </tp:error>
108 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
109 <tp:docstring>
110 Continuous tones are not supported by this stream. Deprecated,
111 since stream IDs are ignored.
112 </tp:docstring>
113 </tp:error>
114 </tp:possible-errors>
115 </method>
116
117 <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones">
118 <tp:added version="0.19.6" />
119 <arg direction="in" name="Tones" type="s">
120 <tp:docstring>A string representation of one or more DTMF
121 events.</tp:docstring>
122 </arg>
123 <tp:docstring>
124 <p>Send multiple DTMF events to all eligible streams in the channel.
125 Each character in the Tones string must be a valid DTMF event
126 (as defined by
127 <a href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>).
128 Each tone will be played for a pre-defined number of milliseconds,
129 followed by a pause before the next tone is played. The
130 duration/pause is defined by the protocol or connection manager.</p>
131 <tp:rationale>
132 In cases where the client knows in advance the tone sequence it wants
133 to send, it's easier to use this method than manually start and stop
134 each tone in the sequence.
135 </tp:rationale>
136
137 <p>Tone overlaping or queueing is not supported, so this method can only
138 be called if no DTMF tones are already being played.</p>
139 </tp:docstring>
140 <tp:possible-errors>
141 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
142 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
143 <tp:docstring>
144 The supplied Tones string was invalid.
145 </tp:docstring>
146 </tp:error>
147 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
148 <tp:docstring>
149 There are no eligible audio streams.
150 </tp:docstring>
151 </tp:error>
152 <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
153 <tp:docstring>
154 DTMF tones are already being played.
155 </tp:docstring>
156 </tp:error>
157 </tp:possible-errors>
158 </method>
159
160 <property name="CurrentlySendingTones"
161 tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read">
162 <tp:added version="0.19.6" />
163 <tp:docstring>
164 Indicates whether there are DTMF tones currently being sent in the
165 channel. If so, the client should wait for
166 <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to
167 send more tones.
168 </tp:docstring>
169 </property>
170
171 <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
172 type="s" access="read">
173 <tp:added version="0.19.6" />
174 <tp:docstring>
175 <p>If non-empty in a channel request that will create a new channel,
176 the connection manager should send the tones immediately after
177 at least one eligible audio stream has been created in the
178 channel.</p>
179
180 <p>This property is immutable (cannot change).</p>
181 </tp:docstring>
182 </property>
183
184 <signal name="SendingTones" tp:name-for-bindings="Sending_Tones">
185 <tp:added version="0.19.6" />
186 <arg name="Tones" type="s">
187 <tp:docstring>DTMF string (one or more events) that is to be played.
188 </tp:docstring>
189 </arg>
190 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
191 <p>DTMF tone(s)are being sent to all eligible streams in the channel.
192 The signal is provided to indicating the fact that the streams are
193 currently being used to send one or more DTMF tones, so any other
194 media input is not getting through to the audio stream. It also
195 serves as a cue for the
196 <tp:member-ref>StopTone</tp:member-ref> method.</p>
197 </tp:docstring>
198 </signal>
199
200 <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones">
201 <tp:added version="0.19.6" />
202 <arg name="Cancelled" type="b">
203 <tp:docstring>True if the DTMF tones were actively cancelled via
204 <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring>
205 </arg>
206 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
207 <p>DTMF tones have finished playing on streams in this channel.</p>
208 </tp:docstring>
209 </signal>
210
211 <tp:enum name="DTMF_Event" type="y">
212 <tp:enumvalue suffix="Digit_0" value="0">
213 <tp:docstring>0</tp:docstring>
214 </tp:enumvalue>
215 <tp:enumvalue suffix="Digit_1" value="1">
216 <tp:docstring>1</tp:docstring>
217 </tp:enumvalue>
218 <tp:enumvalue suffix="Digit_2" value="2">
219 <tp:docstring>2</tp:docstring>
220 </tp:enumvalue>
221 <tp:enumvalue suffix="Digit_3" value="3">
222 <tp:docstring>3</tp:docstring>
223 </tp:enumvalue>
224 <tp:enumvalue suffix="Digit_4" value="4">
225 <tp:docstring>4</tp:docstring>
226 </tp:enumvalue>
227 <tp:enumvalue suffix="Digit_5" value="5">
228 <tp:docstring>5</tp:docstring>
229 </tp:enumvalue>
230 <tp:enumvalue suffix="Digit_6" value="6">
231 <tp:docstring>6</tp:docstring>
232 </tp:enumvalue>
233 <tp:enumvalue suffix="Digit_7" value="7">
234 <tp:docstring>7</tp:docstring>
235 </tp:enumvalue>
236 <tp:enumvalue suffix="Digit_8" value="8">
237 <tp:docstring>8</tp:docstring>
238 </tp:enumvalue>
239 <tp:enumvalue suffix="Digit_9" value="9">
240 <tp:docstring>9</tp:docstring>
241 </tp:enumvalue>
242 <tp:enumvalue suffix="Asterisk" value="10">
243 <tp:docstring>*</tp:docstring>
244 </tp:enumvalue>
245 <tp:enumvalue suffix="Hash" value="11">
246 <tp:docstring>#</tp:docstring>
247 </tp:enumvalue>
248 <tp:enumvalue suffix="Letter_A" value="12">
249 <tp:docstring>A</tp:docstring>
250 </tp:enumvalue>
251 <tp:enumvalue suffix="Letter_B" value="13">
252 <tp:docstring>B</tp:docstring>
253 </tp:enumvalue>
254 <tp:enumvalue suffix="Letter_C" value="14">
255 <tp:docstring>C</tp:docstring>
256 </tp:enumvalue>
257 <tp:enumvalue suffix="Letter_D" value="15">
258 <tp:docstring>D</tp:docstring>
259 </tp:enumvalue>
260 </tp:enum>
136261 </interface>
137262 </node>
138263 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+4
-0
spec/Channel_Interface_Messages.xml less more
312312 <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>)</dt>
313313 <dd>The contact who sent the message. If 0 or omitted, the contact
314314 who sent the message could not be determined.</dd>
315
316 <dt>sender-nickname (s)</dt>
317 <dd>The nickname chosen by the sender of the message, which can be
318 different for each message in a conversation.</dd>
315319
316320 <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>)
317321 </dt>
+85
-0
spec/Channel_Interface_Service_Point.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
3 <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
4 <tp:license xmlns="http://www.w3.org/1999/xhtml">
5 <p>This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.</p>
9
10 <p>This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.</p>
14
15 <p>You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
18 </tp:license>
19 <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental">
20 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
21
22 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
23 <p>An interface for channels
24 that can indicate when/if they are connected to some form
25 of service point. For example, when
26 dialing 9-1-1 in the US, a GSM modem/network will recognize that as
27 an emergency call, and inform higher levels of the stack that the
28 call is being handled by an emergency service. In this example,
29 the call is handled by a Public Safety Answering Point (PSAP) which is labeled
30 as "urn:service:sos". Other networks and protocols may handle this
31 differently while still using this interface.</p>
32
33 <p>Note that while the majority of examples given in this
34 documentation are for GSM calls, they could just as easily be
35 SIP calls, GSM SMS's, etc.</p>
36 </tp:docstring>
37
38 <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point"
39 type="(us)" tp:type="Service_Point" access="read">
40 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
41 <p>This property is used to indicate that the channel target is a
42 well-known service point. Please note that the CM (or lower layers
43 of the stack or network) may forward the connection to other other
44 service points, which the CM SHOULD indicate via
45 <tp:member-ref>ServicePointChanged</tp:member-ref>
46 signal.</p>
47
48 <p>This property SHOULD be set for channel requests that are
49 specifically targeting service points.</p>
50 </tp:docstring>
51 </property>
52
53 <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point"
54 type="(us)" tp:type="Service_Point" access="read">
55 <tp:docstring>
56 The service point that the channel is connected to. If the channel is
57 not connected to any service points, the CM MUST set the
58 <tp:type>Service_Point_Type</tp:type> field to None.
59 </tp:docstring>
60 </property>
61
62 <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed">
63 <tp:docstring>
64 <p>Emitted when a channel changes the service point that it's connected to. This
65 might be a new call being connected to a service, a call connected to
66 a service being routed to a different service
67 (ie, an emergency call being routed from a generic emergency PSAP to
68 a poison control PSAP), or any number of other things.</p>
69
70 <p>Note that this should be emitted as soon as the CM has been notified
71 of the switch, and has updated its internal state. The CM MAY still
72 be in the process of connecting to the new service point.</p>
73 </tp:docstring>
74
75 <arg name="ServicePoint" type="(us)" tp:type="Service_Point">
76 <tp:docstring>
77 The new service point that is being used.
78 </tp:docstring>
79 </arg>
80 </signal>
81
82 </interface>
83 </node>
84 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+1
-4
spec/Channel_Request.xml less more
5454 </property>
5555
5656 <property name="UserActionTime" tp:name-for-bindings="User_Action_Time"
57 type="x" tp:type="Unix_Timestamp64" access="read">
57 type="x" tp:type="User_Action_Timestamp" access="read">
5858 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
5959 <p>The time at which user action occurred, or 0 if this channel
6060 request is for some reason not involving user action.</p>
61
62 <p>This corresponds to the _NET_WM_USER_TIME property in
63 <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
6461
6562 <p>This property is set when the channel request is created,
6663 and can never change.</p>
+20
-1
spec/Channel_Type_Call.xml less more
380380 </tp:rationale>
381381 </tp:docstring>
382382 </tp:flag>
383
384 <tp:flag suffix="Muted" value="64">
385 <tp:docstring>
386 The call has been muted by the local user, e.g. using the
387 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content.Interface"
388 >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only be set if
389 there is at least one Content, and all Contents are locally muted;
390 it makes sense on calls in state Call_State_Pending_Receiver or
391 Call_State_Accepted.
392 </tp:docstring>
393 </tp:flag>
383394 </tp:flags>
384395
385396 <property name="CallStateDetails"
476487 rejected as busy, kicked from a conference by a moderator, etc.).</p>
477488 </tp:docstring>
478489 </tp:enumvalue>
490
491 <tp:enumvalue suffix="Forwarded" value="2">
492 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
493 <p>The call was forwarded. If known, the handle of the contact
494 the call was forwarded to will be indicated by the Actor member
495 of a <tp:type>Call_State_Reason</tp:type> struct.</p>
496 </tp:docstring>
497 </tp:enumvalue>
479498 </tp:enum>
480499
481500 <tp:struct name="Call_State_Reason">
556575 </tp:docstring>
557576 </arg>
558577
559 <arg name="Call_State_Reason" type="(uus)">
578 <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason">
560579 <tp:docstring>
561580 The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
562581 property.
+10
-0
spec/Client_Handler.xml less more
105105 matches closely related Text channels by their Bundle property.
106106 (This is use-case dis5)</p>
107107 </tp:rationale>
108
109 <p>For service-activatable handlers, this property should be specified
110 in the handler's <tt>.client</tt> file as follows:</p>
111
112 <pre>
113 [org.freedesktop.Telepathy.Client.Handler]
114 BypassApproval=true
115 </pre>
108116 </tp:docstring>
109117 </property>
110118
263271 is to be handled for some reason not involving user action.
264272 Handlers SHOULD use this for focus-stealing prevention,
265273 if applicable.
274 This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type>
275 but is unsigned for historical reasons.
266276 </tp:docstring>
267277 </arg>
268278
+4
-2
spec/Client_Interface_Requests.xml less more
118118 properties as possible, given that constraint.</p>
119119
120120 <p>In particular, the properties <tp:dbus-ref
121 namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>
121 namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>,
122 <tp:dbus-ref
123 namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
122124 and <tp:dbus-ref
123 namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
125 namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref>
124126 MUST be included.</p>
125127 </tp:docstring>
126128 </arg>
+18
-7
spec/Client_Observer.xml less more
193193 its <tp:dbus-ref
194194 namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
195195
196 <p>When activatable client having this property disappears from the bus
197 and there are channels matching its ObserverChannelFilter,
198 ObserveChannels will be called immediately to reactivate it again.</p>
196 <p>When an activatable client having this property disappears from the
197 bus and there are channels matching its ObserverChannelFilter,
198 ObserveChannels will be called immediately to reactivate it
199 again. Such clients should specify this property in their
200 <tt>.client</tt> file as follows:</p>
201
202 <pre>
203 [org.freedesktop.Telepathy.Client.Observer]
204 Recover=true
205 </pre>
206
199207 <tp:rationale>
200208 <p>This means that if an activatable Observer crashes, it will
201209 be restarted as soon as possible; while there is an unavoidable
211219 </tp:rationale>
212220
213221 <p>When the ObserveChannels method is called due to observer recovery,
214 the "Observer_Info" dictionary will contain one extra item with key
215 "recovering" and boolean value of True.</p>
222 the <var>Observer_Info</var> dictionary will contain one extra item
223 mapping the key <code>"recovering"</code> to <code>True</code>.</p>
216224 </tp:docstring>
217225 </property>
218226
335343
336344 <dl>
337345 <dt><code>recovering</code> - b</dt>
338 <dd>True if ObserveChannels was called on existing channel due to
339 observer recovery, otherwise False.
346 <dd><code>True</code> if ObserveChannels was called for an existing
347 channel (due to the <tp:member-ref>Recover</tp:member-ref>
348 property being <code>True</code>); <code>False</code> or omitted
349 otherwise.
350
340351 <tp:rationale>
341352 This allows observers to distinguish between new channels (the normal
342353 case), and existing channels that were given to the observer in order
+170
-0
spec/Connection_Interface_Anonymity.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Anonymity"
2 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
4 <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
5 <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.</p>
11
12 <p>This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.</p>
16
17 <p>You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20 02110-1301, USA.</p>
21 </tp:license>
22
23 <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity.DRAFT"
24 tp:causes-havoc="experimental">
25 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
26
27 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28 <p>An interface to support anonymity settings on a per-connection basis.
29 This defines what personal identifying information a remote contact
30 may or may not see. For example, GSM might use this for CLIR, while
31 SIP might use this for privacy service requests.</p>
32 </tp:docstring>
33
34 <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u">
35 <tp:docstring>
36 <p>Flags for the various types of anonymity modes. These modes are solely to
37 inform the CM of the desired anonymous settings. It is up to the
38 CM to determine whether the anonymity modes should be handled within
39 the CM itself, or whether the network that a CM might be talking to
40 should be enforcing anonymity.</p>
41
42 <p>CMs MAY support only a subset of these modes, and specific
43 connections MAY support none at all.</p>
44 </tp:docstring>
45
46 <tp:flag value="1" suffix="Client_Info">
47 <tp:docstring>
48 <p>Obscure any information that provides user identification,
49 user-agent identification or personal details. Examples of this
50 information might be GSM CallerID, SIP from address, various
51 informational email headers, etc.</p>
52
53 <p>The CM should scrub/replace any of this information before
54 passing messages or data onto the network. Note that a CM which
55 has the option of obscuring the information at the CM or privacy
56 service level would choose both (anonymity services are opaque
57 to clients of this interface).</p>
58
59 <p>Clients SHOULD NOT set both Client_Info and ShowClient_Info modes.
60 If they are set, the CM MUST respect Client_Info and ignore
61 Show_Client_Info.</p>
62 </tp:docstring>
63 </tp:flag>
64
65 <tp:flag value="2" suffix="Show_Client_Info">
66 <tp:docstring>
67 <p>Explicitly request showing of client information. In connection
68 context, this can be used to override service default. In channel
69 context, this overrides connection anonymity modes.</p>
70 <tp:rationale>
71 In GSM, it's possible to have CLIR enabled by default, and
72 explicitly suppress CLIR for a single phone call.
73 </tp:rationale>
74
75 <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
76 If they are set, the CM MUST respect Client_Info and ignore
77 ShowClientInfo. The CM MAY set both Client_Info and Show_Client_Info
78 in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate
79 its support for explicitly hiding and publicising client information.
80 </p>
81 </tp:docstring>
82 </tp:flag>
83
84 <tp:flag value="4" suffix="Network_Info">
85 <tp:docstring>
86 <p>Obscure any originating IP address information, contact URIs,
87 and anonymize all traffic involved with sending/receiving any
88 media streams or call content.
89 Examples of this include the "headers" portions of
90 <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as
91 well as the History-Info (described in
92 <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>)
93 for a SIP CM.</p>
94
95 <p>This SHOULD have the effect of hiding address information from
96 the remote contact (ie, the contact cannot know what IP address
97 the session is originated from). Obviously the network still needs
98 to be able to route information between contacts, so this provides
99 no guarantees of what can be seen by intermediaries.</p>
100 </tp:docstring>
101 </tp:flag>
102 </tp:flags>
103
104 <property name="SupportedAnonymityModes" type="u" access="read"
105 tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes">
106 <tp:docstring>
107 The anonymity modes supported by the CM for this connection. Once
108 Connection.Status has moved to Connected, this property MUST NOT change.
109 </tp:docstring>
110 </property>
111
112 <property name="Mandatory" type="b" access="readwrite"
113 tp:name-for-bindings="Mandatory">
114 <tp:docstring>
115 <p>This specifies whether or not the anonymity settings MUST be respected
116 by the CM and any intermediaries between the local and remote contacts.
117 If this is set to true but anonymity settings cannot be followed, then
118 the session MUST be denied with a
119 <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> error.
120 Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref>
121 SHOULD also set this property first (rather than accepting the CM's
122 default value).</p>
123
124 <p>This property can also be set using a connection parameter in <tp:dbus-ref
125 namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
126 see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p>
127 </tp:docstring>
128 </property>
129
130 <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
131 access="readwrite" tp:name-for-bindings="Anonymity_Modes">
132 <tp:docstring>
133 <p>The currently enabled anonymity modes for the connection. Setting
134 has the effect of requesting new modes for the connection, and may
135 raise an error if the unsupported modes are set. Successfully changing
136 the modes will result in emmision of
137 <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p>
138
139 <p>This property can also be set using a connection parameter in <tp:dbus-ref
140 namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
141 see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p>
142 </tp:docstring>
143 <tp:possible-errors>
144 <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
145 <tp:docstring>
146 An unsupported mode was supplied. Supported modes are specified
147 in the SupportedAnonymityModes property, and this should be
148 checked prior to setting AnonymityModes.
149 </tp:docstring>
150 </tp:error>
151 </tp:possible-errors>
152 </property>
153
154 <signal name="AnonymityModesChanged"
155 tp:name-for-bindings="Anonymity_Modes_Changed">
156 <tp:docstring>
157 Emitted when the anonymity mode has changed.
158 </tp:docstring>
159
160 <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags">
161 <tp:docstring>
162 The new anonymity modes for this connection.
163 </tp:docstring>
164 </arg>
165 </signal>
166
167 </interface>
168 </node>
169 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+1
-1
spec/Connection_Interface_Capabilities.xml less more
230230 </method>
231231
232232 <tp:contact-attribute name="caps"
233 type="a(usuu)" tp:type="Contact_Capability">
233 type="a(usuu)" tp:type="Contact_Capability[]">
234234 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
235235 <p>The same structs that would be returned by
236236 <tp:member-ref>GetCapabilities</tp:member-ref>
+82
-0
spec/Connection_Interface_Cellular.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Cellular"
2 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
4 <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
5 <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.</p>
11
12 <p>This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.</p>
16
17 <p>You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20 02110-1301, USA.</p>
21 </tp:license>
22
23 <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular.DRAFT"
24 tp:causes-havoc="experimental">
25 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
26
27 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
28 <p>This interface is for various cellular things (GSM and/or CDMA) things that
29 aren't really applicable to other protocols.</p>
30 </tp:docstring>
31
32 <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period"
33 type="u" access="readwrite">
34 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
35 <p>Define how long should the service centre try message delivery before
36 giving up, failing delivery and deleting the message. A value of 0 means
37 to use the service centre's default period.</p>
38 <p>The value specified is in seconds. Note that various protocols or
39 implementations may round the value up (eg. to a minute or hour
40 precision). The maximum validity period may vary depending on
41 protocol or provider.</p>
42 </tp:docstring>
43 </property>
44
45 <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre"
46 type="s" access="readwrite">
47 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
48 Address for the messaging service centre. Typically (as is the case
49 for GSM's SMSC), it's the ISDN / telephony address (ie. a phone number).
50 </tp:docstring>
51 </property>
52
53 <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read">
54 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
55 <p>The International Mobile Subscriber Identifier, if it exists. This
56 would originate from a SIM card. If the IMSI is unknown, this will
57 contain an empty string ("").</p>
58 </tp:docstring>
59 </property>
60
61 <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed">
62 <tp:docstring>
63 Emitted when the IMSI for the connection changes. This sort of thing
64 is rare, but could happen on cellular phones that allow hot-swapping
65 of SIM cards. In the case of SIM swapping, this signal would be
66 emitted twice; the first time while the SIM is being ejected (with an
67 empty string), and the second time after a new SIM has been inserted
68 (assuming that the IMSI can be determined from the new SIM).
69 </tp:docstring>
70
71 <arg name="IMSI" type="s">
72 <tp:docstring>
73 The new IMSI value. This may be an empty string in the case where
74 the IMSI is being reset or removed.
75 </tp:docstring>
76 </arg>
77 </signal>
78
79 </interface>
80 </node>
81 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+412
-0
spec/Connection_Interface_Contact_Groups.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
3 <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
4 <tp:license xmlns="http://www.w3.org/1999/xhtml">
5 <p>This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.</p>
9
10 <p>This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.</p>
14
15 <p>You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
18 USA.</p>
19 </tp:license>
20 <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT"
21 tp:causes-havoc="experimental">
22 <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
23 <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"/>
24 <tp:added version="0.19.6">(draft 1)</tp:added>
25
26 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
27 <p>An interface for connections in which contacts can be placed in
28 user-defined groups.</p>
29 </tp:docstring>
30
31 <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups"
32 access="read" type="b">
33 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
34 <p>True if each contact can be in at most one group; false if each
35 contact can be in many groups.</p>
36
37 <p>This property cannot change after the connection has moved to the
38 Connected state. Until then, its value is undefined, and it may
39 change at any time, without notification.</p>
40 </tp:docstring>
41 </property>
42
43 <property name="GroupStorage" tp:name-for-bindings="Group_Storage"
44 type="u" tp:type="Contact_Metadata_Storage_Type" access="read">
45 <tp:docstring>
46 <p>Indicates the extent to which contacts' groups can be set and
47 stored.</p>
48
49 <p>This property cannot change after the connection has moved to the
50 Connected state. Until then, its value is undefined, and it may
51 change at any time, without notification.</p>
52 </tp:docstring>
53 </property>
54
55 <tp:contact-attribute name="groups" type="as">
56 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
57 <p>The names of groups of which a contact is a member.</p>
58
59 <p>Change notification is via
60 <tp:member-ref>GroupsChanged</tp:member-ref>,
61 <tp:member-ref>GroupRenamed</tp:member-ref> and
62 <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
63 </tp:docstring>
64 </tp:contact-attribute>
65
66 <property name="Groups" type="as" access="read"
67 tp:name-for-bindings="Groups">
68 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
69 <p>The names of all groups that currently exist. This may be a
70 larger set than the union of all contacts' <code>groups</code>
71 contact attributes, if the connection allows groups to be
72 empty.</p>
73
74 <p>Change notification is via
75 <tp:member-ref>GroupsCreated</tp:member-ref>,
76 <tp:member-ref>GroupRenamed</tp:member-ref> and
77 <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
78 </tp:docstring>
79 </property>
80
81 <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created">
82 <tp:docstring>
83 Emitted when new, empty groups are created. This will often be
84 followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that
85 add some members.
86 </tp:docstring>
87
88 <arg name="Names" type="as">
89 <tp:docstring>The names of the new groups.</tp:docstring>
90 </arg>
91 </signal>
92
93 <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed">
94 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
95 <p>Emitted when a group is renamed. If the group was not empty,
96 immediately after this signal is emitted,
97 <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
98 that the members of that group were removed from the old name
99 and added to the new name.</p>
100
101 <p>On connection managers where groups behave like tags, this signal
102 will probably only be emitted when
103 <tp:member-ref>RenameGroup</tp:member-ref> is called, and renaming a
104 group from another client MAY be signalled as a
105 <tp:member-ref>GroupsChanged</tp:member-ref> signal instead.</p>
106
107 <tp:rationale>
108 <p>On protocols like XMPP, another resource "renaming a group" is
109 indistinguishable from changing contacts' groups individually.</p>
110 </tp:rationale>
111 </tp:docstring>
112
113 <arg name="Old_Name" type="s">
114 <tp:docstring>The old name of the group.</tp:docstring>
115 </arg>
116
117 <arg name="New_Name" type="s">
118 <tp:docstring>The new name of the group.</tp:docstring>
119 </arg>
120 </signal>
121
122 <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed">
123 <tp:docstring>
124 Emitted when one or more groups are removed. If they had members at
125 the time that they were removed, then immediately after this signal is
126 emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
127 that their members were removed.
128 </tp:docstring>
129
130 <arg name="Names" type="as">
131 <tp:docstring>The names of the groups.</tp:docstring>
132 </arg>
133 </signal>
134
135 <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed">
136 <tp:docstring>
137 Emitted when contacts' groups change.
138 </tp:docstring>
139
140 <arg name="Contact" type="au" tp:type="Contact_Handle">
141 <tp:docstring>The relevant contacts.</tp:docstring>
142 </arg>
143
144 <arg name="Added" type="as">
145 <tp:docstring>The names of groups to which the contacts were
146 added.</tp:docstring>
147 </arg>
148
149 <arg name="Removed" type="as">
150 <tp:docstring>The names of groups from which the contacts were
151 removed.</tp:docstring>
152 </arg>
153 </signal>
154
155 <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups">
156 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
157 <p>Add the given contact to the given groups (creating new groups
158 if necessary), and remove them from all other groups.</p>
159
160 <tp:rationale>
161 <p>This is the easiest and most correct way to implement user
162 interfaces that display a single contact with a list of groups,
163 resulting in a user expectation that when they apply the changes,
164 the contact's set of groups will become exactly what was
165 displayed.</p>
166 </tp:rationale>
167
168 <p>If the user is removed from a group of which they were the only
169 member, the group MAY be removed automatically.</p>
170
171 <tp:rationale>
172 <p>In protocols like XMPP where groups behave like tags, a group
173 with no members has no protocol representation.</p>
174 </tp:rationale>
175
176 <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
177 <tp:member-ref>GroupsChanged</tp:member-ref> and
178 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
179 this method call MUST be emitted before the method returns.</p>
180 </tp:docstring>
181
182 <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
183 <tp:docstring>The contact to alter.</tp:docstring>
184 </arg>
185
186 <arg name="Groups" type="as" direction="in">
187 <tp:docstring>The set of groups which the contact should be
188 in.</tp:docstring>
189 </arg>
190
191 <tp:possible-errors>
192 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
193 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
194 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
195 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
196 <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref>
197 is true and the list of groups has more than one
198 member.</tp:docstring>
199 </tp:error>
200 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
201 <tp:docstring>
202 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
203 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
204 </tp:docstring>
205 </tp:error>
206 </tp:possible-errors>
207 </method>
208
209 <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members">
210 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
211 <p>Add the given members to the given group (creating it if necessary),
212 and remove all other members.</p>
213
214 <tp:rationale>
215 <p>This is the easiest and most correct way to implement user
216 interfaces that display a single group with a list of contacts,
217 resulting in a user expectation that when they apply the changes,
218 the groups's set of members will become exactly what was
219 displayed.</p>
220 </tp:rationale>
221
222 <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
223 this will also remove each member from their previous group.</p>
224
225 <p>If the user is removed from a group of which they were the only
226 member, the group MAY be removed automatically.</p>
227
228 <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
229 <tp:member-ref>GroupsChanged</tp:member-ref> and
230 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
231 this method call MUST be emitted before the method returns.</p>
232 </tp:docstring>
233
234 <arg name="Group" type="s" direction="in">
235 <tp:docstring>The group to alter.</tp:docstring>
236 </arg>
237
238 <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
239 <tp:docstring>The set of members for the group. If this set is
240 empty, this method MAY remove the group.</tp:docstring>
241 </arg>
242
243 <tp:possible-errors>
244 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
245 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
246 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
247 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
248 <tp:docstring>
249 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
250 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
251 </tp:docstring>
252 </tp:error>
253 </tp:possible-errors>
254 </method>
255
256 <method name="AddToGroup" tp:name-for-bindings="Add_To_Group">
257 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
258 <p>Add the given members to the given group, creating it if
259 necessary.</p>
260
261 <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
262 this will also remove each member from their previous group.</p>
263
264 <tp:rationale>
265 <p>This is good for user interfaces in which you can edit groups
266 via drag-and-drop.</p>
267 </tp:rationale>
268
269 <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
270 <tp:member-ref>GroupsChanged</tp:member-ref> and
271 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
272 this method call MUST be emitted before the method returns.</p>
273 </tp:docstring>
274
275 <arg name="Group" type="s" direction="in">
276 <tp:docstring>The group to alter.</tp:docstring>
277 </arg>
278
279 <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
280 <tp:docstring>The set of members to include in the group.</tp:docstring>
281 </arg>
282
283 <tp:possible-errors>
284 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
285 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
286 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
287 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
288 <tp:docstring>
289 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
290 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
291 </tp:docstring>
292 </tp:error>
293 </tp:possible-errors>
294 </method>
295
296 <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group">
297 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
298 <p>Remove the given members from the given group.</p>
299
300 <tp:rationale>
301 <p>This is good for user interfaces in which you can edit groups
302 via drag-and-drop.</p>
303 </tp:rationale>
304
305 <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
306 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
307 this method call MUST be emitted before the method returns.</p>
308 </tp:docstring>
309
310 <arg name="Group" type="s" direction="in">
311 <tp:docstring>The group to alter. If it does not exist, then it has
312 no members by definition, so this method SHOULD return
313 successfully.</tp:docstring>
314 </arg>
315
316 <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
317 <tp:docstring>The set of members to remove from the group. It is not
318 an error to remove members who are already not in the group.
319 If there are no members left in the group afterwards, the group MAY
320 itself be removed.</tp:docstring>
321 </arg>
322
323 <tp:possible-errors>
324 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
325 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
326 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
327 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
328 <tp:docstring>
329 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
330 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
331 </tp:docstring>
332 </tp:error>
333 </tp:possible-errors>
334 </method>
335
336 <method name="RemoveGroup" tp:name-for-bindings="Remove_Group">
337 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
338 <p>Remove all members from the given group, then remove the group
339 itself. If the group already does not exist, this method SHOULD
340 return successfully.</p>
341
342 <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
343 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
344 this method call MUST be emitted before the method returns.</p>
345 </tp:docstring>
346
347 <arg name="Group" type="s" direction="in">
348 <tp:docstring>The group to remove.</tp:docstring>
349 </arg>
350
351 <tp:possible-errors>
352 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
353 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
354 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
355 <tp:docstring>
356 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
357 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
358 </tp:docstring>
359 </tp:error>
360 </tp:possible-errors>
361 </method>
362
363 <method name="RenameGroup" tp:name-for-bindings="Rename_Group">
364 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
365 <p>Rename the given group.</p>
366
367 <p>On protocols where groups behave like tags, this is an API
368 short-cut for adding all of the group's members to a group with
369 the new name, then removing the old group.</p>
370
371 <tp:rationale>
372 <p>Otherwise, clients can't perform this operation atomically, even
373 if the connection could.</p>
374 </tp:rationale>
375
376 <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or
377 <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
378 this method call MUST be emitted before the method returns.</p>
379 </tp:docstring>
380
381 <arg name="Old_Name" type="s" direction="in">
382 <tp:docstring>The group to rename.</tp:docstring>
383 </arg>
384
385 <arg name="New_Name" type="s" direction="in">
386 <tp:docstring>The new name for the group.</tp:docstring>
387 </arg>
388
389 <tp:possible-errors>
390 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
391 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
392 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
393 <tp:docstring>
394 Raised if <tp:member-ref>GroupStorage</tp:member-ref>
395 is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
396 </tp:docstring>
397 </tp:error>
398 <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist">
399 <tp:docstring>Raised if there is no group with that
400 name.</tp:docstring>
401 </tp:error>
402 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
403 <tp:docstring>Raised if there is already a group with the new
404 name.</tp:docstring>
405 </tp:error>
406 </tp:possible-errors>
407 </method>
408
409 </interface>
410 </node>
411 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+11
-0
spec/Connection_Interface_Contact_Info.xml less more
503503 network traffic.</p>
504504 </tp:rationale>
505505 </tp:docstring>
506
507 <tp:contact-attribute name="info"
508 type="a(sasas)" tp:type="Contact_Info_Field[]">
509 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
510 <p>The same value that would be returned by
511 <tp:member-ref>GetContactInfo</tp:member-ref> for this contact.
512 Omitted from the result if the contact's info
513 is not known.</p>
514 </tp:docstring>
515 </tp:contact-attribute>
516
506517 </interface>
507518 </node>
508519 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+837
-0
spec/Connection_Interface_Contact_List.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
3 <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
4 <tp:license xmlns="http://www.w3.org/1999/xhtml">
5 <p>This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.</p>
9
10 <p>This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.</p>
14
15 <p>You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
18 USA.</p>
19 </tp:license>
20 <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"
21 tp:causes-havoc="experimental">
22 <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
23 <tp:added version="0.19.6">(draft 1)</tp:added>
24
25 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26 <p>An interface for connections that have any concept of a list of
27 known contacts (roster, buddy list, friends list etc.)</p>
28
29 <tp:rationale>
30 <p>On many protocols, there's a server-side roster (as in XMPP),
31 or a set of server-side lists that can be combined to form a
32 roster (as in MSN).</p>
33
34 <p>In some protocols (like link-local XMPP), while there might not be
35 any server or roster, it's possible to list "nearby" contacts.</p>
36
37 <p>In Telepathy 0.18 and older, we represented contact lists as a
38 collection of <tp:dbus-ref
39 namespace="org.freedesktop.Telepathy.Channel.Type"
40 >ContactList</tp:dbus-ref> channels. This is remarkably difficult to
41 work with in practice - every client that cares about contact lists
42 has to take the union of some hard-to-define set of these
43 channels - and conflicts with the idea that channels that cannot
44 be dispatched to a handler should be closed.</p>
45 </tp:rationale>
46
47 <p>The list of contacts is not exposed as a D-Bus property; it can be
48 fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>.
49 </p>
50
51 <tp:rationale>
52 <p>In some protocols, such as XMPP, the contact list may not be
53 available immediately. The
54 <tp:member-ref>GetContactListAttributes</tp:member-ref> method
55 will wait until the contact list is available before returning.
56 Using a method also allows extra attributes to be retrieved at
57 the same time.</p>
58 </tp:rationale>
59 </tp:docstring>
60
61 <method name="GetContactListAttributes"
62 tp:name-for-bindings="Get_Contact_List_Attributes">
63 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
64 <p>Return some contact attributes for a list of contacts somehow
65 associated with the user.</p>
66
67 <p>This definition is deliberately vague: in practice, most user
68 interfaces should display some subset of this list, by filtering it
69 by some contact attributes (for instance, displaying all contacts
70 whose "subscribe" attribute is Yes is expected to be a common case).
71 This list MAY contain any contacts whatsoever, but MUST contain
72 at least the following:</p>
73
74 <ul>
75 <li>all contacts whose "subscribe" attribute is Ask or Yes</li>
76 <li>all contacts whose "publish" attribute is Ask or Yes</li>
77 <li>all contacts with a persistently-stored stored alias, if
78 supported</li>
79 <li>all contacts in user-defined contact groups, if supported</li>
80 </ul>
81
82 <p>This list does not need to contain every visible contact: for
83 instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
84 here. Blocked contacts SHOULD NOT appear here either, unless they
85 are still stored in a persistent roster/contact list as well as
86 being blocked.</p>
87
88 <tp:rationale>
89 <p>This is basically the union of the historical <tp:dbus-ref
90 namespace="org.freedesktop.Telepathy.Channel.Type"
91 >ContactList</tp:dbus-ref> subscribe, publish and stored
92 channels.</p>
93
94 <p>For example, XMPP, it's the roster; on link-local XMPP, it's the
95 set of visible users on the local network; on MSN, it's the union
96 of the forward and reverse buddy lists.</p>
97
98 <p>An easy way for an application to display a contact list is to
99 call this method with at least this interface in the Interfaces
100 argument, then check which subset of contacts should be displayed
101 (perhaps based on their subscribe attribute, for instance) and display
102 them. Any additional information required to display the contact
103 list, like aliases or presence, can be retrieved at the same
104 time.</p>
105
106 <p>In practice, most user interfaces for the contact list will
107 usually display a large proportion of this list
108 (for instance, most contacts on the contact list will usually
109 have subscribe=Yes in practice, so contact lists that display
110 subscribe=Yes contacts need to display almost the entire list),
111 so the overhead of returning information about too many contacts
112 is small.</p>
113 </tp:rationale>
114
115 <p>This method SHOULD NOT return before the contact list has been
116 retrieved, on protocols where this is possible. As a result,
117 clients SHOULD use a longer-than-default timeout for this method
118 call, since retrieving the contact list can take a significant
119 time on some servers.</p>
120
121 <tp:rationale>
122 <p>This makes it possible for clients to wait for the contact list.
123 For instance, on XMPP this method shouldn't return until the
124 roster has been retrieved, which is an asynchronous process.
125 However, on link-local XMPP you can't know when you have the
126 complete list, so this method would have to return immediately.</p>
127 </tp:rationale>
128 </tp:docstring>
129
130 <arg direction="in" name="Interfaces" type="as"
131 tp:type="DBus_Interface[]">
132 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
133 <p>A list of strings indicating which D-Bus interfaces the calling
134 process is interested in. Equivalent to the corresponding argument
135 to <tp:dbus-ref
136 namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
137 >GetContactAttributes</tp:dbus-ref>.</p>
138 </tp:docstring>
139 </arg>
140
141 <arg direction="in" name="Hold" type="b">
142 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
143 <p>Whether to hold the handles on behalf of the calling process.
144 Equivalent to the corresponding argument to <tp:dbus-ref
145 namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
146 >GetContactAttributes</tp:dbus-ref>.</p>
147
148 <p><em>FIXME: if we do distributed refcounting, we should probably
149 rename this to 'Reference' and implement handle-refcounting
150 semantics first? On the other hand, if we make handles persist
151 for the lifetime of the connection, we can just remove this
152 parameter.</em></p>
153 </tp:docstring>
154 </arg>
155
156 <arg direction="out" type="a{ua{sv}}" name="Attributes"
157 tp:type="Contact_Attributes_Map">
158 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
159 <p>A dictionary mapping the contact handles to contact attributes,
160 equivalent to the result of <tp:dbus-ref
161 namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
162 >GetContactAttributes</tp:dbus-ref>.</p>
163
164 </tp:docstring>
165 </arg>
166
167 <tp:possible-errors>
168 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
169 </tp:possible-errors>
170 </method>
171
172 <tp:enum name="Presence_State" type="u">
173 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
174 <p>A tristate indicating whether presence subscription is denied,
175 denied but pending permission, or allowed. The exact semantics
176 vary according to where this type is used.</p>
177 </tp:docstring>
178
179 <tp:enumvalue suffix="No" value="0">
180 <tp:docstring>Presence information cannot be seen.</tp:docstring>
181 </tp:enumvalue>
182 <tp:enumvalue suffix="Ask" value="1">
183 <tp:docstring>Presence information cannot be seen, but permission
184 to see presence information has been requested.</tp:docstring>
185 </tp:enumvalue>
186 <tp:enumvalue suffix="Yes" value="2">
187 <tp:docstring>Presence information can be seen.</tp:docstring>
188 </tp:enumvalue>
189 </tp:enum>
190
191 <tp:contact-attribute name="subscribe"
192 type="u" tp:type="Presence_State">
193 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
194 <p>If this attribute on a contact is Yes, this connection can
195 expect to receive their presence, along with any other information
196 that has the same access control.</p>
197
198 <tp:rationale>
199 <p>This is subscription="from" or subscription="both" in XMPP,
200 the "forward list" on MSN, or the contact being "added to
201 the local user's buddy list" in ICQ, for example.</p>
202 </tp:rationale>
203
204 <p>If this attribute is No or Ask, the local user cannot generally
205 expect to receive presence from this contact. Their presence status
206 as returned by <tp:dbus-ref
207 namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
208 is likely to be (Unknown, "unknown", ""), unless the local user
209 can temporarily see their presence for some other reason (for
210 instance, on XMPP, contacts seen in chatrooms will temporarily
211 have available presence).</p>
212
213 <p>If this attribute is Ask, this indicates that the local user has
214 asked to receive the contact's presence at some time. It is
215 implementation-dependent whether contacts' subscribe attributes
216 can remain set to Ask, or are reset to No, when the connection
217 disconnects.</p>
218
219 <tp:rationale>
220 <p>Some protocols store the fact that we wishes to see a contact's
221 presence; on these protocols, this attribute can remain Ask
222 indefinitely. On other protocols, only contacts who have been
223 asked during the current session will ever have Ask status.</p>
224 </tp:rationale>
225 </tp:docstring>
226 </tp:contact-attribute>
227
228 <tp:contact-attribute name="publish"
229 type="u" tp:type="Presence_State">
230 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
231 <p>If this attribute on a contact is Yes, the local user's presence
232 is published to that contact, along with any other information that
233 shares an access-control mechanism with presence (depending on
234 protocol, server configuration and/or user configuration, this may
235 include avatars, "rich presence" such as location, etc.).</p>
236
237 <tp:rationale>
238 <p>This is subscription="to" or subscription="both" in XMPP,
239 the "reverse list" on MSN, or the state of "being added to
240 the contact's buddy list" in ICQ, for example.</p>
241 </tp:rationale>
242
243 <p>If this attribute is No or Ask, the
244 local user's presence is not published to that contact; however,
245 if it is Ask, the contact has requested that the local user's
246 presence is made available to them.</p>
247
248 <p>It is implementation-dependent whether contacts' publish
249 attributes can remain set to Ask, or are reset to No, when the
250 connection disconnects.</p>
251
252 <tp:rationale>
253 <p>Some protocols store the fact that a contact wishes to see our
254 presence; on these protocols, this attribute can remain Ask
255 indefinitely. On other protocols, only contacts who have asked
256 during the current session will ever have Ask status.</p>
257 </tp:rationale>
258 </tp:docstring>
259 </tp:contact-attribute>
260
261 <tp:contact-attribute name="publish-request" type="s">
262 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
263 <p>If the "publish" attribute is Ask, an optional message that was
264 sent by the contact asking to receive the local user's presence;
265 omitted if none was given.</p>
266
267 <tp:rationale>
268 <p>If the contact asking to receive our presence is also using
269 Telepathy, this is the message they supplied as the Message
270 argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p>
271 </tp:rationale>
272
273 <p>Otherwise, this SHOULD be omitted.</p>
274 </tp:docstring>
275 </tp:contact-attribute>
276
277 <property name="SubscriptionsPersist"
278 tp:name-for-bindings="Subscriptions_Persist" type="b" access="read">
279 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
280 <p>If true, presence subscriptions (in both directions) on this
281 connection are stored by the server or other infrastructure.</p>
282
283 <tp:rationale>
284 <p>XMPP, MSN, ICQ, etc. all behave like this.</p>
285 </tp:rationale>
286
287 <p>If false, presence subscriptions on this connection are not
288 stored.</p>
289
290 <tp:rationale>
291 <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record
292 of subscriptions, as described below. In link-local XMPP,
293 subscriptions are implicit (everyone on the local network receives
294 presence from everyone else) so nothing is ever stored.</p>
295 </tp:rationale>
296
297 <p>If <tp:member-ref>CanChangeSubscriptions</tp:member-ref>
298 is true, Telepathy clients (e.g. user interfaces or address books)
299 MAY keep a record of permission to publish and requests to subscribe
300 locally, and attempt to restore it for each Connection. If
301 SubscriptionsPersist is false, clients MAY do this for all contacts;
302 if SubscriptionsPersist is true, clients SHOULD NOT change the state
303 of contacts that were not changed locally.</p>
304
305 <tp:rationale>
306 <p>In SIMPLE (SIP), SubscriptionsPersist is false, but
307 CanChangeSubscriptions is true. Presence will not be received
308 unless clients renew any subscriptions they have for each
309 connection, in the way described. There is no server-side storage,
310 so clients have no alternative but to maintain independent contact
311 lists.</p>
312
313 <p>In protocols like XMPP and MSN, it may be useful for clients to
314 queue up subscription requests or removals made while offline and
315 process them next time the connection is online. However, clients
316 should only replay the changes, rather than resetting the contact
317 list to match a stored copy, to avoid overwriting changes that
318 were made on the server.</p>
319 </tp:rationale>
320
321 <p>Clients that replay requests like this SHOULD do so by calling
322 AuthorizePublication to pre-approve publication of presence to the
323 appropriate contacts, followed by RequestSubscription to request the
324 appropriate contacts' presences.</p>
325
326 <p>This property cannot change after the connection has moved to the
327 Connected state. Until then, its value is undefined, and it may
328 change at any time, without notification.</p>
329 </tp:docstring>
330 </property>
331
332 <tp:enum name="Contact_Metadata_Storage_Type" type="u">
333 <tp:docstring>
334 Values of this enumeration indicate the extent to which metadata
335 such as aliases and group memberships can be stored for the contacts
336 on a particular connection.
337 </tp:docstring>
338
339 <tp:enumvalue suffix="None" value="0">
340 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
341 <p>This connection cannot store this type of metadata at all, and
342 attempting to do so will fail with NotImplemented.</p>
343
344 <tp:rationale>
345 <p>Link-local XMPP can't store aliases or group memberships at
346 all, and subscription and presence states are implicit (all
347 contacts on the local network have subscribe = publish = Yes
348 and no other contacts exist).</p>
349
350 <p>As of April 2010, the XMPP server for Facebook Chat provides a
351 read-only view of the user's Facebook contacts, so it could also
352 usefully have this storage type.</p>
353 </tp:rationale>
354 </tp:docstring>
355 </tp:enumvalue>
356
357 <tp:enumvalue suffix="Subscribed_Or_Pending" value="1">
358 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
359 <p>This type of metadata can only be stored permanently for contacts
360 whose subscribe attribute is Ask or Yes.</p>
361
362 <tp:rationale>
363 <p>Contact aliases and groups on MSN have this behaviour.</p>
364 </tp:rationale>
365
366 <p>If this type of metadata is set on a contact with subscribe=No,
367 the Connection MUST cache it until disconnected, and return it
368 if requested. If subscription to the contact's presence is
369 subsequently requested, making it possible to store this metadata,
370 the Connection MUST store the cached value at that time.</p>
371
372 <tp:rationale>
373 <p>This supports the recommended calling pattern for adding a
374 new contact, in which alias and groups are set (without
375 necessarily waiting for a reply) before requesting the
376 contact's presence. Until the subscription request is
377 processed by the server, the alias and groups will be cached
378 in memory; when the subscription request has been processed,
379 the connection manager will store the metadata on the server.</p>
380 </tp:rationale>
381 </tp:docstring>
382 </tp:enumvalue>
383
384 <tp:enumvalue suffix="Subscribed" value="2">
385 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
386 <p>This type of metadata can only be stored permanently for contacts
387 whose subscribe attribute is Yes.</p>
388
389 <tp:rationale>
390 <p>No service with this behaviour is currently known, but it's a
391 stricter form of Subscribed_Or_Pending.</p>
392 </tp:rationale>
393
394 <p>If this type of metadata is set on a contact with subscribe != Yes,
395 the Connection MUST cache it until disconnected, and return it
396 if requested. If subscription to the contact's presence is
397 subsequently allowed, making it possible to store this metadata,
398 the Connection MUST store the cached value at that time.</p>
399
400 <tp:rationale>
401 <p>The same rationale applies as for Subscribed_Or_Pending,
402 except that metadata must be stored until the subscription
403 request is not only processed by the server, but also allowed
404 by the remote user.</p>
405 </tp:rationale>
406 </tp:docstring>
407 </tp:enumvalue>
408
409 <tp:enumvalue suffix="Anyone" value="3">
410 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
411 <p>The user can set this metadata for any valid contact identifier,
412 whether or not they have any presence subscription relationship
413 to it, and it will be stored on their contact list.</p>
414
415 <tp:rationale>
416 <p>Contact aliases and groups on XMPP have this behaviour; it
417 is possible to put a contact in a group, or assign an alias
418 to them, without requesting that presence be shared.</p>
419 </tp:rationale>
420 </tp:docstring>
421 </tp:enumvalue>
422 </tp:enum>
423
424 <tp:struct name="Contact_Subscriptions" array-name="">
425 <tp:docstring>
426 A single contact's subscribe, publish and publish-request attributes.
427 </tp:docstring>
428
429 <tp:member name="Subscribe" type="u" tp:type="Presence_State">
430 <tp:docstring>
431 The new value of the contact's "subscribe" attribute.
432 </tp:docstring>
433 </tp:member>
434
435 <tp:member name="Publish" type="u" tp:type="Presence_State">
436 <tp:docstring>
437 The new value of the contact's "publish" attribute.
438 </tp:docstring>
439 </tp:member>
440
441 <tp:member name="Publish_Request" type="s">
442 <tp:docstring>
443 The new value of the contact's "publish-request" attribute,
444 or the empty string if that attribute would be omitted.
445 </tp:docstring>
446 </tp:member>
447 </tp:struct>
448
449 <tp:mapping name="Contact_Subscription_Map" array-name="">
450 <tp:docstring>
451 A map from contacts to their subscribe, publish and publish-request
452 attributes.
453 </tp:docstring>
454
455 <tp:member name="Contact" type="u" tp:type="Contact_Handle">
456 <tp:docstring>
457 The contact's handle.
458 </tp:docstring>
459 </tp:member>
460
461 <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions">
462 <tp:docstring>
463 The contact's subscribe, publish and publish-request attributes.
464 </tp:docstring>
465 </tp:member>
466 </tp:mapping>
467
468 <signal name="ContactsChanged"
469 tp:name-for-bindings="Contacts_Changed">
470 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
471 <p>Emitted when the contact list becomes available, when contacts'
472 basic stored properties change, when new contacts are added to the
473 list that would be returned by
474 <tp:member-ref>GetContactListAttributes</tp:member-ref>,
475 or when contact are removed from that list.</p>
476
477 <tp:rationale>
478 <p>This provides change notification for that list, and for
479 contacts' "subscribe", "publish" and
480 "publish-request" attributes.</p>
481 </tp:rationale>
482 </tp:docstring>
483
484 <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
485 <tp:docstring>
486 The new subscribe, publish and publish-request attributes of all the
487 contacts that have been added, and all the contacts for which those
488 attributes have changed.
489 </tp:docstring>
490 </arg>
491
492 <arg name="Removals" type="au" tp:type="Contact_Handle[]">
493 <tp:docstring>
494 The contacts that have been removed from the list that would be
495 returned by
496 <tp:member-ref>GetContactListAttributes</tp:member-ref>.
497 This also implies that they have subscribe = No and publish = No;
498 contacts MUST NOT be listed both here and in Changes.
499 </tp:docstring>
500 </arg>
501 </signal>
502
503 <property name="CanChangeSubscriptions" type="b" access="read"
504 tp:name-for-bindings="Can_Change_Subscriptions">
505 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
506 <p>If true, presence subscription and publication can be changed
507 using the
508 <tp:member-ref>RequestSubscription</tp:member-ref>,
509 <tp:member-ref>AuthorizePublication</tp:member-ref> and
510 <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p>
511
512 <p>If false, all of those methods will always fail; they SHOULD raise
513 the error org.freedesktop.Telepathy.Error.NotImplemented.</p>
514
515 <tp:rationale>
516 <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is
517 implicitly published to everyone in the local subnet, so the user
518 cannot control their presence publication.</p>
519 </tp:rationale>
520
521 <p>This property cannot change after the connection has moved to the
522 Connected state. Until then, its value is undefined, and it may
523 change at any time, without notification.</p>
524 </tp:docstring>
525 </property>
526
527 <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription">
528 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
529 <p>Request that the given contacts allow the local user to
530 subscribe to their presence, i.e. that their subscribe attribute
531 becomes Yes.</p>
532
533 <p>Before calling this method on a connection where <tp:dbus-ref
534 namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
535 >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag,
536 user interfaces SHOULD obtain, from the user, an alias to
537 identify the contact in future, and store it using <tp:dbus-ref
538 namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
539 >SetAliases</tp:dbus-ref>.
540
541 The user MAY be
542 prompted using the contact's current self-assigned nickname, or
543 something derived from the contact's (presumably self-assigned)
544 identifier, as a default, but these names chosen by the contact
545 SHOULD NOT be used without user approval.</p>
546
547 <tp:rationale>
548 <p>This is a generalization of
549 <a href="http://xmpp.org/extensions/xep-0165.html"
550 >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>)
551 to protocols other than XMPP. A reasonable user interface for
552 this, as used in many XMPP clients, is to have a text entry
553 for the alias adjacent to the text entry for the identifier
554 to add.</p>
555 </tp:rationale>
556
557 <p>For contacts with subscribe=Yes, this method has no effect.
558 It MUST return successfully if all contacts are in this state.</p>
559
560 <p>For contacts with subscribe=Ask, this method SHOULD send a new
561 request, with the given message, if allowed by the underlying
562 protocol.</p>
563
564 <p>For contacts with subscribe=No, this method SHOULD request that
565 the contact allows the local user to subscribe to their presence;
566 in general, this will change their publish attribute from No
567 to Ask (although it could change directly from No to Yes in some
568 situations).</p>
569
570 <p>Any state changes that immediately result from this request MUST
571 be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
572 before this method returns.</p>
573
574 <tp:rationale>
575 <p>This makes it easy for user interfaces to see what practical
576 effect this method had.</p>
577 </tp:rationale>
578
579 <p>If the remote contact accepts the request, their subscribe
580 attribute will later change from Ask to Yes; if they explicitly
581 reject the request (in protocols that allow this), their subscribe
582 attribute will later change from Ask to No.</p>
583 </tp:docstring>
584
585 <arg name="Contacts" direction="in"
586 type="au" tp:type="Contact_Handle[]">
587 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
588 <p>One or more contacts to whom requests are to be sent.</p>
589 </tp:docstring>
590 </arg>
591
592 <arg name="Message" type="s" direction="in">
593 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
594 <p>An optional plain-text message from the user, to send to those
595 contacts with the subscription request. The
596 <tp:member-ref>RequestUsesMessage</tp:member-ref> property
597 indicates whether this message will be used or ignored.</p>
598
599 <p>Clients SHOULD NOT send a non-empty message without first giving
600 the user an opportunity to edit it.</p>
601
602 <tp:rationale>
603 <p>These messages are typically presented to the remote contact
604 as if the user had typed them, so as a minimum, the user should be
605 allowed to see what the UI will be saying on their behalf.</p>
606 </tp:rationale>
607
608 <p>Connections where this message is not useful MUST still allow it to
609 be non-empty.</p>
610 </tp:docstring>
611 </arg>
612
613 <tp:possible-errors>
614 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
615 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
616 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
617 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
618 <tp:docstring>
619 It was not possible to perform the requested action, because
620 <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
621 </tp:docstring>
622 </tp:error>
623 </tp:possible-errors>
624 </method>
625
626 <property name="RequestUsesMessage" type="b" access="read"
627 tp:name-for-bindings="Request_Uses_Message">
628 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
629 <p>If true, the Message parameter to
630 <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be
631 significant, and user interfaces SHOULD prompt the user for a
632 message to send with the request; a message such as "I would like
633 to add you to my contact list", translated into the local user's
634 language, might make a suitable default.</p>
635
636 <tp:rationale>
637 <p>This matches user expectations in XMPP and ICQ, for instance.</p>
638 </tp:rationale>
639
640 <p>If false, the parameter is ignored; user interfaces SHOULD avoid
641 prompting the user, and SHOULD pass an empty string to
642 RequestSubscription.</p>
643
644 <tp:rationale>
645 <p><em>FIXME: is there any such protocol?</em></p>
646 </tp:rationale>
647 </tp:docstring>
648 </property>
649
650 <method name="AuthorizePublication"
651 tp:name-for-bindings="Authorize_Publication">
652 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
653 <p>For each of the given contacts, request that the local user's
654 presence is sent to that contact, i.e. that their publish attribute
655 becomes Yes.</p>
656
657 <p>For contacts with publish=Yes, this method has no effect; it
658 MUST return successfully if all contacts given have this state.</p>
659
660 <p>For contacts with publish=Ask, this method accepts the
661 contact's request to see the local user's presence, changing
662 their publish attribute from Ask to Yes.</p>
663
664 <p>For contacts with publish=No, if the protocol allows it, this
665 method allows the contacts to see the local user's presence even
666 though they have not requested it, changing their publish attribute
667 from No to Yes. Otherwise, it merely records the fact that
668 presence publication to those contacts is allowed; if any of
669 those contacts ask to receive the local user's presence
670 later in the lifetime of the connection, the connection SHOULD
671 immediately allow them to do so, changing their publish
672 attribute directly from No to Yes.</p>
673
674 <tp:rationale>
675 <p>This makes it easy to implement the common UI policy that if
676 the user attempts to subscribe to a contact's presence, requests
677 for reciprocal subscription are automatically approved.</p>
678 </tp:rationale>
679
680 <p>Any state changes that immediately result from this request MUST
681 be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
682 before this method returns.</p>
683
684 <tp:rationale>
685 <p>This makes it easy for user interfaces to see what practical
686 effect this method had.</p>
687 </tp:rationale>
688 </tp:docstring>
689
690 <arg name="Contacts" direction="in"
691 type="au" tp:type="Contact_Handle[]">
692 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
693 <p>One or more contacts to authorize.</p>
694 </tp:docstring>
695 </arg>
696
697 <tp:possible-errors>
698 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
699 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
700 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
701 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
702 <tp:docstring>
703 It was not possible to perform the requested action, because
704 <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
705 </tp:docstring>
706 </tp:error>
707 </tp:possible-errors>
708 </method>
709
710 <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts">
711 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
712 <p>Remove the given contacts from the contact list entirely. It is
713 protocol-dependent whether this works, and under which
714 circumstances.</p>
715
716 <p>If possible, this method SHOULD set the contacts' subscribe and
717 publish attributes to No, remove any stored aliases for those
718 contacts, and remove the contacts from the result of
719 <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
720
721 <p>This method SHOULD succeed even if it was not possible to carry out
722 the request entirely or for all contacts (for instance, if there is an
723 outstanding request to subscribe to the contact's presence, and it's
724 not possible to cancel such requests). However, all signals that
725 immediately result from this method call MUST be emitted before it
726 returns, so that clients can interpret the result.</p>
727
728 <tp:rationale>
729 <p>User interfaces removing a contact from the contact list are
730 unlikely to want spurious failure notifications resulting from
731 limitations of a particular protocol. However, emitting the
732 signals first means that if a client does want to check exactly
733 what happened, it can wait for the method to return (while
734 applying change-notification signals to its local cache of the
735 contact list's state), then consult its local cache of the
736 contact list's state to see whether the contact is still there.</p>
737 </tp:rationale>
738 </tp:docstring>
739
740 <arg name="Contacts" direction="in"
741 type="au" tp:type="Contact_Handle[]">
742 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
743 <p>One or more contacts to remove.</p>
744 </tp:docstring>
745 </arg>
746
747 <tp:possible-errors>
748 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
749 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
750 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
751 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
752 <tp:docstring>
753 It was not possible to perform the requested action because
754 <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
755 </tp:docstring>
756 </tp:error>
757 </tp:possible-errors>
758 </method>
759
760 <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe">
761 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
762 <p>Attempt to set the given contacts' subscribe attribute to No,
763 i.e. stop receiving their presence.</p>
764
765 <p>For contacts with subscribe=Ask, this attempts to cancel
766 an earlier request to subscribe to the contact's presence; for
767 contacts with subscribe=Yes, this attempts to
768 unsubscribe from the contact's presence.</p>
769
770 <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
771 SHOULD succeed even if it was not possible to carry out the request
772 entirely or for all contacts; however, all signals that
773 immediately result from this method call MUST be emitted before it
774 returns.</p>
775 </tp:docstring>
776
777 <arg name="Contacts" direction="in"
778 type="au" tp:type="Contact_Handle[]">
779 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
780 <p>One or more contacts to remove.</p>
781 </tp:docstring>
782 </arg>
783
784 <tp:possible-errors>
785 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
786 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
787 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
788 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
789 <tp:docstring>
790 It was not possible to perform the requested action because
791 <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
792 </tp:docstring>
793 </tp:error>
794 </tp:possible-errors>
795 </method>
796
797 <method name="Unpublish" tp:name-for-bindings="Unpublish">
798 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
799 <p>Attempt to set the given contacts' publish attribute to No,
800 i.e. stop sending presence to them.</p>
801
802 <p>For contacts with publish=Ask, this method explicitly rejects the
803 contact's request to subscribe to the user's presence; for
804 contacts with publish=Yes, this method attempts to prevent the
805 user's presence from being received by the contact.</p>
806
807 <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
808 SHOULD succeed even if it was not possible to carry out the request
809 entirely or for all contacts; however, all signals that
810 immediately result from this method call MUST be emitted before it
811 returns.</p>
812 </tp:docstring>
813
814 <arg name="Contacts" direction="in"
815 type="au" tp:type="Contact_Handle[]">
816 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
817 <p>One or more contacts to remove.</p>
818 </tp:docstring>
819 </arg>
820
821 <tp:possible-errors>
822 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
823 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
824 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
825 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
826 <tp:docstring>
827 It was not possible to perform the requested action because
828 <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
829 </tp:docstring>
830 </tp:error>
831 </tp:possible-errors>
832 </method>
833
834 </interface>
835 </node>
836 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+322
-65
spec/Connection_Interface_Forwarding.xml less more
00 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Forwarding" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
3 <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
4 <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
1 <node name="/Connection_Interface_Forwarding"
2 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
4 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
5 <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright>
6 <tp:copyright>Copyright © 2006 INdT </tp:copyright>
57 <tp:license xmlns="http://www.w3.org/1999/xhtml">
68 <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>
9 modify it under the terms of the GNU Lesser General Public
10 License as published by the Free Software Foundation; either
11 version 2.1 of the License, or (at your option) any later version.</p>
12
13 <p>This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.</p>
17
18 <p>You should have received a copy of the GNU Lesser General Public
19 License along with this library; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 02110-1301, USA.</p>
1922 </tp:license>
20 <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding"
21 tp:causes-havoc='not well-tested'>
22 <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
23 <signal name="ForwardingChanged" tp:name-for-bindings="Forwarding_Changed">
24 <arg name="Forward_To" type="u" tp:type="Contact_Handle">
25 <tp:docstring>
26 An integer contact handle to forward communication to
27 </tp:docstring>
28 </arg>
29 <tp:docstring>
30 Emitted when the forwarding contact handle for this connection has been
31 changed. An zero handle indicates forwarding is disabled.
32 </tp:docstring>
23
24 <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT"
25 tp:causes-havoc="experimental">
26 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
27
28 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
29 <p>This connection interface is for protocols that are capable of
30 signaling to remote contacts that incoming communication channels
31 should be instead sent to a separate contact. This might apply to
32 things such as call forwarding, for example.</p>
33
34 <p>In some cases, a CM may register forwarding rules with an external
35 service; in those cases, it will never see the incoming channel, and
36 the forwarding will happen automatically.</p>
37
38 <p>In other cases, the CM will handle the forwarding itself. When an
39 incoming channel is detected, the status of the local user will
40 determine whether or not a forwarding rule is matched. For some
41 rules, this MAY happen immediately (ie, if the user is Busy); for
42 others, there MAY be a timeout (in seconds) that must expire
43 before the forwarding rule is matched (the timeout is specified
44 by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p>
45
46 <p>Once a forwarding rule is matched and any necessary timeouts have
47 expired, the CM can forward the incoming channel to the specified
48 handle. If for whatever reason the remote handle does not accept
49 the channel AND the CM supports multiple forwarding entries AND
50 any necessary timeouts have expired (specified by the next entry
51 in the list), the CM can forward the incoming channel to the next
52 handle in the entry list. This continues until the list is
53 exhausted, or the incoming channel is accepted.</p>
54
55 <p>Note that the rule matches are only for the first entry in the
56 in the forwarding rule list. Once the incoming channel has been
57 forwarded, the next entry in the list (assuming one exists and
58 the contact that the channel has been forwarded to does not respond
59 after any necessary timeouts) is used regardless of the status of
60 the forwarded channel. The initial match rule might have been
61 Busy, whereas the contact that the channel has been forwarded to
62 might be offline. Even in this case, the Busy list is still
63 traversed until the channel is handled (or there are no more
64 forwarding entries in the list).</p>
65
66 <p>For example, assuming the following dict for Forwarding_Rules:</p>
67 <pre>
68 ForwardingRules = {
69 Busy: ( initial-timeout: 30, [
70 (handle: 3, timeout: 15),
71 (handle: 5, timeout: 20)
72 ]),
73 NoReply: ( initial-timeout: 15, [
74 (handle: 5, timeout: 30),
75 (handle: 3, timeout: 20)
76 ])
77 }</pre>
78
79 <p>We can imagine a scenario where an incoming channel is detected,
80 the media stream is available (ie, not Busy),
81 and the local user is online. While the CM is waiting for the local user to
82 accept the channel, it looks at NoReply's first timeout value. After 15s if
83 the local user hasn't accepted, the CM forwards the channel to Handle #5. The
84 CM then waits 30s for Handle #5 to accept the channel. If after 30s it does
85 not, the CM forwards the incoming channel to Handle #3, which will have
86 20s to accept the channel.</p>
87 </tp:docstring>
88
89 <tp:enum name="Forwarding_Condition" type="u">
90 <tp:docstring>
91 The various forwarding conditions that are supported by this interface.
92 In general, the conditions should not overlap; it should be very clear
93 which rule would be chosen given a CM's behavior with an incoming
94 channel. The exception to this is Unconditional,
95 which will override all other rules.
96 </tp:docstring>
97
98 <tp:enumvalue value="0" suffix="Unconditional">
99 <tp:docstring>
100 Incoming channels should always be forwarded. Note that setting this
101 will override any other rules. If not set, other rules will
102 be checked when an incoming communication channel is detected.
103 </tp:docstring>
104 </tp:enumvalue>
105
106 <tp:enumvalue value="1" suffix="Busy">
107 <tp:docstring>
108 <p>The incoming channel should be forwarded if a busy signal is
109 detected. What defines "Busy" is CM-specific (perhaps a single
110 resource is already in use, or a user's status is set to Busy
111 <tp:type>Connection_Presence_Type</tp:type>).</p>
112 <p>If initial timeout is specified for Busy condition and call
113 waiting is not supported by the service, the timeout will be
114 ignored.</p>
115 </tp:docstring>
116 </tp:enumvalue>
117
118 <tp:enumvalue value="2" suffix="No_Reply">
119 <tp:docstring>
120 The incoming channel should be forwarded if the local user doesn't
121 accept it within the specified amount of time.
122 </tp:docstring>
123 </tp:enumvalue>
124
125 <tp:enumvalue value="3" suffix="Not_Reachable">
126 <tp:docstring>
127 The incoming channel should be forwarded if the user is offline.
128 This could be a manual setting (the user has chosen to set their
129 presence to offline or invisible) or something specified by the
130 underlying network (the user is not within range of a cell tower).
131 </tp:docstring>
132 </tp:enumvalue>
133 </tp:enum>
134
135 <tp:struct name="Forwarding_Rule_Entry"
136 array-name="Forwarding_Rule_Entry_List">
137 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
138 <p>A forwarding rule entry. These MAY be chained together
139 for CMs that support chaining of forwards (in other words,
140 a forwarding rule may have multiple entries; if the contact
141 in the first entry doesn't respond, the incoming channel
142 might be forwarded to the contact in the second entry).</p>
143
144 <p>For CMs and protocols that don't support chaining of
145 entries, only the first entry would be used.</p>
146 </tp:docstring>
147
148 <tp:member type="u" name="Timeout">
149 <tp:docstring>
150 <p>The length of time (in seconds) to wait the contact to respond
151 to the forwarded channel. This MAY be ignored by the CM if it
152 isn't supported by the underlying network/protocol for the
153 specific status of the remote contact (for example, a GSM call
154 that is forwarded may return Not_Reachable immediately without
155 waiting for the timeout value to expire).</p>
156 <p>A value of 0 means the condition can match immediately. A
157 value of MAX_UINT32 means that the CM's default should be
158 used.</p>
159 </tp:docstring>
160 </tp:member>
161
162 <tp:member type="u" tp:type="Contact_Handle" name="Handle">
163 <tp:docstring>
164 The contact to forward an incoming channel to. If the handle
165 doesn't point to anything (e.g. points to a phone number that
166 doesn't exist), the entry SHOULD be skipped.
167 </tp:docstring>
168 </tp:member>
169 </tp:struct>
170
171 <tp:struct name="Forwarding_Rule_Chain">
172 <tp:docstring>
173 A chain of forwarding rules and an initial timeout after which
174 the rules are applied.
175 </tp:docstring>
176
177 <tp:member type="u" name="InitialTimeout">
178 <tp:docstring>Initial timeout for the rule.</tp:docstring>
179 </tp:member>
180
181 <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]">
182 <tp:docstring>The forwarding targets (an array of type
183 <tp:type>Forwarding_Rule_Entry</tp:type>).
184 </tp:docstring>
185 </tp:member>
186 </tp:struct>
187
188 <tp:mapping name="Forwarding_Rule_Map" array-name="">
189 <tp:docstring>A dictionary whose keys are forwarding conditions and
190 whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs.
191 </tp:docstring>
192
193 <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
194 <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain"
195 name="Rule_Chain" />
196 </tp:mapping>
197
198 <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name="">
199 <tp:docstring>A dictionary whose keys are forwarding conditions and
200 whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
201 for the condition.
202 </tp:docstring>
203 <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
204 <tp:member type="u" name="Chain_Length" />
205 </tp:mapping>
206
207 <property name="SupportedForwardingConditions" type="a{uu}" access="read"
208 tp:type="Supported_Forwarding_Conditions_Map"
209 tp:name-for-bindings="Supported_Forwarding_Conditions">
210 <tp:docstring>
211 <p>
212 A map of forwarding conditions supported on this connection to
213 maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
214 supported for the specific condition.
215 <tp:rationale>
216 When forwarding is done by the provider, different providers
217 might support different chain sizes, or provider and local
218 implementation chain sizes might differ.
219 </tp:rationale>
220 </p>
221 </tp:docstring>
222 </property>
223
224 <property name="ForwardingRules" type="a{u(ua(uu))}" access="read"
225 tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules">
226 <tp:docstring>
227 <p>The current forwarding rules that are enabled for this connection.
228 Forwarding rules each contain an array of type
229 <tp:type>Forwarding_Rule_Entry</tp:type>.</p>
230 </tp:docstring>
231 </property>
232
233 <signal name="ForwardingRuleChanged"
234 tp:name-for-bindings="Forwarding_Rule_Changed">
235 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
236 <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p>
237
238 <p>By the time this is emitted, the property MUST have been updated
239 with the new rules being active. If any protocol/network
240 requests must be made, they should be completed before the signal
241 is emitted.</p>
242 </tp:docstring>
243
244 <arg name="Condition" type="u" tp:type="Forwarding_Condition">
245 <tp:docstring>
246 The condition of the forwarding rule that's been changed.
247 </tp:docstring>
248 </arg>
249
250 <arg name="Timeout" type="u">
251 <tp:docstring>
252 The new initial timeout for the rule.
253 </tp:docstring>
254 </arg>
255
256 <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
257 <tp:docstring>
258 The new (and as of the emission of the signal, currently active)
259 forwards. The order is relevant; those at the lowest array index
260 are used first.
261 </tp:docstring>
262 </arg>
33263 </signal>
34 <method name="GetForwardingHandle"
35 tp:name-for-bindings="Get_Forwarding_Handle">
36 <arg direction="out" type="u" tp:type="Contact_Handle">
37 <tp:docstring>
38 An integer contact handle to whom incoming communication is forwarded
39 </tp:docstring>
40 </arg>
41 <tp:docstring>
42 Returns the current forwarding contact handle, or zero if none is set.
43 </tp:docstring>
264
265 <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule">
266 <tp:docstring>
267 Update the forwarding rules.
268 </tp:docstring>
269
270 <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition">
271 <tp:docstring>
272 <p>The forwarding rule to override. Note that this SHOULD not affect
273 other rules; setting a rule that overrides others (such as
274 Forwarding_Rule_Unconditional) will not modify other rules. This
275 means that when a client sets Forwarding_Rule_Busy and then
276 temporarily sets Forwarding_Rule_Unconditional, the
277 Forwarding_Rule_Busy rule will retain settings after
278 Forwarding_Rule_Unconditional, has been unset.</p>
279
280 <p>If the CM has no choice but to adjust multiple rules after a call
281 to this function (ie, due to the network or protocol forcing such
282 behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref>
283 signals for each changed rule. The order of the signals is
284 implementation-dependent, with the only requirement that the
285 last signal is for the rule that was originally requested to have
286 been changed (e.g. if Unconditional automatically modifies
287 Busy and NoReply, three
288 separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the
289 last signal being for Forwarding_Rule_Unconditional).</p>
290
291 <p>Each forwarding condition will occur no more than once in
292 the rule array. Setting a rule will overwrite the old rule
293 with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p>
294 </tp:docstring>
295 </arg>
296
297 <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
298 <tp:docstring>
299 The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to
300 activate for the rule. An empty array will effectively disable the
301 rule.
302 </tp:docstring>
303 </arg>
304
305 <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
306 <tp:docstring>
307 The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>).
308 This is the list of entries that is being replaced with the call to
309 <tp:member-ref>SetForwardingRule</tp:member-ref>.
310 </tp:docstring>
311 </arg>
44312 <tp:possible-errors>
45313 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
46314 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
47 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
315 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
316 <tp:docstring>
317 The specified Condition is not supported by this connection,
318 or the number of chained
319 <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should
320 be checked prior to calling
321 <tp:member-ref>SetForwardingRule</tp:member-ref>.
322 </tp:docstring>
323 </tp:error>
324 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
325 <tp:docstring>
326 A Handle that has been supplied is invalid.
327 </tp:docstring>
328 </tp:error>
48329 </tp:possible-errors>
49330 </method>
50 <method name="SetForwardingHandle"
51 tp:name-for-bindings="Set_Forwarding_Handle">
52 <arg direction="in" name="Forward_To" type="u" tp:type="Contact_Handle">
53 <tp:docstring>
54 An integer contact handle to forward incoming communications to
55 </tp:docstring>
56 </arg>
57 <tp:docstring>
58 Set a contact handle to forward incoming communications to. A zero
59 handle disables forwarding.
60 </tp:docstring>
61 <tp:possible-errors>
62 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
63 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
64 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
65 <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
66 <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
67 </tp:possible-errors>
68 </method>
69 <tp:docstring>
70 A connection interface for services which can signal to contacts
71 that they should instead contact a different user ID, effectively
72 forwarding all incoming communication channels to another contact on
73 the service.
74 </tp:docstring>
331
75332 </interface>
76333 </node>
77334 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+35
-1
spec/Connection_Interface_Location.xml less more
364364
365365 <tp:possible-errors>
366366 <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
367 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
367 <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
368 <tp:docstring>
369 The user's server does not support publishing their own location.
370 If it is possible to determine this ahead of time, the
371 <code>Can_Set</code> flag will not be set in
372 <tp:member-ref>SupportedLocationFeatures</tp:member-ref>.
373 </tp:docstring>
374 </tp:error>
368375 <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
369376 </tp:possible-errors>
370377 </method>
384391 supported).</tp:docstring>
385392 </property>
386393
394 <property name="SupportedLocationFeatures"
395 tp:name-for-bindings="Supported_Location_Features"
396 type="u" tp:type="Location_Features" access="read">
397 <tp:added version="0.19.6"/>
398 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
399 Indicates the Location features supported by this connection. This
400 property MAY be undefined before <tp:dbus-ref
401 namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref>
402 becomes <code>Connected</code>, but MUST remain constant thereafter.
403 </tp:docstring>
404 </property>
405
406 <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature">
407 <tp:flag suffix="Can_Set" value="1">
408 <tp:docstring>
409 Indicates that setting your own location with
410 <tp:member-ref>SetLocation</tp:member-ref> is supported on this
411 connection.
412 </tp:docstring>
413 </tp:flag>
414
415 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
416 Flags describing the Location features which may be supported on any
417 given connection.
418 </tp:docstring>
419 </tp:flags>
420
387421 <tp:contact-attribute name="location"
388422 type="a{sv}" tp:type="Location">
389423 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+11
-3
spec/Connection_Interface_Mail_Notification.xml less more
158158 </tp:struct>
159159
160160 <tp:struct name="Mail_Address" array-name="Mail_Address_List">
161 <tp:docstring>
162 A pair (name, address) representing an e-mail address,
163 such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk").
161 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
162 <p>A pair (name, address) representing an e-mail address,
163 such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At
164 least one of name and address MUST be provided. A missing element will
165 be represented by the empty string.</p>
166 <tp:rationale>
167 <p>The CM should provide as much information as possible, but not all
168 protocols provide both the displayed name and the address. (If a
169 protocol doesn't provide either, it should omit the appropriate
170 field from the <tp:type>Mail</tp:type> entirely.)</p>
171 </tp:rationale>
164172 </tp:docstring>
165173 <tp:member type="s" name="Name">
166174 <tp:docstring>The displayed name corresponding to the e-mail
+135
-0
spec/Connection_Interface_Service_Point.xml less more
0 <?xml version="1.0" ?>
1 <node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
2 <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
3 <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
4 <tp:license xmlns="http://www.w3.org/1999/xhtml">
5 <p>This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.</p>
9
10 <p>This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.</p>
14
15 <p>You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
18 </tp:license>
19 <interface name="org.freedesktop.Telepathy.Connection.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental">
20 <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
21
22 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
23 <p>An interface for connections whose channels may be able to indicate
24 specific they are connected to some form
25 of service station. For example, when
26 dialing 9-1-1 in the US, a GSM modem/network will recognize that as
27 an emergency call, and inform higher levels of the stack that the
28 call is being handled by an emergency service. In this example,
29 the call is handled by a Public Safety Answering Point (PSAP) which is labeled
30 as "urn:service:sos". Other networks and protocols may handle this
31 differently while still using this interface.</p>
32 </tp:docstring>
33
34 <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List">
35 <tp:member type="(us)" tp:type="Service_Point" name="ServicePoint">
36 <tp:docstring>
37 The service point.
38 </tp:docstring>
39 </tp:member>
40 <tp:member type="as" name="ServiceIDs">
41 <tp:docstring>
42 A list of IDs that are mapped to this service. This is provided as
43 a convenience for the UIs, but the preferred method for
44 requesting channel to a service is by setting <tp:dbus-ref
45 namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT">InitialServicePoint</tp:dbus-ref>
46 property in channel request.
47 </tp:docstring>
48 </tp:member>
49 <tp:docstring>
50 <p>Description of a service point and IDs which are mapped to id.</p>
51
52 <p>An example Service Point info for GSM emergency calls (callable through
53 "911" and "112") could look like:</p>
54
55 <pre>
56 ServicePointInfo = (
57 ServicePoint: (
58 ServicePointType: 1 (Emergency),
59 ServicePoint: "urn:service:sos"
60 ),
61 ServiceIDs: [ "911", "112" ]
62 )
63 </pre>
64 </tp:docstring>
65 </tp:struct>
66
67 <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points"
68 type="a((us)as)" tp:type="Service_Point_Info[]" access="read">
69 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
70 The list of all (known) service points.
71 </tp:docstring>
72 </property>
73
74 <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed">
75 <arg name="ServicePoints" type="a((us)as)" tp:type="Service_Point_Info[]">
76 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
77 <p>The new list of service points.</p>
78 </tp:docstring>
79 </arg>
80 <tp:docstring>
81 Indicate that the list of known service points (or their IDs) have
82 changed, presenting the new list.
83 </tp:docstring>
84 </signal>
85
86 <tp:struct name="Service_Point">
87 <tp:docstring>A service point.</tp:docstring>
88 <tp:member type="u" name="ServicePointType" tp:type="Service_Point_Type">
89 <tp:docstring>
90 The service type.
91 </tp:docstring>
92 </tp:member>
93 <tp:member type="s" name="Service">
94 <tp:docstring>
95 String representation of the service point. The representation is
96 service specific; it may be <tp:type>Uniform_Resource_Name</tp:type>
97 or may be in some other form. Empty, unused or unknown value is
98 represented by "".
99 </tp:docstring>
100 </tp:member>
101 </tp:struct>
102
103 <tp:enum name="Service_Point_Type" type="u">
104 <tp:docstring>
105 The various types of service points the channel might connect to.
106 </tp:docstring>
107
108 <tp:enumvalue value="0" suffix="None">
109 <tp:docstring>
110 The service point is not used/available.
111 </tp:docstring>
112 </tp:enumvalue>
113
114 <tp:enumvalue value="1" suffix="Emergency">
115 <tp:docstring>
116 The service point is a generic emergency point.
117 </tp:docstring>
118 </tp:enumvalue>
119
120 <tp:enumvalue value="2" suffix="Counseling">
121 <tp:docstring>
122 The service point is some kind of counseling service (ie, mental health
123 or child-services counseling).
124 </tp:docstring>
125 </tp:enumvalue>
126 </tp:enum>
127
128 <tp:simple-type name="Uniform_Resource_Name" type="s">
129 <tp:docstring>Uniform Resource Name as specified by
130 <a href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>.</tp:docstring>
131 </tp:simple-type>
132 </interface>
133 </node>
134 <!-- vim:set sw=2 sts=2 et ft=xml: -->
+10
-3
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.19.5</tp:version>
5 <tp:version>0.19.6</tp:version>
66
77 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
88 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
4141 <xi:include href="Connection.xml"/>
4242 <xi:include href="Connection_Future.xml"/>
4343 <xi:include href="Connection_Interface_Aliasing.xml"/>
44 <xi:include href="Connection_Interface_Anonymity.xml"/>
4445 <xi:include href="Connection_Interface_Avatars.xml"/>
4546 <xi:include href="Connection_Interface_Balance.xml"/>
4647 <xi:include href="Connection_Interface_Capabilities.xml"/>
48 <xi:include href="Connection_Interface_Cellular.xml"/>
4749 <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
50 <xi:include href="Connection_Interface_Contact_Groups.xml"/>
4851 <xi:include href="Connection_Interface_Contact_Info.xml"/>
52 <xi:include href="Connection_Interface_Contact_List.xml"/>
4953 <xi:include href="Connection_Interface_Contacts.xml"/>
54 <xi:include href="Connection_Interface_Forwarding.xml"/>
5055 <xi:include href="Connection_Interface_Location.xml"/>
56 <xi:include href="Connection_Interface_Service_Point.xml"/>
5157 <xi:include href="Connection_Interface_Mail_Notification.xml"/>
5258 <xi:include href="Connection_Interface_Presence.xml"/>
5359 <xi:include href="Connection_Interface_Renaming.xml"/>
98104 depending on its type:
99105 </p>
100106 </tp:docstring>
107 <xi:include href="Channel_Interface_Anonymity.xml"/>
101108 <xi:include href="Channel_Interface_Call_State.xml"/>
102109 <xi:include href="Channel_Interface_Chat_State.xml"/>
103110 <xi:include href="Channel_Interface_Conference.xml"/>
106113 <xi:include href="Channel_Interface_Group.xml"/>
107114 <xi:include href="Channel_Interface_Hold.xml"/>
108115 <xi:include href="Channel_Interface_HTML.xml"/>
116 <xi:include href="Channel_Interface_Service_Point.xml"/>
109117 <xi:include href="Channel_Interface_Password.xml"/>
110118 <xi:include href="Channel_Interface_Media_Signalling.xml"/>
111119 <xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
123131 <tp:section name="Calls">
124132 <xi:include href="Call_Content.xml"/>
125133 <xi:include href="Call_Content_Interface_Media.xml"/>
134 <xi:include href="Call_Content_Interface_Mute.xml"/>
126135 <xi:include href="Call_Content_Codec_Offer.xml"/>
127136 <xi:include href="Call_Stream.xml"/>
128137 <xi:include href="Call_Stream_Interface_Media.xml"/>
184193 <xi:include href="errors.xml"/>
185194 <xi:include href="generic-types.xml"/>
186195
187 <!-- Never implemented, insufficient (needs conditions)
188 <xi:include href="Connection_Interface_Forwarding.xml"/> -->
189196 <!-- Never implemented, vague
190197 <xi:include href="Connection_Interface_Privacy.xml"/> -->
191198 <!-- Causes havoc, never implemented, unclear requirements
+23
-0
spec/errors.xml less more
00 <?xml version="1.0" ?>
11 <tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">
2
3 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
4 <p>The D-Bus errors used in Telepathy all start with
5 <code>org.freedesktop.Telepathy.Error.</code>. They are used in
6 D-Bus messages of type ERROR, and also as plain strings annotated with
7 the <tp:type>DBus_Error_Name</tp:type> type.</p>
8
9 <p>In principle, any method can raise any error (this is a general fact
10 of IPC). For instance, generic D-Bus errors starting with
11 <code>org.freedesktop.DBus.Error.</code> will occur in some
12 situations.</p>
13
14 <p>Telepathy methods can also raise implementation-specific errors to
15 indicate specialized failure conditions. For better interoperability,
16 if a suitable Telepathy error exists, it should be preferred.</p>
17
18 <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code>
19 is reserved for use by the D-Bus client implementation in telepathy-qt4,
20 which uses it to represent certain error situations that did not involve
21 a D-Bus ERROR message. These errors are defined and documented as part of
22 telepathy-qt4's C++ API, and should not be used on D-Bus.</p>
23 </tp:docstring>
24
225 <tp:error name="Network Error">
326 <tp:docstring>
427 Raised when there is an error reading from or writing to the network.
+30
-0
spec/generic-types.xml less more
164164 </tp:member>
165165 </tp:struct>
166166
167 <tp:simple-type name="User_Action_Timestamp" type="x">
168 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
169 <p>The time at which an user action occurred. This type has the 2
170 following special values:</p>
171
172 <p>0: the action doesn't involve any user action. Clients
173 SHOULD avoid stealing focus when presenting the channel.</p>
174
175 <p>MAX_INT64: clients SHOULD behave as though the user action happened
176 at the current time, e.g. a client MAY request that its window gains
177 focus.
178 </p>
179
180 <tp:rationale>
181 <p>This can be used by clients that can't know the X server time like
182 command line applications for example.</p>
183 </tp:rationale>
184
185 <p>For all the other values it corresponds to the time of the user
186 action. Clients SHOULD use this for focus-stealing prevention,
187 if applicable.
188 Note that the time is dependant on the local
189 environment and so is not necessarily a wall-clock time.
190 For example in an X environment it's expected to be the X timestamp
191 of events.
192 This corresponds to the _NET_WM_USER_TIME property in
193 <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
194 </tp:docstring>
195 </tp:simple-type>
196
167197 </tp:generic-types>
+0
-37
tools/c-errors-enum-generator.xsl less more
0 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
1 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
2 exclude-result-prefixes="tp">
3
4 <xsl:output method="text" indent="no" encoding="ascii"/>
5
6 <xsl:template match="tp:error">
7 /* <xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/>
8 <xsl:value-of select="tp:docstring"/> */
9 <xsl:text> TP_ERROR_</xsl:text><xsl:value-of select="translate(@name, 'abcdefghijklmnopqrstuvwxyz .', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ__')"/>,
10 </xsl:template>
11
12 <xsl:template match="text()"/>
13
14 <xsl:template match="/tp:errors">/* Generated from the Telepathy spec
15
16 <xsl:for-each select="tp:copyright">
17 <xsl:value-of select="."/><xsl:text>
18 </xsl:text></xsl:for-each><xsl:text>
19 </xsl:text><xsl:value-of select="tp:license"/>
20 */
21
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25
26 typedef enum {
27 <xsl:apply-templates select="tp:error"/>} TpError;
28
29 #ifdef __cplusplus
30 }
31 #endif
32 </xsl:template>
33
34 </xsl:stylesheet>
35
36 <!-- vim:set sw=2 sts=2 et noai noci: -->
+0
-1266
tools/doc-generator.xsl less more
0 <!-- Generate HTML documentation from the Telepathy specification.
1 The master copy of this stylesheet is in the Telepathy spec repository -
2 please make any changes there.
3
4 Copyright (C) 2006-2008 Collabora Limited
5
6 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.
10
11 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.
15
16 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 St, Fifth Floor, Boston, MA 02110-1301 USA
19 -->
20
21 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
22 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
23 xmlns:html="http://www.w3.org/1999/xhtml"
24 exclude-result-prefixes="tp html">
25 <!--Don't move the declaration of the HTML namespace up here — XMLNSs
26 don't work ideally in the presence of two things that want to use the
27 absence of a prefix, sadly. -->
28
29 <xsl:param name="allow-undefined-interfaces" select="false()"/>
30
31 <xsl:template match="html:* | @*" mode="html">
32 <xsl:copy>
33 <xsl:apply-templates mode="html" select="@*|node()"/>
34 </xsl:copy>
35 </xsl:template>
36
37 <xsl:template match="tp:type" mode="html">
38 <xsl:call-template name="tp-type">
39 <xsl:with-param name="tp-type" select="string(.)"/>
40 </xsl:call-template>
41 </xsl:template>
42
43 <!-- tp:dbus-ref: reference a D-Bus interface, signal, method or property -->
44 <xsl:template match="tp:dbus-ref" mode="html">
45 <xsl:variable name="name">
46 <xsl:choose>
47 <xsl:when test="@namespace">
48 <xsl:value-of select="@namespace"/>
49 <xsl:text>.</xsl:text>
50 </xsl:when>
51 </xsl:choose>
52 <xsl:value-of select="string(.)"/>
53 </xsl:variable>
54
55 <xsl:choose>
56 <xsl:when test="//interface[@name=$name]
57 or //interface/method[concat(../@name, '.', @name)=$name]
58 or //interface/signal[concat(../@name, '.', @name)=$name]
59 or //interface/property[concat(../@name, '.', @name)=$name]
60 or //interface[@name=concat($name, '.DRAFT')]
61 or //interface/method[
62 concat(../@name, '.', @name)=concat($name, '.DRAFT')]
63 or //interface/signal[
64 concat(../@name, '.', @name)=concat($name, '.DRAFT')]
65 or //interface/property[
66 concat(../@name, '.', @name)=concat($name, '.DRAFT')]
67 ">
68 <a xmlns="http://www.w3.org/1999/xhtml" href="#{$name}">
69 <xsl:value-of select="string(.)"/>
70 </a>
71 </xsl:when>
72
73 <xsl:when test="$allow-undefined-interfaces">
74 <span xmlns="http://www.w3.org/1999/xhtml" title="defined elsewhere">
75 <xsl:value-of select="string(.)"/>
76 </span>
77 </xsl:when>
78
79 <xsl:otherwise>
80 <xsl:message terminate="yes">
81 <xsl:text>ERR: cannot find D-Bus interface, method, </xsl:text>
82 <xsl:text>signal or property called '</xsl:text>
83 <xsl:value-of select="$name"/>
84 <xsl:text>'&#10;</xsl:text>
85 </xsl:message>
86 </xsl:otherwise>
87 </xsl:choose>
88 </xsl:template>
89
90 <!-- tp:member-ref: reference a property of the current interface -->
91 <xsl:template match="tp:member-ref" mode="html">
92 <xsl:variable name="prefix" select="concat(ancestor::interface/@name,
93 '.')"/>
94 <xsl:variable name="name" select="string(.)"/>
95
96 <xsl:if test="not(ancestor::interface)">
97 <xsl:message terminate="yes">
98 <xsl:text>ERR: Cannot use tp:member-ref when not in an</xsl:text>
99 <xsl:text> &lt;interface&gt;&#10;</xsl:text>
100 </xsl:message>
101 </xsl:if>
102
103 <xsl:choose>
104 <xsl:when test="ancestor::interface/signal[@name=$name]"/>
105 <xsl:when test="ancestor::interface/method[@name=$name]"/>
106 <xsl:when test="ancestor::interface/property[@name=$name]"/>
107 <xsl:otherwise>
108 <xsl:message terminate="yes">
109 <xsl:text>ERR: interface </xsl:text>
110 <xsl:value-of select="ancestor::interface/@name"/>
111 <xsl:text> has no signal/method/property called </xsl:text>
112 <xsl:value-of select="$name"/>
113 <xsl:text>&#10;</xsl:text>
114 </xsl:message>
115 </xsl:otherwise>
116 </xsl:choose>
117
118 <a xmlns="http://www.w3.org/1999/xhtml" href="#{$prefix}{$name}">
119 <xsl:value-of select="$name"/>
120 </a>
121 </xsl:template>
122
123 <xsl:template match="*" mode="identity">
124 <xsl:copy>
125 <xsl:apply-templates mode="identity"/>
126 </xsl:copy>
127 </xsl:template>
128
129 <xsl:template match="tp:docstring">
130 <xsl:apply-templates mode="html"/>
131 </xsl:template>
132
133 <xsl:template match="tp:added">
134 <p class="added" xmlns="http://www.w3.org/1999/xhtml">Added in
135 version <xsl:value-of select="@version"/>.
136 <xsl:apply-templates select="node()" mode="html"/></p>
137 </xsl:template>
138
139 <xsl:template match="tp:changed">
140 <xsl:choose>
141 <xsl:when test="node()">
142 <p class="changed" xmlns="http://www.w3.org/1999/xhtml">Changed in
143 version <xsl:value-of select="@version"/>:
144 <xsl:apply-templates select="node()" mode="html"/></p>
145 </xsl:when>
146 <xsl:otherwise>
147 <p class="changed">Changed in version
148 <xsl:value-of select="@version"/></p>
149 </xsl:otherwise>
150 </xsl:choose>
151 </xsl:template>
152
153 <xsl:template match="tp:deprecated">
154 <p class="deprecated" xmlns="http://www.w3.org/1999/xhtml">Deprecated
155 since version <xsl:value-of select="@version"/>.
156 <xsl:apply-templates select="node()" mode="html"/></p>
157 </xsl:template>
158
159 <xsl:template match="tp:rationale" mode="html">
160 <div xmlns="http://www.w3.org/1999/xhtml" class="rationale">
161 <xsl:apply-templates select="node()" mode="html"/>
162 </div>
163 </xsl:template>
164
165 <xsl:template match="tp:errors">
166 <h1 xmlns="http://www.w3.org/1999/xhtml">Errors</h1>
167 <xsl:apply-templates/>
168 </xsl:template>
169
170 <xsl:template match="tp:generic-types">
171 <h1 xmlns="http://www.w3.org/1999/xhtml">Generic types</h1>
172 <xsl:call-template name="do-types"/>
173 </xsl:template>
174
175 <xsl:template name="do-types">
176 <xsl:if test="tp:simple-type">
177 <h2 xmlns="http://www.w3.org/1999/xhtml">Simple types</h2>
178 <xsl:apply-templates select="tp:simple-type"/>
179 </xsl:if>
180
181 <xsl:if test="tp:enum">
182 <h2 xmlns="http://www.w3.org/1999/xhtml">Enumerated types:</h2>
183 <xsl:apply-templates select="tp:enum"/>
184 </xsl:if>
185
186 <xsl:if test="tp:flags">
187 <h2 xmlns="http://www.w3.org/1999/xhtml">Sets of flags:</h2>
188 <xsl:apply-templates select="tp:flags"/>
189 </xsl:if>
190
191 <xsl:if test="tp:struct">
192 <h2 xmlns="http://www.w3.org/1999/xhtml">Structure types</h2>
193 <xsl:apply-templates select="tp:struct"/>
194 </xsl:if>
195
196 <xsl:if test="tp:mapping">
197 <h2 xmlns="http://www.w3.org/1999/xhtml">Mapping types</h2>
198 <xsl:apply-templates select="tp:mapping"/>
199 </xsl:if>
200
201 <xsl:if test="tp:external-type">
202 <h2 xmlns="http://www.w3.org/1999/xhtml">Types defined elsewhere</h2>
203 <dl><xsl:apply-templates select="tp:external-type"/></dl>
204 </xsl:if>
205 </xsl:template>
206
207 <xsl:template match="tp:error">
208 <h2 xmlns="http://www.w3.org/1999/xhtml"><a name="{concat(../@namespace, '.', translate(@name, ' ', ''))}"></a><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></h2>
209 <xsl:apply-templates select="tp:docstring"/>
210 <xsl:apply-templates select="tp:added"/>
211 <xsl:apply-templates select="tp:changed"/>
212 <xsl:apply-templates select="tp:deprecated"/>
213 </xsl:template>
214
215 <xsl:template match="/tp:spec/tp:copyright">
216 <div xmlns="http://www.w3.org/1999/xhtml">
217 <xsl:apply-templates mode="text"/>
218 </div>
219 </xsl:template>
220 <xsl:template match="/tp:spec/tp:license">
221 <div xmlns="http://www.w3.org/1999/xhtml" class="license">
222 <xsl:apply-templates mode="html"/>
223 </div>
224 </xsl:template>
225
226 <xsl:template match="tp:copyright"/>
227 <xsl:template match="tp:license"/>
228
229 <xsl:template match="interface">
230 <h1 xmlns="http://www.w3.org/1999/xhtml"><a name="{@name}"></a><xsl:value-of select="@name"/></h1>
231
232 <xsl:if test="@tp:causes-havoc">
233 <p xmlns="http://www.w3.org/1999/xhtml" class="causes-havoc">
234 This interface is <xsl:value-of select="@tp:causes-havoc"/>
235 and is likely to cause havoc to your API/ABI if bindings are generated.
236 Don't include it in libraries that care about compatibility.
237 </p>
238 </xsl:if>
239
240 <xsl:if test="tp:requires">
241 <p>Implementations of this interface must also implement:</p>
242 <ul xmlns="http://www.w3.org/1999/xhtml">
243 <xsl:for-each select="tp:requires">
244 <li><code><a href="#{@interface}"><xsl:value-of select="@interface"/></a></code></li>
245 </xsl:for-each>
246 </ul>
247 </xsl:if>
248
249 <xsl:apply-templates select="tp:docstring" />
250 <xsl:apply-templates select="tp:added"/>
251 <xsl:apply-templates select="tp:changed"/>
252 <xsl:apply-templates select="tp:deprecated"/>
253
254 <xsl:choose>
255 <xsl:when test="method">
256 <h2 xmlns="http://www.w3.org/1999/xhtml">Methods:</h2>
257 <xsl:apply-templates select="method"/>
258 </xsl:when>
259 <xsl:otherwise>
260 <p xmlns="http://www.w3.org/1999/xhtml">Interface has no methods.</p>
261 </xsl:otherwise>
262 </xsl:choose>
263
264 <xsl:choose>
265 <xsl:when test="signal">
266 <h2 xmlns="http://www.w3.org/1999/xhtml">Signals:</h2>
267 <xsl:apply-templates select="signal"/>
268 </xsl:when>
269 <xsl:otherwise>
270 <p xmlns="http://www.w3.org/1999/xhtml">Interface has no signals.</p>
271 </xsl:otherwise>
272 </xsl:choose>
273
274 <xsl:choose>
275 <xsl:when test="tp:property">
276 <h2 xmlns="http://www.w3.org/1999/xhtml">Telepathy Properties:</h2>
277 <p xmlns="http://www.w3.org/1999/xhtml">Accessed using the
278 <a href="#org.freedesktop.Telepathy.Properties">Telepathy
279 Properties</a> interface.</p>
280 <dl xmlns="http://www.w3.org/1999/xhtml">
281 <xsl:apply-templates select="tp:property"/>
282 </dl>
283 </xsl:when>
284 <xsl:otherwise>
285 <p xmlns="http://www.w3.org/1999/xhtml">Interface has no Telepathy
286 properties.</p>
287 </xsl:otherwise>
288 </xsl:choose>
289
290 <xsl:choose>
291 <xsl:when test="property">
292 <h2 xmlns="http://www.w3.org/1999/xhtml">D-Bus core Properties:</h2>
293 <p xmlns="http://www.w3.org/1999/xhtml">Accessed using the
294 org.freedesktop.DBus.Properties interface.</p>
295 <dl xmlns="http://www.w3.org/1999/xhtml">
296 <xsl:apply-templates select="property"/>
297 </dl>
298 </xsl:when>
299 <xsl:otherwise>
300 <p xmlns="http://www.w3.org/1999/xhtml">Interface has no D-Bus core
301 properties.</p>
302 </xsl:otherwise>
303 </xsl:choose>
304
305 <xsl:call-template name="do-types"/>
306
307 </xsl:template>
308
309 <xsl:template match="tp:flags">
310
311 <xsl:if test="not(@name) or @name = ''">
312 <xsl:message terminate="yes">
313 <xsl:text>ERR: missing @name on a tp:flags type&#10;</xsl:text>
314 </xsl:message>
315 </xsl:if>
316
317 <xsl:if test="not(@type) or @type = ''">
318 <xsl:message terminate="yes">
319 <xsl:text>ERR: missing @type on tp:flags type</xsl:text>
320 <xsl:value-of select="@name"/>
321 <xsl:text>&#10;</xsl:text>
322 </xsl:message>
323 </xsl:if>
324
325 <h3>
326 <a name="type-{@name}">
327 <xsl:value-of select="@name"/>
328 </a>
329 </h3>
330 <xsl:apply-templates select="tp:docstring" />
331 <xsl:apply-templates select="tp:added"/>
332 <xsl:apply-templates select="tp:changed"/>
333 <xsl:apply-templates select="tp:deprecated"/>
334 <dl xmlns="http://www.w3.org/1999/xhtml">
335 <xsl:variable name="value-prefix">
336 <xsl:choose>
337 <xsl:when test="@value-prefix">
338 <xsl:value-of select="@value-prefix"/>
339 </xsl:when>
340 <xsl:otherwise>
341 <xsl:value-of select="@name"/>
342 </xsl:otherwise>
343 </xsl:choose>
344 </xsl:variable>
345 <xsl:for-each select="tp:flag">
346 <dt xmlns="http://www.w3.org/1999/xhtml"><code><xsl:value-of select="concat($value-prefix, '_', @suffix)"/> = <xsl:value-of select="@value"/></code></dt>
347 <xsl:choose>
348 <xsl:when test="tp:docstring">
349 <dd xmlns="http://www.w3.org/1999/xhtml">
350 <xsl:apply-templates select="tp:docstring" />
351 <xsl:apply-templates select="tp:added"/>
352 <xsl:apply-templates select="tp:changed"/>
353 <xsl:apply-templates select="tp:deprecated"/>
354 </dd>
355 </xsl:when>
356 <xsl:otherwise>
357 <dd xmlns="http://www.w3.org/1999/xhtml">(Undocumented)</dd>
358 </xsl:otherwise>
359 </xsl:choose>
360 </xsl:for-each>
361 </dl>
362 </xsl:template>
363
364 <xsl:template match="tp:enum">
365
366 <xsl:if test="not(@name) or @name = ''">
367 <xsl:message terminate="yes">
368 <xsl:text>ERR: missing @name on a tp:enum type&#10;</xsl:text>
369 </xsl:message>
370 </xsl:if>
371
372 <xsl:if test="not(@type) or @type = ''">
373 <xsl:message terminate="yes">
374 <xsl:text>ERR: missing @type on tp:enum type</xsl:text>
375 <xsl:value-of select="@name"/>
376 <xsl:text>&#10;</xsl:text>
377 </xsl:message>
378 </xsl:if>
379
380 <h3 xmlns="http://www.w3.org/1999/xhtml">
381 <a name="type-{@name}">
382 <xsl:value-of select="@name"/>
383 </a>
384 </h3>
385 <xsl:apply-templates select="tp:docstring" />
386 <xsl:apply-templates select="tp:added"/>
387 <xsl:apply-templates select="tp:changed"/>
388 <xsl:apply-templates select="tp:deprecated"/>
389 <dl xmlns="http://www.w3.org/1999/xhtml">
390 <xsl:variable name="value-prefix">
391 <xsl:choose>
392 <xsl:when test="@value-prefix">
393 <xsl:value-of select="@value-prefix"/>
394 </xsl:when>
395 <xsl:otherwise>
396 <xsl:value-of select="@name"/>
397 </xsl:otherwise>
398 </xsl:choose>
399 </xsl:variable>
400 <xsl:for-each select="tp:enumvalue">
401 <dt xmlns="http://www.w3.org/1999/xhtml"><code><xsl:value-of select="concat($value-prefix, '_', @suffix)"/> = <xsl:value-of select="@value"/></code></dt>
402 <xsl:choose>
403 <xsl:when test="tp:docstring">
404 <dd xmlns="http://www.w3.org/1999/xhtml">
405 <xsl:apply-templates select="tp:docstring" />
406 <xsl:apply-templates select="tp:added"/>
407 <xsl:apply-templates select="tp:changed"/>
408 <xsl:apply-templates select="tp:deprecated"/>
409 </dd>
410 </xsl:when>
411 <xsl:otherwise>
412 <dd xmlns="http://www.w3.org/1999/xhtml">(Undocumented)</dd>
413 </xsl:otherwise>
414 </xsl:choose>
415 </xsl:for-each>
416 </dl>
417 </xsl:template>
418
419 <xsl:template name="binding-name-check">
420 <xsl:if test="not(@tp:name-for-bindings)">
421 <xsl:message terminate="yes">
422 <xsl:text>ERR: Binding name missing from </xsl:text>
423 <xsl:value-of select="parent::interface/@name"/>
424 <xsl:text>.</xsl:text>
425 <xsl:value-of select="@name"/>
426 <xsl:text>&#10;</xsl:text>
427 </xsl:message>
428 </xsl:if>
429
430 <xsl:if test="translate(@tp:name-for-bindings, '_', '') != @name">
431 <xsl:message terminate="yes">
432 <xsl:text>ERR: Binding name </xsl:text>
433 <xsl:value-of select="@tp:name-for-bindings"/>
434 <xsl:text> doesn't correspond to D-Bus name </xsl:text>
435 <xsl:value-of select="@name"/>
436 <xsl:text>&#10;</xsl:text>
437 </xsl:message>
438 </xsl:if>
439 </xsl:template>
440
441 <xsl:template match="property">
442
443 <xsl:call-template name="binding-name-check"/>
444
445 <xsl:if test="not(parent::interface)">
446 <xsl:message terminate="yes">
447 <xsl:text>ERR: property </xsl:text>
448 <xsl:value-of select="@name"/>
449 <xsl:text> does not have an interface as parent&#10;</xsl:text>
450 </xsl:message>
451 </xsl:if>
452
453 <xsl:if test="not(@name) or @name = ''">
454 <xsl:message terminate="yes">
455 <xsl:text>ERR: missing @name on a property of </xsl:text>
456 <xsl:value-of select="../@name"/>
457 <xsl:text>&#10;</xsl:text>
458 </xsl:message>
459 </xsl:if>
460
461 <xsl:if test="not(@type) or @type = ''">
462 <xsl:message terminate="yes">
463 <xsl:text>ERR: missing @type on property </xsl:text>
464 <xsl:value-of select="concat(../@name, '.', @name)"/>
465 <xsl:text>: '</xsl:text>
466 <xsl:value-of select="@access"/>
467 <xsl:text>'&#10;</xsl:text>
468 </xsl:message>
469 </xsl:if>
470
471 <dt xmlns="http://www.w3.org/1999/xhtml">
472 <a name="{concat(../@name, '.', @name)}">
473 <code><xsl:value-of select="@name"/></code>
474 </a>
475 <xsl:text> − </xsl:text>
476 <code><xsl:value-of select="@type"/></code>
477 <xsl:call-template name="parenthesized-tp-type"/>
478 <xsl:text>, </xsl:text>
479 <xsl:choose>
480 <xsl:when test="@access = 'read'">
481 <xsl:text>read-only</xsl:text>
482 </xsl:when>
483 <xsl:when test="@access = 'write'">
484 <xsl:text>write-only</xsl:text>
485 </xsl:when>
486 <xsl:when test="@access = 'readwrite'">
487 <xsl:text>read/write</xsl:text>
488 </xsl:when>
489 <xsl:otherwise>
490 <xsl:message terminate="yes">
491 <xsl:text>ERR: unknown or missing value for </xsl:text>
492 <xsl:text>@access on property </xsl:text>
493 <xsl:value-of select="concat(../@name, '.', @name)"/>
494 <xsl:text>: '</xsl:text>
495 <xsl:value-of select="@access"/>
496 <xsl:text>'&#10;</xsl:text>
497 </xsl:message>
498 </xsl:otherwise>
499 </xsl:choose>
500 </dt>
501 <dd xmlns="http://www.w3.org/1999/xhtml">
502 <xsl:apply-templates select="tp:docstring"/>
503 <xsl:apply-templates select="tp:added"/>
504 <xsl:apply-templates select="tp:changed"/>
505 <xsl:apply-templates select="tp:deprecated"/>
506 </dd>
507 </xsl:template>
508
509 <xsl:template match="tp:property">
510 <dt xmlns="http://www.w3.org/1999/xhtml">
511 <xsl:if test="@name">
512 <code><xsl:value-of select="@name"/></code> −
513 </xsl:if>
514 <code><xsl:value-of select="@type"/></code>
515 </dt>
516 <dd xmlns="http://www.w3.org/1999/xhtml">
517 <xsl:apply-templates select="tp:docstring"/>
518 <xsl:apply-templates select="tp:added"/>
519 <xsl:apply-templates select="tp:changed"/>
520 <xsl:apply-templates select="tp:deprecated"/>
521 </dd>
522 </xsl:template>
523
524 <xsl:template match="tp:mapping">
525 <div xmlns="http://www.w3.org/1999/xhtml" class="struct">
526 <h3>
527 <a name="type-{@name}">
528 <xsl:value-of select="@name"/>
529 </a> − a{
530 <xsl:for-each select="tp:member">
531 <xsl:value-of select="@type"/>
532 <xsl:text>: </xsl:text>
533 <xsl:value-of select="@name"/>
534 <xsl:if test="position() != last()"> &#x2192; </xsl:if>
535 </xsl:for-each>
536 }
537 </h3>
538 <div class="docstring">
539 <xsl:apply-templates select="tp:docstring"/>
540 <xsl:if test="string(@array-name) != ''">
541 <p>In bindings that need a separate name, arrays of
542 <xsl:value-of select="@name"/> should be called
543 <xsl:value-of select="@array-name"/>.</p>
544 </xsl:if>
545 </div>
546 <div>
547 <h4>Members</h4>
548 <dl>
549 <xsl:apply-templates select="tp:member" mode="members-in-docstring"/>
550 </dl>
551 </div>
552 </div>
553 </xsl:template>
554
555 <xsl:template match="tp:docstring" mode="in-index"/>
556
557 <xsl:template match="tp:simple-type | tp:enum | tp:flags | tp:external-type"
558 mode="in-index">
559 − <xsl:value-of select="@type"/>
560 </xsl:template>
561
562 <xsl:template match="tp:simple-type">
563
564 <xsl:if test="not(@name) or @name = ''">
565 <xsl:message terminate="yes">
566 <xsl:text>ERR: missing @name on a tp:simple-type&#10;</xsl:text>
567 </xsl:message>
568 </xsl:if>
569
570 <xsl:if test="not(@type) or @type = ''">
571 <xsl:message terminate="yes">
572 <xsl:text>ERR: missing @type on tp:simple-type</xsl:text>
573 <xsl:value-of select="@name"/>
574 <xsl:text>&#10;</xsl:text>
575 </xsl:message>
576 </xsl:if>
577
578 <div xmlns="http://www.w3.org/1999/xhtml" class="simple-type">
579 <h3>
580 <a name="type-{@name}">
581 <xsl:value-of select="@name"/>
582 </a> − <xsl:value-of select="@type"/>
583 </h3>
584 <div class="docstring">
585 <xsl:apply-templates select="tp:docstring"/>
586 <xsl:apply-templates select="tp:added"/>
587 <xsl:apply-templates select="tp:changed"/>
588 <xsl:apply-templates select="tp:deprecated"/>
589 </div>
590 </div>
591 </xsl:template>
592
593 <xsl:template match="tp:external-type">
594
595 <xsl:if test="not(@name) or @name = ''">
596 <xsl:message terminate="yes">
597 <xsl:text>ERR: missing @name on a tp:external-type&#10;</xsl:text>
598 </xsl:message>
599 </xsl:if>
600
601 <xsl:if test="not(@type) or @type = ''">
602 <xsl:message terminate="yes">
603 <xsl:text>ERR: missing @type on tp:external-type</xsl:text>
604 <xsl:value-of select="@name"/>
605 <xsl:text>&#10;</xsl:text>
606 </xsl:message>
607 </xsl:if>
608
609 <div xmlns="http://www.w3.org/1999/xhtml" class="external-type">
610 <dt>
611 <a name="type-{@name}">
612 <xsl:value-of select="@name"/>
613 </a> − <xsl:value-of select="@type"/>
614 </dt>
615 <dd>Defined by: <xsl:value-of select="@from"/></dd>
616 </div>
617 </xsl:template>
618
619 <xsl:template match="tp:struct" mode="in-index">
620 − ( <xsl:for-each select="tp:member">
621 <xsl:value-of select="@type"/>
622 <xsl:if test="position() != last()">, </xsl:if>
623 </xsl:for-each> )
624 </xsl:template>
625
626 <xsl:template match="tp:mapping" mode="in-index">
627 − a{ <xsl:for-each select="tp:member">
628 <xsl:value-of select="@type"/>
629 <xsl:if test="position() != last()"> &#x2192; </xsl:if>
630 </xsl:for-each> }
631 </xsl:template>
632
633 <xsl:template match="tp:struct">
634 <div xmlns="http://www.w3.org/1999/xhtml" class="struct">
635 <h3>
636 <a name="type-{@name}">
637 <xsl:value-of select="@name"/>
638 </a> − (
639 <xsl:for-each select="tp:member">
640 <xsl:value-of select="@type"/>
641 <xsl:text>: </xsl:text>
642 <xsl:value-of select="@name"/>
643 <xsl:if test="position() != last()">, </xsl:if>
644 </xsl:for-each>
645 )
646 </h3>
647 <div class="docstring">
648 <xsl:apply-templates select="tp:docstring"/>
649 <xsl:apply-templates select="tp:added"/>
650 <xsl:apply-templates select="tp:changed"/>
651 <xsl:apply-templates select="tp:deprecated"/>
652 </div>
653 <xsl:choose>
654 <xsl:when test="string(@array-name) != ''">
655 <p>In bindings that need a separate name, arrays of
656 <xsl:value-of select="@name"/> should be called
657 <xsl:value-of select="@array-name"/>.</p>
658 </xsl:when>
659 <xsl:otherwise>
660 <p>Arrays of <xsl:value-of select="@name"/> don't generally
661 make sense.</p>
662 </xsl:otherwise>
663 </xsl:choose>
664 <div>
665 <h4>Members</h4>
666 <dl>
667 <xsl:apply-templates select="tp:member" mode="members-in-docstring"/>
668 </dl>
669 </div>
670 </div>
671 </xsl:template>
672
673 <xsl:template match="method">
674
675 <xsl:call-template name="binding-name-check"/>
676
677 <xsl:if test="not(parent::interface)">
678 <xsl:message terminate="yes">
679 <xsl:text>ERR: method </xsl:text>
680 <xsl:value-of select="@name"/>
681 <xsl:text> does not have an interface as parent&#10;</xsl:text>
682 </xsl:message>
683 </xsl:if>
684
685 <xsl:if test="not(@name) or @name = ''">
686 <xsl:message terminate="yes">
687 <xsl:text>ERR: missing @name on a method of </xsl:text>
688 <xsl:value-of select="../@name"/>
689 <xsl:text>&#10;</xsl:text>
690 </xsl:message>
691 </xsl:if>
692
693 <xsl:for-each select="arg">
694 <xsl:if test="not(@type) or @type = ''">
695 <xsl:message terminate="yes">
696 <xsl:text>ERR: an arg of method </xsl:text>
697 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
698 <xsl:text> has no type</xsl:text>
699 </xsl:message>
700 </xsl:if>
701 <xsl:choose>
702 <xsl:when test="@direction='in'">
703 <xsl:if test="not(@name) or @name = ''">
704 <xsl:message terminate="yes">
705 <xsl:text>ERR: an 'in' arg of method </xsl:text>
706 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
707 <xsl:text> has no name</xsl:text>
708 </xsl:message>
709 </xsl:if>
710 </xsl:when>
711 <xsl:when test="@direction='out'">
712 <xsl:if test="not(@name) or @name = ''">
713 <xsl:message terminate="no">
714 <xsl:text>WARNING: an 'out' arg of method </xsl:text>
715 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
716 <xsl:text> has no name</xsl:text>
717 </xsl:message>
718 </xsl:if>
719 </xsl:when>
720 <xsl:otherwise>
721 <xsl:message terminate="yes">
722 <xsl:text>ERR: an arg of method </xsl:text>
723 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
724 <xsl:text> has direction neither 'in' nor 'out'</xsl:text>
725 </xsl:message>
726 </xsl:otherwise>
727 </xsl:choose>
728 </xsl:for-each>
729
730 <div xmlns="http://www.w3.org/1999/xhtml" class="method">
731 <h3 xmlns="http://www.w3.org/1999/xhtml">
732 <a name="{concat(../@name, concat('.', @name))}">
733 <xsl:value-of select="@name"/>
734 </a> (
735 <xsl:for-each xmlns="" select="arg[@direction='in']">
736 <xsl:value-of select="@type"/>: <xsl:value-of select="@name"/>
737 <xsl:if test="position() != last()">, </xsl:if>
738 </xsl:for-each>
739 ) &#x2192;
740 <xsl:choose>
741 <xsl:when test="arg[@direction='out']">
742 <xsl:for-each xmlns="" select="arg[@direction='out']">
743 <xsl:value-of select="@type"/>
744 <xsl:if test="position() != last()">, </xsl:if>
745 </xsl:for-each>
746 </xsl:when>
747 <xsl:otherwise>nothing</xsl:otherwise>
748 </xsl:choose>
749 </h3>
750 <div xmlns="http://www.w3.org/1999/xhtml" class="docstring">
751 <xsl:apply-templates select="tp:docstring" />
752 <xsl:apply-templates select="tp:added"/>
753 <xsl:apply-templates select="tp:changed"/>
754 <xsl:apply-templates select="tp:deprecated"/>
755 </div>
756
757 <xsl:if test="arg[@direction='in']">
758 <div xmlns="http://www.w3.org/1999/xhtml">
759 <h4>Parameters</h4>
760 <dl xmlns="http://www.w3.org/1999/xhtml">
761 <xsl:apply-templates select="arg[@direction='in']"
762 mode="parameters-in-docstring"/>
763 </dl>
764 </div>
765 </xsl:if>
766
767 <xsl:if test="arg[@direction='out']">
768 <div xmlns="http://www.w3.org/1999/xhtml">
769 <h4>Returns</h4>
770 <dl xmlns="http://www.w3.org/1999/xhtml">
771 <xsl:apply-templates select="arg[@direction='out']"
772 mode="returns-in-docstring"/>
773 </dl>
774 </div>
775 </xsl:if>
776
777 <xsl:if test="tp:possible-errors">
778 <div xmlns="http://www.w3.org/1999/xhtml">
779 <h4>Possible errors</h4>
780 <dl xmlns="http://www.w3.org/1999/xhtml">
781 <xsl:apply-templates select="tp:possible-errors/tp:error"/>
782 </dl>
783 </div>
784 </xsl:if>
785
786 </div>
787 </xsl:template>
788
789 <xsl:template name="tp-type">
790 <xsl:param name="tp-type"/>
791 <xsl:param name="type"/>
792
793 <xsl:variable name="single-type">
794 <xsl:choose>
795 <xsl:when test="contains($tp-type, '[]')">
796 <xsl:value-of select="substring-before($tp-type, '[]')"/>
797 </xsl:when>
798 <xsl:otherwise>
799 <xsl:value-of select="$tp-type"/>
800 </xsl:otherwise>
801 </xsl:choose>
802 </xsl:variable>
803
804 <xsl:variable name="type-of-single-tp-type">
805 <xsl:choose>
806 <xsl:when test="//tp:simple-type[@name=$single-type]">
807 <xsl:value-of select="string(//tp:simple-type[@name=$single-type]/@type)"/>
808 </xsl:when>
809 <xsl:when test="//tp:struct[@name=$single-type]">
810 <xsl:text>(</xsl:text>
811 <xsl:for-each select="//tp:struct[@name=$single-type]/tp:member">
812 <xsl:value-of select="@type"/>
813 </xsl:for-each>
814 <xsl:text>)</xsl:text>
815 </xsl:when>
816 <xsl:when test="//tp:enum[@name=$single-type]">
817 <xsl:value-of select="string(//tp:enum[@name=$single-type]/@type)"/>
818 </xsl:when>
819 <xsl:when test="//tp:flags[@name=$single-type]">
820 <xsl:value-of select="string(//tp:flags[@name=$single-type]/@type)"/>
821 </xsl:when>
822 <xsl:when test="//tp:mapping[@name=$single-type]">
823 <xsl:text>a{</xsl:text>
824 <xsl:for-each select="//tp:mapping[@name=$single-type]/tp:member">
825 <xsl:value-of select="@type"/>
826 </xsl:for-each>
827 <xsl:text>}</xsl:text>
828 </xsl:when>
829 <xsl:when test="//tp:external-type[@name=$single-type]">
830 <xsl:value-of select="string(//tp:external-type[@name=$single-type]/@type)"/>
831 </xsl:when>
832 <xsl:otherwise>
833 <xsl:message terminate="yes">
834 <xsl:text>ERR: Unable to find type '</xsl:text>
835 <xsl:value-of select="$tp-type"/>
836 <xsl:text>'&#10;</xsl:text>
837 </xsl:message>
838 </xsl:otherwise>
839 </xsl:choose>
840 </xsl:variable>
841
842 <xsl:variable name="type-of-tp-type">
843 <xsl:if test="contains($tp-type, '[]')">
844 <!-- one 'a', plus one for each [ after the [], and delete all ] -->
845 <xsl:value-of select="concat('a',
846 translate(substring-after($tp-type, '[]'), '[]', 'a'))"/>
847 </xsl:if>
848 <xsl:value-of select="$type-of-single-tp-type"/>
849 </xsl:variable>
850
851 <xsl:if test="string($type) != '' and
852 string($type-of-tp-type) != string($type)">
853 <xsl:message terminate="yes">
854 <xsl:text>ERR: tp:type '</xsl:text>
855 <xsl:value-of select="$tp-type"/>
856 <xsl:text>' has D-Bus type '</xsl:text>
857 <xsl:value-of select="$type-of-tp-type"/>
858 <xsl:text>' but has been used with type='</xsl:text>
859 <xsl:value-of select="$type"/>
860 <xsl:text>'&#10;</xsl:text>
861 </xsl:message>
862 </xsl:if>
863
864 <xsl:if test="contains($tp-type, '[]')">
865 <xsl:call-template name="tp-type-array-usage-check">
866 <xsl:with-param name="single-type" select="$single-type"/>
867 <xsl:with-param name="type-of-single-tp-type"
868 select="$type-of-single-tp-type"/>
869 </xsl:call-template>
870 </xsl:if>
871
872 <a href="#type-{$single-type}"><xsl:value-of select="$tp-type"/></a>
873
874 </xsl:template>
875
876 <xsl:template name="tp-type-array-usage-check">
877 <xsl:param name="single-type"/>
878 <xsl:param name="type-of-single-tp-type"/>
879
880 <xsl:variable name="array-name">
881 <xsl:choose>
882 <xsl:when test="//tp:struct[@name=$single-type]">
883 <xsl:value-of select="//tp:struct[@name=$single-type]/@array-name"/>
884 </xsl:when>
885 <xsl:when test="//tp:mapping[@name=$single-type]">
886 <xsl:value-of select="//tp:mapping[@name=$single-type]/@array-name"/>
887 </xsl:when>
888 <xsl:when test="//tp:external-type[@name=$single-type]">
889 <xsl:value-of select="//tp:external-type[@name=$single-type]/@array-name"/>
890 </xsl:when>
891 <xsl:otherwise>
892 <xsl:value-of select="''"/>
893 </xsl:otherwise>
894 </xsl:choose>
895 </xsl:variable>
896
897 <xsl:if test="not(contains('ybnqiuxtdsvog', $type-of-single-tp-type))">
898 <xsl:if test="not($array-name) or $array-name=''">
899 <xsl:message terminate="yes">
900 <xsl:text>No array-name specified for complex type </xsl:text>
901 <xsl:value-of select="$single-type"/>
902 <xsl:text>, but array used&#10;</xsl:text>
903 </xsl:message>
904 </xsl:if>
905 </xsl:if>
906 </xsl:template>
907
908 <xsl:template name="parenthesized-tp-type">
909 <xsl:if test="@tp:type">
910 <xsl:text> (</xsl:text>
911 <xsl:call-template name="tp-type">
912 <xsl:with-param name="tp-type" select="@tp:type"/>
913 <xsl:with-param name="type" select="@type"/>
914 </xsl:call-template>
915 <xsl:text>)</xsl:text>
916 </xsl:if>
917 </xsl:template>
918
919 <xsl:template match="tp:member" mode="members-in-docstring">
920 <dt xmlns="http://www.w3.org/1999/xhtml">
921 <code><xsl:value-of select="@name"/></code> −
922 <code><xsl:value-of select="@type"/></code>
923 <xsl:call-template name="parenthesized-tp-type"/>
924 </dt>
925 <dd xmlns="http://www.w3.org/1999/xhtml">
926 <xsl:choose>
927 <xsl:when test="tp:docstring">
928 <xsl:apply-templates select="tp:docstring" />
929 </xsl:when>
930 <xsl:otherwise>
931 <em>(undocumented)</em>
932 </xsl:otherwise>
933 </xsl:choose>
934 </dd>
935 </xsl:template>
936
937 <xsl:template match="arg" mode="parameters-in-docstring">
938 <dt xmlns="http://www.w3.org/1999/xhtml">
939 <code><xsl:value-of select="@name"/></code> −
940 <code><xsl:value-of select="@type"/></code>
941 <xsl:call-template name="parenthesized-tp-type"/>
942 </dt>
943 <dd xmlns="http://www.w3.org/1999/xhtml">
944 <xsl:apply-templates select="tp:docstring" />
945 </dd>
946 </xsl:template>
947
948 <xsl:template match="arg" mode="returns-in-docstring">
949 <dt xmlns="http://www.w3.org/1999/xhtml">
950 <xsl:if test="@name">
951 <code><xsl:value-of select="@name"/></code> −
952 </xsl:if>
953 <code><xsl:value-of select="@type"/></code>
954 <xsl:call-template name="parenthesized-tp-type"/>
955 </dt>
956 <dd xmlns="http://www.w3.org/1999/xhtml">
957 <xsl:apply-templates select="tp:docstring"/>
958 </dd>
959 </xsl:template>
960
961 <xsl:template match="tp:possible-errors/tp:error">
962 <dt xmlns="http://www.w3.org/1999/xhtml">
963 <code><xsl:value-of select="@name"/></code>
964 </dt>
965 <dd xmlns="http://www.w3.org/1999/xhtml">
966 <xsl:variable name="name" select="@name"/>
967 <xsl:choose>
968 <xsl:when test="tp:docstring">
969 <xsl:apply-templates select="tp:docstring"/>
970 </xsl:when>
971 <xsl:when test="//tp:errors/tp:error[concat(../@namespace, '.', translate(@name, ' ', ''))=$name]/tp:docstring">
972 <xsl:apply-templates select="//tp:errors/tp:error[concat(../@namespace, '.', translate(@name, ' ', ''))=$name]/tp:docstring"/> <em xmlns="http://www.w3.org/1999/xhtml">(generic description)</em>
973 </xsl:when>
974 <xsl:otherwise>
975 (Undocumented.)
976 </xsl:otherwise>
977 </xsl:choose>
978 </dd>
979 </xsl:template>
980
981 <xsl:template match="signal">
982
983 <xsl:call-template name="binding-name-check"/>
984
985 <xsl:if test="not(parent::interface)">
986 <xsl:message terminate="yes">
987 <xsl:text>ERR: signal </xsl:text>
988 <xsl:value-of select="@name"/>
989 <xsl:text> does not have an interface as parent&#10;</xsl:text>
990 </xsl:message>
991 </xsl:if>
992
993 <xsl:if test="not(@name) or @name = ''">
994 <xsl:message terminate="yes">
995 <xsl:text>ERR: missing @name on a signal of </xsl:text>
996 <xsl:value-of select="../@name"/>
997 <xsl:text>&#10;</xsl:text>
998 </xsl:message>
999 </xsl:if>
1000
1001 <xsl:for-each select="arg">
1002 <xsl:if test="not(@type) or @type = ''">
1003 <xsl:message terminate="yes">
1004 <xsl:text>ERR: an arg of signal </xsl:text>
1005 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
1006 <xsl:text> has no type</xsl:text>
1007 </xsl:message>
1008 </xsl:if>
1009 <xsl:if test="not(@name) or @name = ''">
1010 <xsl:message terminate="yes">
1011 <xsl:text>ERR: an arg of signal </xsl:text>
1012 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
1013 <xsl:text> has no name</xsl:text>
1014 </xsl:message>
1015 </xsl:if>
1016 <xsl:choose>
1017 <xsl:when test="not(@direction)"/>
1018 <xsl:when test="@direction='in'">
1019 <xsl:message terminate="no">
1020 <xsl:text>INFO: an arg of signal </xsl:text>
1021 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
1022 <xsl:text> has unnecessary direction 'in'</xsl:text>
1023 </xsl:message>
1024 </xsl:when>
1025 <xsl:otherwise>
1026 <xsl:message terminate="yes">
1027 <xsl:text>ERR: an arg of signal </xsl:text>
1028 <xsl:value-of select="concat(../../@name, '.', ../@name)"/>
1029 <xsl:text> has direction other than 'in'</xsl:text>
1030 </xsl:message>
1031 </xsl:otherwise>
1032 </xsl:choose>
1033 </xsl:for-each>
1034
1035 <div xmlns="http://www.w3.org/1999/xhtml" class="signal">
1036 <h3 xmlns="http://www.w3.org/1999/xhtml">
1037 <a name="{concat(../@name, concat('.', @name))}">
1038 <xsl:value-of select="@name"/>
1039 </a> (
1040 <xsl:for-each xmlns="" select="arg">
1041 <xsl:value-of select="@type"/>: <xsl:value-of select="@name"/>
1042 <xsl:if test="position() != last()">, </xsl:if>
1043 </xsl:for-each>
1044 )</h3>
1045
1046 <div xmlns="http://www.w3.org/1999/xhtml" class="docstring">
1047 <xsl:apply-templates select="tp:docstring"/>
1048 <xsl:apply-templates select="tp:added"/>
1049 <xsl:apply-templates select="tp:changed"/>
1050 <xsl:apply-templates select="tp:deprecated"/>
1051 </div>
1052
1053 <xsl:if test="arg">
1054 <div xmlns="http://www.w3.org/1999/xhtml">
1055 <h4>Parameters</h4>
1056 <dl xmlns="http://www.w3.org/1999/xhtml">
1057 <xsl:apply-templates select="arg" mode="parameters-in-docstring"/>
1058 </dl>
1059 </div>
1060 </xsl:if>
1061 </div>
1062 </xsl:template>
1063
1064 <xsl:output method="xml" indent="no" encoding="ascii"
1065 omit-xml-declaration="yes"
1066 doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
1067 doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" />
1068
1069 <xsl:template match="/tp:spec">
1070 <html xmlns="http://www.w3.org/1999/xhtml">
1071 <head>
1072 <title>
1073 <xsl:value-of select="tp:title"/>
1074 <xsl:if test="tp:version">
1075 <xsl:text> version </xsl:text>
1076 <xsl:value-of select="tp:version"/>
1077 </xsl:if>
1078 </title>
1079 <style type="text/css">
1080
1081 body {
1082 font-family: sans-serif;
1083 margin: 2em;
1084 height: 100%;
1085 font-size: 1.2em;
1086 }
1087 h1 {
1088 padding-top: 5px;
1089 padding-bottom: 5px;
1090 font-size: 1.6em;
1091 background: #dadae2;
1092 }
1093 h2 {
1094 font-size: 1.3em;
1095 }
1096 h3 {
1097 font-size: 1.2em;
1098 }
1099 a:link, a:visited, a:link:hover, a:visited:hover {
1100 font-weight: bold;
1101 }
1102 .topbox {
1103 padding-top: 10px;
1104 padding-left: 10px;
1105 border-bottom: black solid 1px;
1106 padding-bottom: 10px;
1107 background: #dadae2;
1108 font-size: 2em;
1109 font-weight: bold;
1110 color: #5c5c5c;
1111 }
1112 .topnavbox {
1113 padding-left: 10px;
1114 padding-top: 5px;
1115 padding-bottom: 5px;
1116 background: #abacba;
1117 border-bottom: black solid 1px;
1118 font-size: 1.2em;
1119 }
1120 .topnavbox a{
1121 color: black;
1122 font-weight: normal;
1123 }
1124 .sidebar {
1125 float: left;
1126 /* width:9em;
1127 border-right:#abacba solid 1px;
1128 border-left: #abacba solid 1px;
1129 height:100%; */
1130 border: #abacba solid 1px;
1131 padding-left: 10px;
1132 margin-left: 10px;
1133 padding-right: 10px;
1134 margin-right: 10px;
1135 color: #5d5d5d;
1136 background: #dadae2;
1137 }
1138 .sidebar a {
1139 text-decoration: none;
1140 border-bottom: #e29625 dotted 1px;
1141 color: #e29625;
1142 font-weight: normal;
1143 }
1144 .sidebar h1 {
1145 font-size: 1.2em;
1146 color: black;
1147 }
1148 .sidebar ul {
1149 padding-left: 25px;
1150 padding-bottom: 10px;
1151 border-bottom: #abacba solid 1px;
1152 }
1153 .sidebar li {
1154 padding-top: 2px;
1155 padding-bottom: 2px;
1156 }
1157 .sidebar h2 {
1158 font-style:italic;
1159 font-size: 0.81em;
1160 padding-left: 5px;
1161 padding-right: 5px;
1162 font-weight: normal;
1163 }
1164 .date {
1165 font-size: 0.6em;
1166 float: right;
1167 font-style: italic;
1168 }
1169 .method, .signal, .property {
1170 margin-left: 1em;
1171 margin-right: 4em;
1172 }
1173 .rationale {
1174 font-style: italic;
1175 border-left: 0.25em solid #808080;
1176 padding-left: 0.5em;
1177 }
1178
1179 .added {
1180 color: #006600;
1181 background: #ffffff;
1182 }
1183 .deprecated {
1184 color: #ff0000;
1185 background: #ffffff;
1186 }
1187 table, tr, td, th {
1188 border: 1px solid #666;
1189 }
1190
1191 </style>
1192 </head>
1193 <body>
1194 <h1 class="topbox">
1195 <xsl:value-of select="tp:title" />
1196 </h1>
1197 <xsl:if test="tp:version">
1198 <h2>Version <xsl:value-of select="string(tp:version)"/></h2>
1199 </xsl:if>
1200 <xsl:apply-templates select="tp:copyright"/>
1201 <xsl:apply-templates select="tp:license"/>
1202 <xsl:apply-templates select="tp:docstring"/>
1203
1204 <h2>Interfaces</h2>
1205 <ul>
1206 <xsl:for-each select="//node/interface">
1207 <li><code><a href="#{@name}"><xsl:value-of select="@name"/></a></code></li>
1208 </xsl:for-each>
1209 </ul>
1210
1211 <xsl:apply-templates select="//node"/>
1212 <xsl:apply-templates select="tp:generic-types"/>
1213 <xsl:apply-templates select="tp:errors"/>
1214
1215 <h1>Index</h1>
1216 <h2>Index of interfaces</h2>
1217 <ul>
1218 <xsl:for-each select="//node/interface">
1219 <li><code><a href="#{@name}"><xsl:value-of select="@name"/></a></code></li>
1220 </xsl:for-each>
1221 </ul>
1222 <h2>Index of types</h2>
1223 <ul>
1224 <xsl:for-each select="//tp:simple-type | //tp:enum | //tp:flags | //tp:mapping | //tp:struct | //tp:external-type">
1225 <xsl:sort select="@name"/>
1226 <li>
1227 <code>
1228 <a href="#type-{@name}">
1229 <xsl:value-of select="@name"/>
1230 </a>
1231 </code>
1232 <xsl:apply-templates mode="in-index" select="."/>
1233 </li>
1234 </xsl:for-each>
1235 </ul>
1236 </body>
1237 </html>
1238 </xsl:template>
1239
1240 <xsl:template match="node">
1241 <xsl:apply-templates />
1242 </xsl:template>
1243
1244 <xsl:template match="text()">
1245 <xsl:if test="normalize-space(.) != ''">
1246 <xsl:message terminate="yes">
1247 <xsl:text>Stray text: {{{</xsl:text>
1248 <xsl:value-of select="." />
1249 <xsl:text>}}}&#10;</xsl:text>
1250 </xsl:message>
1251 </xsl:if>
1252 </xsl:template>
1253
1254 <xsl:template match="*">
1255 <xsl:message terminate="yes">
1256 <xsl:text>Unrecognised element: {</xsl:text>
1257 <xsl:value-of select="namespace-uri(.)" />
1258 <xsl:text>}</xsl:text>
1259 <xsl:value-of select="local-name(.)" />
1260 <xsl:text>&#10;</xsl:text>
1261 </xsl:message>
1262 </xsl:template>
1263 </xsl:stylesheet>
1264
1265 <!-- vim:set sw=2 sts=2 et: -->
+0
-468
tools/gengobject.py less more
0 #!/usr/bin/python
1
2 import sys
3 import os.path
4 import xml.dom.minidom
5 import dbus
6
7 def cmdline_error():
8 print "usage: gen-gobject xmlfile classname"
9 sys.exit(1)
10
11 def camelcase_to_lower(s):
12 out ="";
13 out += s[0].lower()
14 last_upper=False
15 if s[0].isupper():
16 last_upper=True
17 for i in range(1,len(s)):
18 if s[i].isupper():
19 if last_upper:
20 if (i+1) < len(s) and s[i+1].islower():
21 out += "_" + s[i].lower()
22 else:
23 out += s[i].lower()
24 else:
25 out += "_" + s[i].lower()
26 last_upper=True
27 else:
28 out += s[i]
29 last_upper=False
30 return out
31
32 def camelcase_to_upper(s):
33 return camelcase_to_lower(s).upper()
34
35 def type_to_gtype(s):
36 if s == 'y': #byte
37 return ("guchar ", "G_TYPE_UCHAR","UCHAR", False)
38 elif s == 'b': #boolean
39 return ("gboolean ", "G_TYPE_BOOLEAN","BOOLEAN", False)
40 elif s == 'n': #int16
41 return ("gint ", "G_TYPE_INT","INT", False)
42 elif s == 'q': #uint16
43 return ("guint ", "G_TYPE_UINT","UINT", False)
44 elif s == 'i': #int32
45 return ("gint ", "G_TYPE_INT","INT", False)
46 elif s == 'u': #uint32
47 return ("guint ", "G_TYPE_UINT","UINT", False)
48 elif s == 'x': #int64
49 return ("gint ", "G_TYPE_INT64","INT64", False)
50 elif s == 't': #uint32
51 return ("guint ", "G_TYPE_UINT64","UINT64", False)
52 elif s == 'd': #double
53 return ("gdouble ", "G_TYPE_DOUBLE","DOUBLE", False)
54 elif s == 's': #string
55 return ("gchar *", "G_TYPE_STRING", "STRING", True)
56 elif s == 'g': #signature - FIXME
57 return ("gchar *", "DBUS_TYPE_G_SIGNATURE", "STRING", True)
58 elif s == 'o': #object path
59 return ("gchar *", "DBUS_TYPE_G_OBJECT_PATH", "STRING", True)
60 elif s == 'v': #variant
61 return ("GValue *", "G_TYPE_VALUE", "BOXED", True)
62 elif s == 'as': #array of strings
63 return ("gchar **", "G_TYPE_STRV", "BOXED", True)
64 elif s == 'ay': #byte array
65 return ("GArray *", "DBUS_TYPE_G_BYTE_ARRAY", "BOXED", True)
66 elif s == 'au': #uint array
67 return ("GArray *", "DBUS_TYPE_G_UINT_ARRAY", "BOXED", True)
68 elif s == 'ai': #int array
69 return ("GArray *", "DBUS_TYPE_G_INT_ARRAY", "BOXED", True)
70 elif s == 'ax': #int64 array
71 return ("GArray *", "DBUS_TYPE_G_INT64_ARRAY", "BOXED", True)
72 elif s == 'at': #uint64 array
73 return ("GArray *", "DBUS_TYPE_G_UINT64_ARRAY", "BOXED", True)
74 elif s == 'ad': #double array
75 return ("GArray *", "DBUS_TYPE_G_DOUBLE_ARRAY", "BOXED", True)
76 elif s == 'ab': #boolean array
77 return ("GArray *", "DBUS_TYPE_G_BOOLEAN_ARRAY", "BOXED", True)
78 elif s[:2] == 'a(': #array of structs, recurse
79 gtype = type_to_gtype(s[1:])[1]
80 return ("GPtrArray *", "(dbus_g_type_get_collection (\"GPtrArray\", "+gtype+"))", "BOXED", True)
81 elif s == 'a{ss}': #hash table of string to string
82 return ("GHashTable *", "DBUS_TYPE_G_STRING_STRING_HASHTABLE", "BOXED", False)
83 elif s[:2] == 'a{': #some arbitrary hash tables
84 if s[2] not in ('y', 'b', 'n', 'q', 'i', 'u', 's', 'o', 'g'):
85 raise Exception, "can't index a hashtable off non-basic type " + s
86 first = type_to_gtype(s[2])
87 second = type_to_gtype(s[3:-1])
88 return ("GHashTable *", "(dbus_g_type_get_map (\"GHashTable\", " + first[1] + ", " + second[1] + "))", "BOXED", False)
89 elif s[:1] == '(': #struct
90 gtype = "(dbus_g_type_get_struct (\"GValueArray\", "
91 for subsig in dbus.Signature(s[1:-1]):
92 gtype = gtype + type_to_gtype(subsig)[1] + ", "
93 gtype = gtype + "G_TYPE_INVALID))"
94 return ("GValueArray *", gtype, "BOXED", True)
95
96 # we just don't know ..
97 raise Exception, "don't know the GType for " + s
98
99
100 def signal_to_marshal_type(signal):
101 """
102 return a list of strings indicating the marshalling type for this signal.
103 """
104
105 mtype=[]
106 for i in signal.getElementsByTagName("arg"):
107 name =i.getAttribute("name")
108 type = i.getAttribute("type")
109 mtype.append(type_to_gtype(type)[2])
110
111 return mtype
112
113 def signal_to_marshal_name(signal, prefix):
114 glib_marshallers = set(['VOID', 'BOOLEAN', 'CHAR', 'UCHAR', 'INT',
115 'STRING', 'UINT', 'LONG', 'ULONG', 'ENUM', 'FLAGS', 'FLOAT',
116 'DOUBLE', 'STRING', 'PARAM', 'BOXED', 'POINTER', 'OBJECT',
117 'UINT_POINTER'])
118
119 mtype = signal_to_marshal_type(signal)
120 if len(mtype):
121 name = '_'.join(mtype)
122 else:
123 name = 'VOID'
124
125 if name in glib_marshallers:
126 return 'g_cclosure_marshal_VOID__' + name
127 else:
128 return prefix + '_marshal_VOID__' + name
129
130 def signal_to_gtype_list(signal):
131 gtype=[]
132 for i in signal.getElementsByTagName("arg"):
133 name =i.getAttribute("name")
134 type = i.getAttribute("type")
135 gtype.append(type_to_gtype(type)[1])
136
137 return gtype
138
139
140 def print_license(stream, filename, description):
141 stream.write(
142 """/*
143 * %s - %s
144 * Copyright (C) 2005 Collabora Ltd.
145 * Copyright (C) 2005 Nokia Corporation
146 *
147 * This library is free software; you can redistribute it and/or
148 * modify it under the terms of the GNU Lesser General Public
149 * License as published by the Free Software Foundation; either
150 * version 2.1 of the License, or (at your option) any later version.
151 *
152 * This library is distributed in the hope that it will be useful,
153 * but WITHOUT ANY WARRANTY; without even the implied warranty of
154 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
155 * Lesser General Public License for more details.
156 *
157 * You should have received a copy of the GNU Lesser General Public
158 * License along with this library; if not, write to the Free Software
159 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
160 */
161
162 """ % (filename, description))
163
164 def print_header_begin(stream, prefix):
165 guardname = '__'+prefix.upper()+'_H__'
166 stream.write ("#ifndef "+guardname+"\n")
167 stream.write ("#define "+guardname+"\n\n")
168
169 stream.write ("#include <glib-object.h>\n\n")
170 stream.write ("G_BEGIN_DECLS\n\n")
171
172 def print_header_end(stream, prefix):
173 guardname = '__'+prefix.upper()+'_H__'
174 stream.write ("\nG_END_DECLS\n\n")
175 stream.write ("#endif /* #ifndef "+guardname+"*/\n")
176
177 def print_simple_class_defn(stream, prefix, classname):
178 stream.write ("typedef struct _%s %s;\n" % (classname,classname))
179 stream.write ("typedef struct _%sClass %sClass;\n\n" % (classname,classname))
180 stream.write ("struct _%sClass {\n" % classname)
181 stream.write (" GObjectClass parent_class;\n")
182 stream.write ("};\n\n")
183
184 stream.write ("struct _%s {\n" % classname)
185 stream.write (" GObject parent;\n\n")
186 stream.write (" gpointer priv;\n")
187 stream.write ("};\n")
188
189 stream.write(
190 """
191 GType %(prefix)s_get_type(void);
192
193 """ % {'prefix':prefix,'uprefix':prefix.upper()})
194
195 macro_prefix = prefix.upper().split('_',1)
196 gtype = '_TYPE_'.join(macro_prefix)
197
198 stream.write(
199 """/* TYPE MACROS */
200 #define %(type)s \\
201 (%(prefix)s_get_type())
202 #define %(main)s_%(sub)s(obj) \\
203 (G_TYPE_CHECK_INSTANCE_CAST((obj), %(type)s, %(name)s))
204 #define %(main)s_%(sub)s_CLASS(klass) \\
205 (G_TYPE_CHECK_CLASS_CAST((klass), %(type)s, %(name)sClass))
206 #define %(main)s_IS_%(sub)s(obj) \\
207 (G_TYPE_CHECK_INSTANCE_TYPE((obj), %(type)s))
208 #define %(main)s_IS_%(sub)s_CLASS(klass) \\
209 (G_TYPE_CHECK_CLASS_TYPE((klass), %(type)s))
210 #define %(main)s_%(sub)s_GET_CLASS(obj) \\
211 (G_TYPE_INSTANCE_GET_CLASS ((obj), %(type)s, %(name)sClass))
212
213 """ % {"main":macro_prefix[0], "sub":macro_prefix[1], "type":gtype, "name":classname, "prefix":prefix})
214
215 if __name__ == '__main__':
216 try:
217 classname = sys.argv[2]
218 except IndexError:
219 cmdline_error()
220
221 prefix = camelcase_to_lower(classname)
222 if len(sys.argv) > 3:
223 basename = sys.argv[3]
224 else:
225 basename = prefix.replace('_','-')
226
227 outname_header = basename + ".h"
228 outname_body = basename + ".c"
229 outname_signal_marshal = basename + "-signals-marshal.list"
230
231 header=open(outname_header,'w')
232 body=open(outname_body, 'w')
233 signal_marshal=open(outname_signal_marshal, 'w')
234
235 try:
236 dom = xml.dom.minidom.parse(sys.argv[1])
237 except IndexError:
238 cmdline_error()
239
240 signals = dom.getElementsByTagName("signal")
241 signals.sort(key=lambda n: n.getAttributeNode("name").nodeValue)
242 methods = dom.getElementsByTagName("method")
243 methods.sort(key=lambda n: n.getAttributeNode("name").nodeValue)
244
245 print_license(header, outname_header, "Header for " + classname)
246 print_license(body, outname_body, "Source for " + classname)
247 print_header_begin(header,prefix)
248
249 print_simple_class_defn(header, prefix, classname)
250
251 body.write(
252 """#include <dbus/dbus-glib.h>
253 #include <stdio.h>
254 #include <stdlib.h>
255
256 #include "%s"
257 #include "%s-signals-marshal.h"
258
259 #include "%s-glue.h"
260
261 """ % (outname_header, basename, basename))
262
263 body.write(
264 """G_DEFINE_TYPE(%(classname)s, %(prefix)s, G_TYPE_OBJECT)
265
266 """ % {'classname':classname, 'prefix':prefix})
267
268 body.write("/* signal enum */\nenum\n{\n")
269 for signal in signals:
270 dbus_name = signal.getAttributeNode("name").nodeValue
271 body.write(" %s,\n" % camelcase_to_upper(dbus_name) )
272 body.write(" LAST_SIGNAL\n};\n\n")
273 body.write("static guint signals[LAST_SIGNAL] = {0};\n\n")
274
275 gtypename = '_TYPE_'.join(prefix.upper().split('_',1))
276
277 body.write("""/* private structure */
278 typedef struct _%(classname)sPrivate %(classname)sPrivate;
279
280 struct _%(classname)sPrivate
281 {
282 gboolean dispose_has_run;
283 };
284
285 #define %(uprefix)s_GET_PRIVATE(obj) \\
286 ((%(classname)sPrivate *)obj->priv)
287 """ % {'classname':classname, 'uprefix':prefix.upper(), 'gtypename':gtypename})
288
289 body.write(
290 """
291 static void
292 %(prefix)s_init (%(classname)s *self)
293 {
294 %(classname)sPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (self,
295 %(gtypename)s, %(classname)sPrivate);
296
297 self->priv = priv;
298
299 /* allocate any data required by the object here */
300 }
301
302 static void %(prefix)s_dispose (GObject *object);
303 static void %(prefix)s_finalize (GObject *object);
304
305 static void
306 %(prefix)s_class_init (%(classname)sClass *%(prefix)s_class)
307 {
308 GObjectClass *object_class = G_OBJECT_CLASS (%(prefix)s_class);
309
310 g_type_class_add_private (%(prefix)s_class, sizeof (%(classname)sPrivate));
311
312 object_class->dispose = %(prefix)s_dispose;
313 object_class->finalize = %(prefix)s_finalize;
314 """ % {'classname':classname, 'gtypename':gtypename, 'prefix':prefix, 'uprefix':prefix.upper()})
315
316 header.write("\n")
317
318 marshallers = set()
319 for signal in signals:
320 dbus_name = signal.getAttributeNode("name").nodeValue
321 gtypelist = signal_to_gtype_list(signal)
322 marshal_name = signal_to_marshal_name(signal, prefix)
323
324 body.write(
325 """
326 signals[%s] =
327 g_signal_new ("%s",
328 G_OBJECT_CLASS_TYPE (%s_class),
329 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
330 0,
331 NULL, NULL,
332 %s,
333 G_TYPE_NONE, %s);
334 """ % (camelcase_to_upper(dbus_name),
335 camelcase_to_lower(dbus_name).replace('_','-'),
336 prefix, marshal_name,
337 ', '.join([str(len(gtypelist))] + gtypelist)))
338
339 if not marshal_name.startswith('g_cclosure_marshal_VOID__'):
340 mtype = signal_to_marshal_type(signal)
341 assert(len(mtype))
342 marshallers.add(','.join(mtype))
343
344 for marshaller in marshallers:
345 signal_marshal.write("VOID:"+marshaller+"\n")
346
347 body.write(
348 """
349 dbus_g_object_type_install_info (G_TYPE_FROM_CLASS (%(prefix)s_class), &dbus_glib_%(prefix)s_object_info);
350 }
351
352 void
353 %(prefix)s_dispose (GObject *object)
354 {
355 %(classname)s *self = %(uprefix)s (object);
356 %(classname)sPrivate *priv = %(uprefix)s_GET_PRIVATE (self);
357
358 if (priv->dispose_has_run)
359 return;
360
361 priv->dispose_has_run = TRUE;
362
363 /* release any references held by the object here */
364
365 if (G_OBJECT_CLASS (%(prefix)s_parent_class)->dispose)
366 G_OBJECT_CLASS (%(prefix)s_parent_class)->dispose (object);
367 }
368
369 void
370 %(prefix)s_finalize (GObject *object)
371 {
372 %(classname)s *self = %(uprefix)s (object);
373 %(classname)sPrivate *priv = %(uprefix)s_GET_PRIVATE (self);
374
375 /* free any data held directly by the object here */
376
377 G_OBJECT_CLASS (%(prefix)s_parent_class)->finalize (object);
378 }
379
380
381 """ % {'classname':classname,'prefix':prefix, 'uprefix':prefix.upper()})
382
383 for method in methods:
384 dbus_method_name = method.getAttributeNode("name").nodeValue
385 c_method_name = prefix + '_' + camelcase_to_lower(dbus_method_name)
386 async=False
387 ret_count=0
388
389 for i in method.getElementsByTagName("annotation"):
390 if i.getAttribute("name") == "org.freedesktop.DBus.GLib.Async":
391 async=True
392
393 if async:
394 c_decl = "void\n"
395 else:
396 c_decl = "gboolean\n"
397
398 tmp = c_method_name+' ('
399 pad = ' ' * len(tmp)
400 c_decl += tmp+classname+' *self'
401
402 for i in method.getElementsByTagName("arg"):
403 name =i.getAttribute("name")
404 direction = i.getAttribute("direction")
405 type = i.getAttribute("type")
406
407 if async and direction=="out":
408 continue
409
410 if not name and direction == "out":
411 if ret_count==0:
412 name = "ret"
413 else:
414 name = "ret"+str(ret_count)
415 ret_count += 1
416
417 gtype = type_to_gtype(type)[0]
418 if direction =="out":
419 gtype+='*'
420 else:
421 if type_to_gtype(type)[3]:
422 gtype="const "+gtype
423 c_decl +=",\n"+pad+gtype+name
424
425 if async:
426 c_decl += ",\n"+pad+"DBusGMethodInvocation *context)"
427 else:
428 c_decl += ",\n"+pad+"GError **error)"
429
430 interface = method.parentNode.getAttribute("name");
431 header.write(c_decl+";\n\n")
432 body.write(
433 """
434 /**
435 * %(c_method_name)s
436 *
437 * Implements D-Bus method %(method)s
438 * on interface %(interface)s
439 *""" % {'c_method_name':c_method_name, 'method':dbus_method_name, 'interface':interface})
440 if async:
441 body.write(
442 """
443 * @context: The D-Bus invocation context to use to return values
444 * or throw an error.
445 */
446 """)
447 else:
448 body.write(
449 """
450 * @error: Used to return a pointer to a GError detailing any error
451 * that occurred, D-Bus will throw the error only if this
452 * function returns FALSE.
453 *
454 * Returns: TRUE if successful, FALSE if an error was thrown.
455 */
456 """)
457
458 if async:
459 body.write(c_decl+"\n{\n return;\n}\n\n")
460 else:
461 body.write(c_decl+"\n{\n return TRUE;\n}\n\n")
462
463 header.write('\n')
464
465 print_header_end(header,prefix)
466 header.close()
467 body.close()
+0
-35
tools/ls-interfaces.xsl less more
0 <!--
1 Extract a space-separated list of interface classnames from the Telepathy spec.
2 The master copy of this stylesheet is in the Telepathy spec repository -
3 please make any changes there.
4
5 Copyright (C) 2006, 2007 Collabora Limited
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 -->
21
22 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
23
24 <xsl:output method="text" indent="no" encoding="ascii"/>
25
26 <xsl:template match="text()"/>
27
28 <xsl:template match="node">
29 <xsl:value-of select="concat(' ', translate(@name, '/', ''), ' ')"/>
30 </xsl:template>
31
32 </xsl:stylesheet>
33
34 <!-- vim:set sw=2 sts=2 et noai noci: -->
+0
-56
tools/make_all_async.py less more
0 #!/usr/bin/python2.4
1
2 import sys
3
4 try:
5 try:
6 # it's in this package in python2.5
7 from xml.etree.ElementTree import fromstring, tostring, ElementTree, Element
8 except ImportError:
9 from elementtree.ElementTree import fromstring, tostring, ElementTree, Element
10 except ImportError:
11 print "You need to install ElementTree (http://effbot.org/zone/element-index.htm)"
12 sys.exit(1)
13
14 from xml.dom.minidom import parseString
15
16 import sys
17
18 def strip (element):
19 if element.text:
20 element.text = element.text.strip()
21 if element.tail:
22 element.tail = element.tail.strip()
23 for child in element:
24 strip (child)
25
26 def annotate(root):
27 assert root.tag == 'node'
28
29 for interface_elt in root:
30 if interface_elt.tag != 'interface':
31 continue
32 for method_elt in interface_elt:
33 if method_elt.tag != 'method':
34 continue
35 a_elt = Element('annotation',
36 name='org.freedesktop.DBus.GLib.Async',
37 value='')
38 method_elt.insert(0, a_elt)
39 #a_elt = Element('annotation',
40 # name='org.freedesktop.DBus.GLib.Const',
41 # value='')
42 #method_elt.insert(0, a_elt)
43
44 if __name__ == '__main__':
45 root = ElementTree(file=sys.argv[1]).getroot()
46 annotate(root)
47
48 # pretty print
49 strip(root)
50 xml = tostring(root)
51 dom = parseString(xml)
52
53 output = file(sys.argv[2], 'w')
54 output.write(dom.toprettyxml(' ', '\n'))
55 output.close()
+69
-15
tools/specparser.py less more
3636 class UnsupportedArray(Exception): pass
3737 class BadNameForBindings(Exception): pass
3838 class BrokenHTML(Exception): pass
39 class TooManyChildren(Exception): pass
39 class WrongNumberOfChildren(Exception): pass
4040 class MismatchedFlagsAndEnum(Exception): pass
41 class TypeMismatch(Exception): pass
42 class MissingVersion(Exception): pass
4143
4244 def getText(dom):
4345 try:
6163 return None
6264
6365 if len(kids) > 1:
64 raise TooManyChildren('%s node should have at most one child of type '
66 raise WrongNumberOfChildren('%s node should have at most one child of type '
6567 '{%s}%s' % (dom.tagName, namespace, name))
6668
6769 return kids[0]
130132 raise UnnamedItem("Node %s of %s has no name" % (
131133 self.__class__.__name__, self.parent))
132134
135 def check_consistency(self):
136 pass
137
133138 def get_type_name(self):
134139 return self.__class__.__name__
135140
163168 nnode.getAttribute('version')).firstChild
164169 node.insertBefore(span, node.firstChild)
165170 except xml.dom.NotFoundErr:
166 print >> sys.stderr, \
167 'WARNING: %s was %s, but gives no version' % (self, htmlclass)
171 raise MissingVersion(
172 '%s was %s, but gives no version' % (self, htmlclass))
168173
169174 self._convert_to_html(node)
170175
316321 arg.direction == Arg.DIRECTION_OUT:
317322 continue
318323
319 print >> sys.stderr, "WARNING: '%s' of method '%s' does not specify a suitable direction" % (arg, self)
324 raise UnknownDirection("'%s' of method '%s' does not specify a suitable direction" % (arg, self))
320325
321326 self.possible_errors = build_list(self, PossibleError, None,
322327 dom.getElementsByTagNameNS(XMLNS_TP, 'error'))
330335 else:
331336 return 'nothing'
332337
338 def check_consistency(self):
339 for x in self.in_args:
340 x.check_consistency()
341
342 for x in self.out_args:
343 x.check_consistency()
344
333345 class Typed(Base):
334346 """The base class for all typed nodes (i.e. Arg and Property).
335347
345357 # check we have a dbus type
346358 if self.dbus_type == '':
347359 raise UntypedItem("Node referred to by '%s' has no type" % dom.toxml())
360
348361 def get_type(self):
349362 return self.get_spec().lookup_type(self.type)
350363
357370 t = self.get_type()
358371 if t is None: return ''
359372 else: return t.get_title()
373
374 def check_consistency(self):
375 t = self.get_type()
376 if t is None:
377 if self.dbus_type not in (
378 # Basic types
379 'y', 'b', 'n', 'q', 'i', 'u', 'x', 't', 'd', 's', 'v', 'o',
380 'g',
381 # QtDBus generic support
382 'as', 'ay', 'av', 'a{sv}',
383 # telepathy-qt4 generic support
384 'ab', 'an', 'aq', 'ai', 'au', 'ax', 'at', 'ad', 'ao', 'ag',
385 ):
386 raise TypeMismatch('%r type %s needs to be a named tp:type '
387 'for QtDBus interoperability'
388 % (self, self.dbus_type))
389 else:
390 if self.dbus_type != t.dbus_type:
391 raise TypeMismatch('%r type %s isn\'t tp:type %s\'s type %s'
392 % (self, self.dbus_type, t, t.dbus_type))
360393
361394 def spec_name(self):
362395 return '%s: %s' % (self.dbus_type, self.short_name)
423456 if arg.direction == Arg.DIRECTION_UNSPECIFIED:
424457 continue
425458
426 print >> sys.stderr, "WARNING: '%s' of signal '%s' does not specify a suitable direction" % (arg, self)
459 raise UnknownDirection("'%s' of signal '%s' does not specify a suitable direction" % (arg, self))
427460
428461 def get_args(self):
429462 return ', '.join(map(lambda a: a.spec_name(), self.args))
573606 self.dbus_type = dom.getAttribute('type')
574607 self.array_name = dom.getAttribute('array-name')
575608 self.array_depth = dom.getAttribute('array-depth')
609 self.name = self.short_name
576610
577611 def get_root_namespace(self):
578612 return self.namespace
640674 def __init__(self, parent, namespace, dom):
641675 super(Mapping, self).__init__(parent, namespace, dom)
642676
677 if len(self.members) != 2:
678 raise WrongNumberOfChildren('%s node should have exactly two tp:members'
679 % dom.tagName)
680
643681 # rewrite the D-Bus type
644682 self.dbus_type = 'a{%s}' % ''.join(map(lambda m: m.dbus_type, self.members))
645683
649687
650688 def __init__(self, parent, namespace, dom):
651689 super(Struct, self).__init__(parent, namespace, dom)
690
691 if len(self.members) == 0:
692 raise WrongNumberOfChildren('%s node should have a tp:member'
693 % dom.tagName)
652694
653695 # rewrite the D-Bus type
654696 self.dbus_type = '(%s)' % ''.join(map(lambda m: m.dbus_type, self.members))
784826 def get_root_namespace(self):
785827 return None
786828
829 class ErrorsSection(Section):
830 def validate(self):
831 pass
832
787833 class Spec(SectionBase):
788834 def __init__(self, dom, spec_namespace):
789835 # build a dictionary of errors in this spec
792838 self.errors = build_dict(self, Error,
793839 errorsnode.getAttribute('namespace'),
794840 errorsnode.getElementsByTagNameNS(XMLNS_TP, 'error'))
841 self.errors_section = ErrorsSection(self, None, errorsnode,
842 spec_namespace)
795843 except IndexError:
796844 self.errors = {}
845 self.errors_section = None
846
847 self.sorted_errors = sorted(self.errors.values(),
848 key=lambda e: e.name)
797849
798850 # build a list of generic types
799851 self.generic_types = reduce (lambda a, b: a + b,
817869 self.everything = {}
818870 self.types = {}
819871
820 for type in self.generic_types: self.types[type.short_name] = type
872 for type in self.generic_types:
873 self.types[type.name] = type
821874
822875 for interface in self.interfaces:
823876 self.everything[interface.name] = interface
836889 self.everything[token.name] = token
837890
838891 for type in interface.types:
839 self.types[type.short_name] = type
892 self.types[type.name] = type
840893
841894 # get some extra bits for the HTML
842895 node = dom.getElementsByTagNameNS(XMLNS_TP, 'spec')[0]
852905
853906 try:
854907 license = getChildrenByName(node, XMLNS_TP, 'license')[0]
855 license.tagName = 'div'
856 license.namespaceURI = None
857 license.setAttribute('class', 'license')
858 self.license = license.toxml()
908 self.license = map(getText, license.getElementsByTagName('p'))
859909 except IndexError:
860 self.license = ''
861
862 # FIXME: we need to check all args for type correctness
910 self.license = []
911
912 self.check_consistency()
913
914 def check_consistency(self):
915 for x in self.everything.values():
916 x.check_consistency()
863917
864918 def get_spec(self):
865919 return self