Imported Upstream version 0.17.4
Simon McVittie
15 years ago
0 | Fri May 9 11:26:40 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
1 | tagged telepathy-spec 0.17.4 | |
2 | ||
3 | Fri May 9 11:26:29 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
4 | * Release 0.17.4 | |
5 | ||
6 | Thu May 8 09:56:56 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
7 | * Adjust NEWS | |
8 | ||
9 | Thu May 8 09:50:04 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
10 | * Mark Hold as stable | |
11 | ||
12 | Thu May 8 09:31:04 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
13 | * Update NEWS in preparation for a 0.17.4 release | |
14 | ||
15 | Tue May 6 11:14:57 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
16 | * Simplify generation of links to arrays of types | |
17 | ||
18 | Wed Apr 16 16:22:43 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
19 | * Expand on the description of NormalizedName | |
20 | ||
21 | Wed Apr 16 16:17:45 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
22 | * Re-indent the Enabled property, fix a typo, and explicitly allow it to be set on invalid accounts (although it has no effect until the account becomes valid) | |
23 | ||
24 | Tue Apr 1 14:57:01 BST 2008 Alberto Mardegan <mardy@users.sourceforge.net> | |
25 | * fix_enable_capitalization | |
26 | ||
27 | Thu Mar 20 07:34:23 GMT 2008 Alberto Mardegan <mardy@users.sourceforge.net> | |
28 | * prop_enabled | |
29 | ||
30 | Thu Mar 20 07:11:40 GMT 2008 Alberto Mardegan <mardy@users.sourceforge.net> | |
31 | * normalizedname | |
32 | ||
33 | Fri Apr 18 12:01:49 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
34 | * Channel_Interface_DTMF: annotate stream IDs as Stream_ID | |
35 | ||
36 | Wed Mar 5 14:25:05 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
37 | * Channel_Interface_DTMF: introduce whitespace for clarity | |
38 | ||
39 | Mon Apr 7 16:45:06 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
40 | * Improve Hold spec to cover no-op cases better | |
41 | ||
42 | Fri Apr 4 14:36:52 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
43 | * Make Hold interface more elaborate - instead of a boolean for "held?", provide four states (unheld, held, trying to hold, trying to unhold) and a reason-code enum | |
44 | ||
45 | Fri Apr 4 14:25:01 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
46 | * MediaStreamHandler: explain how Hold-related API should interact with notifications to the remote contact | |
47 | ||
48 | Thu Apr 3 19:36:01 BST 2008 Dafydd Harries <dafydd.harries@collabora.co.uk> | |
49 | * add XHTML namespace to ListPendingMessages docstring element | |
50 | ||
51 | Thu Apr 3 17:02:51 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
52 | * Nano version 0.17.3.1 | |
53 | ||
0 | 54 | Thu Apr 3 17:02:27 BST 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
1 | 55 | tagged telepathy-spec 0.17.3 |
2 | 56 | |
54 | 108 | Tue Mar 18 14:56:23 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
55 | 109 | * Remove never-implemented legacy interfaces from all.xml so they don't end up in the spec HTML |
56 | 110 | |
111 | Tue Mar 18 13:37:49 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
112 | * Move Handle, Contact_Handle, etc. from generic-types to Connection (since that's their scope) | |
113 | ||
114 | Tue Mar 18 13:36:16 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
115 | * ConnectionManager: annotate bus name returned from RequestChannel as a DBus_Bus_Name | |
116 | ||
117 | Tue Mar 18 13:35:52 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
118 | * ConnectionManager: remove remnant of inline list of protocols in ListProtocols (it's now documented under Protocol) | |
119 | ||
120 | Tue Mar 18 13:35:26 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
121 | * ConnectionManager: add some whitespace | |
122 | ||
57 | 123 | Tue Mar 18 16:06:28 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
58 | 124 | * Update NEWS with merged changes so far in 0.17.3 |
59 | ||
60 | Tue Mar 18 13:37:49 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
61 | * Move Handle, Contact_Handle, etc. from generic-types to Connection (since that's their scope) | |
62 | ||
63 | Tue Mar 18 13:36:16 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
64 | * ConnectionManager: annotate bus name returned from RequestChannel as a DBus_Bus_Name | |
65 | ||
66 | Tue Mar 18 13:35:52 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
67 | * ConnectionManager: remove remnant of inline list of protocols in ListProtocols (it's now documented under Protocol) | |
68 | ||
69 | Tue Mar 18 13:35:26 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
70 | * ConnectionManager: add some whitespace | |
71 | 125 | |
72 | 126 | Tue Mar 18 13:52:50 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
73 | 127 | * Clarify interaction between ListPendingMessages(clear=true) and AcknowledgePendingMessages |
134 | 188 | Thu Mar 6 14:39:59 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
135 | 189 | * Prepare spec release 0.17.2 |
136 | 190 | |
191 | Wed Mar 5 17:47:27 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
192 | * doc-generator.xsl: generate docs for all interfaces at any level of nesting | |
193 | ||
194 | Wed Feb 27 16:01:42 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
195 | * Add Channel_Call_State_Queued | |
196 | ||
197 | Thu Mar 6 12:08:04 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
198 | * Update NEWS for planned release | |
199 | ||
137 | 200 | Thu Mar 6 13:00:59 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
138 | 201 | * Fix conflict: whitespace vs addition of Media_Session_Type, Media_Session_Handler_Info |
139 | 202 | |
157 | 220 | |
158 | 221 | Thu Mar 6 12:55:37 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
159 | 222 | * Channel_Type_Streamed_Media: we like the whitespace |
160 | ||
161 | Wed Mar 5 17:47:27 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
162 | * doc-generator.xsl: generate docs for all interfaces at any level of nesting | |
163 | ||
164 | Wed Feb 27 16:01:42 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
165 | * Add Channel_Call_State_Queued | |
166 | ||
167 | Thu Mar 6 12:08:04 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
168 | * Update NEWS for planned release | |
169 | 223 | |
170 | 224 | Thu Feb 28 11:43:32 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
171 | 225 | * Connection_Interface_Privacy: set xmlns so HTML renders properly |
309 | 363 | Tue Feb 19 10:27:22 GMT 2008 Sjoerd Simons <sjoerd@luon.net> |
310 | 364 | * If you can't get the tokens without retrieving the avatar, then a correct implementation is to return a random token. So remove this case from the GetKnownAvatars exception |
311 | 365 | |
312 | Tue Feb 19 10:02:46 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
313 | * Explicitly say that service names for TCP tubes should be either an IANA service name from assignments/port-numbers or a dns-sd.org service type, rather than only referencing dns-sd.org (which itself references the IANA list) | |
314 | ||
315 | 366 | Tue Feb 12 10:04:20 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
316 | 367 | * Copyright 2008 |
317 | 368 | |
352 | 403 | * Makefile: assume that all XML files starting with a capital letter are interfaces, and all starting with lower-case are misc. |
353 | 404 | Based on a mail from Will Stephenson. |
354 | 405 | |
406 | Tue Jan 29 14:51:59 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
407 | * Don't allow RequestHold to raise InvalidHandle (it doesn't take a handle argument any more). Clarify what NotAvailable means for it. | |
408 | ||
409 | Tue Feb 19 10:02:46 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
410 | * Explicitly say that service names for TCP tubes should be either an IANA service name from assignments/port-numbers or a dns-sd.org service type, rather than only referencing dns-sd.org (which itself references the IANA list) | |
411 | ||
355 | 412 | Wed Feb 6 16:41:38 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
356 | 413 | * Remove extensibility mechanism - we don't really need it and it causes confusing warnings |
357 | 414 | |
358 | 415 | Wed Feb 6 16:39:30 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
359 | 416 | * Fix mismatched tag |
360 | ||
361 | Tue Jan 29 14:51:59 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> | |
362 | * Don't allow RequestHold to raise InvalidHandle (it doesn't take a handle argument any more). Clarify what NotAvailable means for it. | |
363 | 417 | |
364 | 418 | Thu Jan 24 12:46:44 GMT 2008 Simon McVittie <simon.mcvittie@collabora.co.uk> |
365 | 419 | * Relax mention of special handling of CM params containing "password" from a "should" to a backwards compatibility note |
0 | 0 | This file contains the same edited highlights as the announcement emails. |
1 | 1 | For full details, see the ChangeLog in tarballs, or "darcs changes" in Darcs |
2 | 2 | checkouts. |
3 | ||
4 | telepathy-spec 0.17.4 (2008-05-09) | |
5 | ================================== | |
6 | ||
7 | API changes: | |
8 | ||
9 | * Improve the Hold interface: instead of a boolean "held?" we now have | |
10 | a quad-state arrangement (unheld, held, trying to hold, trying to unhold) | |
11 | which turns out to be more useful for clients. This API has already been | |
12 | implemented as an extension in telepathy-gabble 0.7.3 and in | |
13 | telepathy-sofiasip 0.5.8. | |
14 | ||
15 | API additions: | |
16 | ||
17 | * Add the Enabled and NormalizedName properties to the Account interface | |
18 | ||
19 | * The Hold interface is now marked as stable, please include it in bindings | |
20 | ||
21 | Fixes: | |
22 | ||
23 | * Explain the intended interaction between the Hold API presented to | |
24 | streaming clients (MediaStreamHandler), and signalling to the remote contact | |
25 | ||
26 | * ListPendingMessages documentation shows up correctly in the HTML spec | |
27 | ||
28 | Tools changes: | |
29 | ||
30 | * Some simplifications in doc-generator.xsl | |
3 | 31 | |
4 | 32 | telepathy-spec 0.17.3 (2008-04-03) |
5 | 33 | ================================== |
191 | 191 | </tp:docstring> |
192 | 192 | </property> |
193 | 193 | |
194 | <property name="Enabled" type="b" access="readwrite"> | |
195 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> | |
196 | <p>This property gives the users the possibility to prevent an account | |
197 | from being used. This flag does not change the validity of the | |
198 | account.</p> | |
199 | ||
200 | <p>A disabled account can never be put online.</p> | |
201 | ||
202 | <tp:rationale> | |
203 | <p>Use cases:</p> | |
204 | ||
205 | <ul> | |
206 | <li>user has two or more accounts capable of calling contact X, but | |
207 | he doesn't want the UI to prompt him everytime about which one he | |
208 | wants to use for the call. He can then disable all the equivalent | |
209 | accounts but one.</li> | |
210 | ||
211 | <li>There is some temporary server error and the user doesn't want | |
212 | to be be bother by error messages, or change the account | |
213 | configuration: temporarily disabling the account is quicker.</li> | |
214 | </ul> | |
215 | ||
216 | <p>The AccountManager SHOULD allow this property to be set on invalid | |
217 | accounts, but MUST NOT attempt to put invalid accounts online | |
218 | even if they become Enabled.</p> | |
219 | ||
220 | <tp:rationale> | |
221 | <p>There doesn't seem to be any good reason not to allow this.</p> | |
222 | </tp:rationale> | |
223 | </tp:rationale> | |
224 | </tp:docstring> | |
225 | </property> | |
226 | ||
194 | 227 | <property name="Nickname" type="as" access="readwrite"> |
195 | 228 | <tp:docstring> |
196 | 229 | The nickname to set on this account for display to other contacts, |
417 | 450 | </tp:docstring> |
418 | 451 | </property> |
419 | 452 | |
453 | <property name="NormalizedName" type="s" access="read"> | |
454 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> | |
455 | <p>The normalized user ID of the local user on this account (i.e. the | |
456 | string returned when the InspectHandle method is called on the | |
457 | result of GetSelfHandle() for an active connection).</p> | |
458 | ||
459 | <p>It is unspecified whether this user ID is globally unique.</p> | |
460 | ||
461 | <tp:rationale> | |
462 | <p>As currently implemented, IRC user IDs are only unique within | |
463 | the same IRCnet. On some saner protocols, the user ID includes a | |
464 | DNS name which provides global uniqueness.</p> | |
465 | </tp:rationale> | |
466 | ||
467 | <p>If this value is not known yet (which will always be the case for | |
468 | accounts that have never been online), it will be an empty | |
469 | string.</p> | |
470 | ||
471 | <p>It is possible that this value will change if the connection | |
472 | manager's normalization algorithm changes, although this SHOULD | |
473 | be avoided.</p> | |
474 | ||
475 | <tp:rationale> | |
476 | <p>It's not always completely clear what normalization algorithm | |
477 | should be used; for instance, in Gabble, we currently use JIDs, | |
478 | but it would also have been reasonable to use xmpp URIs.</p> | |
479 | </tp:rationale> | |
480 | </tp:docstring> | |
481 | </property> | |
482 | ||
420 | 483 | </interface> |
421 | 484 | </node> |
422 | 485 | <!-- vim:set sw=2 sts=2 et ft=xml: --> |
19 | 19 | </tp:license> |
20 | 20 | <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF"> |
21 | 21 | <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> |
22 | ||
22 | 23 | <method name="StartTone"> |
23 | <arg direction="in" name="stream_id" type="u"> | |
24 | <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID"> | |
24 | 25 | <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> |
25 | 26 | </arg> |
26 | 27 | <arg direction="in" name="event" type="y" tp:type="DTMF_Event"> |
47 | 48 | </tp:error> |
48 | 49 | </tp:possible-errors> |
49 | 50 | </method> |
51 | ||
50 | 52 | <method name="StopTone"> |
51 | <arg direction="in" name="stream_id" type="u"> | |
53 | <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID"> | |
52 | 54 | <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> |
53 | 55 | </arg> |
54 | 56 | <tp:docstring> |
69 | 71 | </tp:error> |
70 | 72 | </tp:possible-errors> |
71 | 73 | </method> |
74 | ||
72 | 75 | <tp:enum name="DTMF_Event" type="y"> |
73 | 76 | <tp:enumvalue suffix="Digit_0" value="0"> |
74 | 77 | <tp:docstring>0</tp:docstring> |
119 | 122 | <tp:docstring>D</tp:docstring> |
120 | 123 | </tp:enumvalue> |
121 | 124 | </tp:enum> |
125 | ||
122 | 126 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> |
123 | 127 | An interface that gives a Channel the ability to send DTMF events over |
124 | 128 | audio streams which have been established using the StreamedMedia channel |
126 | 130 | href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are |
127 | 131 | listed in the DTMF_Event enumeration. |
128 | 132 | </tp:docstring> |
133 | ||
129 | 134 | </interface> |
130 | 135 | </node> |
131 | 136 | <!-- vim:set sw=2 sts=2 et ft=xml: --> |
18 | 18 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
19 | 19 | </tp:license> |
20 | 20 | |
21 | <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold" | |
22 | tp:causes-havoc='not yet API-stable'> | |
21 | <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"> | |
23 | 22 | <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> |
24 | 23 | |
25 | 24 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> |
37 | 36 | </tp:docstring> |
38 | 37 | |
39 | 38 | <method name="GetHoldState"> |
40 | <arg name="Held" direction="out" type="b"> | |
41 | <tp:docstring> | |
42 | True if the local user has placed the channel on hold. | |
43 | </tp:docstring> | |
44 | </arg> | |
45 | 39 | <tp:docstring> |
46 | 40 | Return whether the local user has placed the channel on hold. |
47 | 41 | </tp:docstring> |
42 | ||
43 | <arg name="HoldState" direction="out" type="u" | |
44 | tp:type="Local_Hold_State"> | |
45 | <tp:docstring> | |
46 | The state of the channel | |
47 | </tp:docstring> | |
48 | </arg> | |
49 | ||
50 | <arg name="Reason" direction="out" type="u" | |
51 | tp:type="Local_Hold_State_Reason"> | |
52 | <tp:docstring> | |
53 | The reason why the channel is in that state | |
54 | </tp:docstring> | |
55 | </arg> | |
48 | 56 | </method> |
49 | 57 | |
50 | 58 | <signal name="HoldStateChanged"> |
51 | <arg name="Held" type="b"> | |
52 | <tp:docstring> | |
53 | True if the local user has placed the channel on hold. | |
54 | </tp:docstring> | |
55 | </arg> | |
56 | 59 | <tp:docstring> |
57 | 60 | Emitted to indicate that the hold state has changed for this channel. |
58 | 61 | This may occur as a consequence of you requesting a change with |
59 | 62 | RequestHold, or the state changing as a result of a request from |
60 | 63 | another process. |
61 | 64 | </tp:docstring> |
65 | ||
66 | <arg name="HoldState" direction="out" type="u" | |
67 | tp:type="Local_Hold_State"> | |
68 | <tp:docstring> | |
69 | The state of the channel | |
70 | </tp:docstring> | |
71 | </arg> | |
72 | ||
73 | <arg name="Reason" direction="out" type="u" | |
74 | tp:type="Local_Hold_State_Reason"> | |
75 | <tp:docstring> | |
76 | The reason for the state change | |
77 | </tp:docstring> | |
78 | </arg> | |
62 | 79 | </signal> |
80 | ||
81 | <tp:enum name="Local_Hold_State" type="u"> | |
82 | <tp:docstring> | |
83 | The hold state of a channel. | |
84 | </tp:docstring> | |
85 | ||
86 | <tp:enumvalue value="0" suffix="Unheld"> | |
87 | <tp:docstring> | |
88 | All streams are unheld (the call is active). New channels SHOULD | |
89 | have this hold state. | |
90 | </tp:docstring> | |
91 | </tp:enumvalue> | |
92 | ||
93 | <tp:enumvalue value="1" suffix="Held"> | |
94 | <tp:docstring> | |
95 | All streams are held (the call is on hold) | |
96 | </tp:docstring> | |
97 | </tp:enumvalue> | |
98 | ||
99 | <tp:enumvalue value="2" suffix="Pending_Hold"> | |
100 | <tp:docstring> | |
101 | The connection manager is attempting to move to state Held, but | |
102 | has not yet completed that operation. It is unspecified whether | |
103 | any, all or none of the streams making up the channel are on hold. | |
104 | </tp:docstring> | |
105 | </tp:enumvalue> | |
106 | ||
107 | <tp:enumvalue value="3" suffix="Pending_Unhold"> | |
108 | <tp:docstring> | |
109 | The connection manager is attempting to move to state Held, but | |
110 | has not yet completed that operation. It is unspecified whether | |
111 | any, all or none of the streams making up the channel are on hold. | |
112 | </tp:docstring> | |
113 | </tp:enumvalue> | |
114 | </tp:enum> | |
115 | ||
116 | <tp:enum name="Local_Hold_State_Reason" type="u"> | |
117 | <tp:docstring> | |
118 | The reason for a change to the Local_Hold_State. Clients MUST | |
119 | treat unknown values as equivalent to Local_Hold_State_Reason_None. | |
120 | </tp:docstring> | |
121 | ||
122 | <tp:enumvalue value="0" suffix="None"> | |
123 | <tp:docstring> | |
124 | The reason cannot be described by any of the predefined values | |
125 | (connection managers SHOULD avoid this reason, but clients MUST | |
126 | handle it gracefully) | |
127 | </tp:docstring> | |
128 | </tp:enumvalue> | |
129 | ||
130 | <tp:enumvalue value="1" suffix="Requested"> | |
131 | <tp:docstring> | |
132 | The change is in response to a user request | |
133 | </tp:docstring> | |
134 | </tp:enumvalue> | |
135 | ||
136 | <tp:enumvalue value="2" suffix="Resource_Not_Available"> | |
137 | <tp:docstring> | |
138 | The change is because some resource was not available | |
139 | </tp:docstring> | |
140 | </tp:enumvalue> | |
141 | </tp:enum> | |
63 | 142 | |
64 | 143 | <method name="RequestHold"> |
65 | 144 | <arg direction="in" name="Hold" type="b"> |
67 | 146 | A boolean indicating whether or not the channel should be on hold |
68 | 147 | </tp:docstring> |
69 | 148 | </arg> |
70 | <tp:docstring> | |
71 | Request that the channel be put on hold (be instructed not to send | |
72 | any media streams to you) or be taken off hold. Success is indicated | |
73 | by the HoldStateChanged signal being emitted and by a successful | |
74 | return from this method. | |
75 | </tp:docstring> | |
149 | ||
150 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> | |
151 | <p>Request that the channel be put on hold (be instructed not to send | |
152 | any media streams to you) or be taken off hold.</p> | |
153 | ||
154 | <p>If the connection manager can immediately tell that the requested | |
155 | state change could not possibly succeed, this method SHOULD | |
156 | return the NotAvailable error. If the requested state is the | |
157 | same as the current state, this method SHOULD return successfully | |
158 | without doing anything.</p> | |
159 | ||
160 | <p>Otherwise, this method SHOULD immediately set the hold state to | |
161 | Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold | |
162 | (as appropriate), emitting HoldStateChanged if this is a change, | |
163 | and return successfully.</p> | |
164 | ||
165 | <p>The eventual success or failure of the request is indicated by a | |
166 | subsequent HoldStateChanged signal, changing the hold state to | |
167 | Local_Hold_State_Held or Local_Hold_State_Unheld.</p> | |
168 | ||
169 | <p>If the channel has multiple streams, and the connection manager | |
170 | succeeds in changing the hold state of one stream but fails to | |
171 | change the hold state of another, it SHOULD attempt to revert | |
172 | all streams to their previous hold states.</p> | |
173 | ||
174 | <p>The following state transitions SHOULD be used, where | |
175 | appropriate:</p> | |
176 | ||
177 | <ul> | |
178 | <li>Successful hold: | |
179 | (Unheld, any reason) → (Pending_Hold, Requested) → | |
180 | (Held, Requested) | |
181 | </li> | |
182 | <li>Successful unhold: | |
183 | (Held, any reason) → (Pending_Unhold, Requested) → | |
184 | (Unheld, Requested) | |
185 | </li> | |
186 | <li>Attempting to unhold fails at the first attempt to acquire a | |
187 | resource: | |
188 | (Held, any reason) → (Pending_Unhold, Requested) → | |
189 | (Held, Resource_Not_Available) | |
190 | </li> | |
191 | <li>Attempting to unhold acquires one resource, but fails to acquire | |
192 | a second, and takes time to release the first: | |
193 | (Held, any reason) → (Pending_Unhold, Requested) → | |
194 | (Pending_Hold, Resource_Not_Available) → | |
195 | (Held, Resource_Not_Available) | |
196 | </li> | |
197 | </ul> | |
198 | </tp:docstring> | |
199 | ||
76 | 200 | <tp:possible-errors> |
77 | 201 | <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> |
78 | 202 | <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> |
83 | 83 | </tp:docstring> |
84 | 84 | </arg> |
85 | 85 | <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]"> |
86 | <tp:docstring> | |
86 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> | |
87 | 87 | An array of structs representing the pending queue. Each contains: |
88 | 88 | <ul> |
89 | 89 | <li>a numeric identifier</li> |
312 | 312 | </method> |
313 | 313 | |
314 | 314 | <signal name="SetStreamHeld"> |
315 | <tp:docstring> | |
316 | Emitted when the connection manager wishes to place the stream on | |
317 | hold (so the streaming client should free hardware or software | |
318 | resources) or take the stream off hold (so the streaming client should | |
319 | reacquire the necessary resources). | |
315 | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> | |
316 | <p>Emitted when the connection manager wishes to place the stream on | |
317 | hold (so the streaming client should free hardware or software | |
318 | resources) or take the stream off hold (so the streaming client | |
319 | should reacquire the necessary resources).</p> | |
320 | ||
321 | <p>When placing a channel's streams on hold, the connection manager | |
322 | SHOULD notify the remote contact that this will be done (if | |
323 | appropriate in the protocol) before it emits this signal.</p> | |
324 | ||
325 | <tp:rationale> | |
326 | <p>It is assumed that relinquishing a resource will not fail. | |
327 | If it does, the call is probably doomed anyway.</p> | |
328 | </tp:rationale> | |
329 | ||
330 | <p>When unholding a channel's streams, the connection manager | |
331 | SHOULD emit this signal and wait for success to be indicated | |
332 | via HoldState before it notifies the remote contact that the | |
333 | channel has been taken off hold.</p> | |
334 | ||
335 | <tp:rationale> | |
336 | <p>This means that if a resource is unavailable, the remote | |
337 | contact will never even be told that we tried to acquire it.</p> | |
338 | </tp:rationale> | |
320 | 339 | </tp:docstring> |
321 | 340 | <arg name="Held" type="b"> |
322 | 341 | <tp:docstring> |
2 | 2 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
3 | 3 | |
4 | 4 | <tp:title>Telepathy D-Bus Interface Specification</tp:title> |
5 | <tp:version>0.17.3</tp:version> | |
5 | <tp:version>0.17.4</tp:version> | |
6 | 6 | |
7 | 7 | <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> |
8 | 8 | <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> |
476 | 476 | </xsl:choose> |
477 | 477 | </xsl:variable> |
478 | 478 | <xsl:choose> |
479 | <xsl:when test="//tp:simple-type[@name=$tp-type]" /> | |
480 | <xsl:when test="//tp:simple-type[concat(@name, '[]')=$tp-type]" /> | |
481 | <xsl:when test="//tp:struct[concat(@name, '[]')=$tp-type][string(@array-name) != '']" /> | |
482 | <xsl:when test="//tp:mapping[concat(@name, '[]')=$tp-type][string(@array-name) != '']" /> | |
483 | <xsl:when test="//tp:struct[@name=$tp-type]" /> | |
484 | <xsl:when test="//tp:enum[@name=$tp-type]" /> | |
485 | <xsl:when test="//tp:enum[concat(@name, '[]')=$tp-type]" /> | |
486 | <xsl:when test="//tp:flags[@name=$tp-type]" /> | |
487 | <xsl:when test="//tp:flags[concat(@name, '[]')=$tp-type]" /> | |
488 | <xsl:when test="//tp:mapping[@name=$tp-type]" /> | |
489 | <xsl:when test="//tp:external-type[concat(@name, '[]')=$tp-type]" /> | |
490 | <xsl:when test="//tp:external-type[@name=$tp-type]" /> | |
479 | <xsl:when test="//tp:simple-type[@name=$single-type]" /> | |
480 | <xsl:when test="//tp:struct[@name=$single-type]" /> | |
481 | <xsl:when test="//tp:enum[@name=$single-type]" /> | |
482 | <xsl:when test="//tp:flags[@name=$single-type]" /> | |
483 | <xsl:when test="//tp:mapping[@name=$single-type]" /> | |
484 | <xsl:when test="//tp:external-type[@name=$single-type]" /> | |
491 | 485 | <xsl:otherwise> |
492 | 486 | <xsl:message terminate="yes"> |
493 | 487 | <xsl:text>ERR: Unable to find type '</xsl:text> |