« back to all changes in this revision
Viewing changes to spec/Account.xml
- browse files at revision 9
- compare with another revision
- download diff
- download tarball
- view history from revision 9
- Committer: Bazaar Package Importer
- Author(s): Jonny Lamb
- Date: 2009-02-16 10:47:31 UTC
- mfrom: (7.1.14 jaunty)
- Revision ID: james.westby@ubuntu.com-20090216104731-3l467x71wygwok32
Tags: 0.15.6-2
debian/control: Added myself to Uploaders.
- files added:
- debian/README.source
- files modified:
- MANIFEST.in
added
removed
spec/Account.xml
1
<?xml version="1.0" ?>
2
<node name="/Account"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
4
<tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
5
<tp:copyright>Copyright (C) 2008 Nokia Corporation</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 02110-1301, USA.
20
</p>
21
</tp:license>
22
<interface name="org.freedesktop.Telepathy.Account">
23
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
24
<p>An Account object encapsulates the necessary details to make a
25
Telepathy connection.</p>
26
27
<p>Accounts are uniquely identified by object path. The object path
28
of an Account MUST take the form
29
<code>/org/freedesktop/Telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p>
30
31
<ul>
32
<li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type>
33
that appears in the connection manager's well-known bus name and
34
object path</li>
35
<li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
36
<tp:dbus-ref
37
namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
38
but with "-" replaced with "_"
39
(i.e. the same as in the object-path of a <tp:dbus-ref
40
namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li>
41
<li><em>acct</em> is an arbitrary string of ASCII letters, digits
42
and underscores, starting with a letter or underscore, which
43
uniquely identifies this account</li>
44
<li>Clients SHOULD parse the object path to discover the
45
connection manager and protocol</li>
46
<li>Clients MUST NOT attempt to parse <em>acct</em></li>
47
<li>Clients MUST NOT assume that <em>acct</em> matches
48
the connection-specific part of a Connection's object-path and
49
bus name</li>
50
<li>The account manager SHOULD choose <em>acct</em> such that if
51
an account is deleted, its object path will be re-used if and only
52
if the new account is in some sense "the same"
53
(incorporating the 'account' parameter in some way is
54
recommended)</li>
55
</ul>
56
57
<tp:rationale>
58
<p>This API avoids specifying the "profiles" used in Mission Control
59
4.x or the "presets" that have been proposed to replace them. An
60
optional interface will be provided for AM implementations
61
that want to provide presets.</p>
62
63
<p>There is deliberately no functionality here for opening channels;
64
we intend to provide that in the channel dispatcher.</p>
65
66
<p>Other missing features which would be better in their own
67
interfaces:</p>
68
69
<ul>
70
<li>dynamic parameter-providing (aka provisioning)</li>
71
<li>saved server capabilities</li>
72
<li>account conditions</li>
73
<li>account grouping</li>
74
</ul>
75
</tp:rationale>
76
77
</tp:docstring>
78
<tp:added version="0.17.2"/>
79
<tp:changed version="0.17.6">moved the Avatar property to a separate
80
interface</tp:changed>
81
82
<!-- Missing functionality compared with NMC 4.x account + profile,
83
apart from as listed above:
84
85
* vCard field, + default profile for each vCard field
86
(vCard field is per protocol and should be chosen by the
87
Telepathy <-> address-book bridge?; default profile is now
88
meaningless)
89
90
* "normalized name" (normalized handle?)
91
92
* branding icon (what's this and how does it differ from the icon?)
93
94
* configuration UI (not our problem - perhaps the UI could special-case
95
by cm,protocol,preset tuples?)
96
97
* default account domain (somewhat meaningless in general; specialized
98
account config UI can hard-code this)
99
100
* SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol,
101
not the profile, and in any case only the account config UI cares)
102
103
Missing functionality compared with Decibel accounts:
104
105
* we don't really know, they take arbitrary key/value pairs...
106
but display name, protocol, presence/message, current, autoreconnect
107
are the ones given special status by the source, and we have all of them
108
-->
109
110
<property name="Interfaces" tp:name-for-bindings="Interfaces"
111
type="as" tp:type="DBus_Interface[]" access="read">
112
<tp:docstring>
113
A list of the extra interfaces provided by this account.
114
</tp:docstring>
115
</property>
116
117
<method name="Remove" tp:name-for-bindings="Remove">
118
<tp:docstring>Delete the account.</tp:docstring>
119
<tp:possible-errors>
120
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
121
</tp:possible-errors>
122
</method>
123
124
<signal name="Removed" tp:name-for-bindings="Removed">
125
<tp:docstring>
126
This account has been removed.
127
128
<tp:rationale>
129
This is redundant with <tp:dbus-ref
130
namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
131
but it's still worth having,
132
to avoid having to bind to AccountManager.AccountRemoved to tell
133
you whether your Account is valid — ideally, an account-editing UI
134
should only care about a single Account.
135
</tp:rationale>
136
</tp:docstring>
137
</signal>
138
139
<signal name="AccountPropertyChanged"
140
tp:name-for-bindings="Account_Property_Changed">
141
<tp:docstring>
142
The values of one or more properties on this interface (that do not
143
specify that this signal does not apply to them) may have changed.
144
This does not cover properties of other interfaces, which must
145
provide their own change notification if appropriate.
146
</tp:docstring>
147
148
<arg name="Properties" type="a{sv}">
149
<tp:docstring>
150
A map from property names in this namespace (e.g.
151
<tp:member-ref>Nickname</tp:member-ref>) to
152
values. Properties whose values have not changed SHOULD be
153
omitted, but this need not be done.
154
</tp:docstring>
155
</arg>
156
</signal>
157
158
<property name="DisplayName" type="s" access="readwrite"
159
tp:name-for-bindings="Display_Name">
160
<tp:docstring>
161
The user-visible name of this account. This SHOULD be chosen by the
162
user at account creation time. The account creation user interface
163
is responsible for setting a reasonable default value in the user's
164
locale; something like "Jabber (bob@example.com)" would be sensible.
165
166
<tp:rationale>
167
This approximately corresponds to "display name" in NMC 4.x and
168
Decibel.
169
</tp:rationale>
170
</tp:docstring>
171
</property>
172
173
<property name="Icon" tp:name-for-bindings="Icon"
174
type="s" access="readwrite">
175
<tp:docstring>
176
The name of an icon in the system's icon theme, such as "im-msn",
177
or the empty string to not specify an icon. If the icon is set to
178
an empty string, the account manager or any client MAY derive a
179
default icon, for instance from the protocol.
180
181
<tp:rationale>
182
This approximately corresponds to mc_profile_get_icon_name
183
(or possibly mc_profile_get_branding_icon_name) in NMC 4.x.
184
It's accessed via the account rather than the profile because
185
we no longer have profiles as a core concept.
186
</tp:rationale>
187
</tp:docstring>
188
</property>
189
190
<property name="Valid" tp:name-for-bindings="Valid"
191
type="b" access="read">
192
<tp:docstring>
193
If true, this account is considered by the account manager to be
194
complete and usable. If false, user action is required to make it
195
usable, and it will never attempt to connect (for instance, this
196
might be caused by the absence of a required parameter).
197
198
<tp:rationale>
199
For connection managers with a plugin architecture, like
200
telepathy-haze, we have little or no control over the parameters
201
offered; for platforms with package management, we have little or
202
no control over the CMs offered. NMC 4.x would just pretend the
203
account didn't exist in these circumstances, but silent data loss
204
is bad, and UIs with CM-specific knowledge (or a user filling in
205
newly-required parameters) might be able to rescue a broken account.
206
</tp:rationale>
207
</tp:docstring>
208
</property>
209
210
<property name="Enabled" tp:name-for-bindings="Enabled"
211
type="b" access="readwrite">
212
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
213
<p>This property gives the users the possibility to prevent an account
214
from being used. This flag does not change the validity of the
215
account.</p>
216
217
<p>A disabled account can never be put online.</p>
218
219
<tp:rationale>
220
<p>Use cases:</p>
221
222
<ul>
223
<li>user has two or more accounts capable of calling contact X, but
224
he doesn't want the UI to prompt him everytime about which one he
225
wants to use for the call. He can then disable all the equivalent
226
accounts but one.</li>
227
228
<li>There is some temporary server error and the user doesn't want
229
to be be bother by error messages, or change the account
230
configuration: temporarily disabling the account is quicker.</li>
231
</ul>
232
</tp:rationale>
233
234
<p>The AccountManager SHOULD allow this property to be set on invalid
235
accounts, but MUST NOT attempt to put invalid accounts online
236
even if they become Enabled.</p>
237
238
<tp:rationale>
239
<p>There doesn't seem to be any good reason not to allow this.</p>
240
</tp:rationale>
241
</tp:docstring>
242
</property>
243
244
<property name="Nickname" tp:name-for-bindings="Nickname"
245
type="s" access="readwrite">
246
<tp:docstring>
247
The nickname to set on this account for display to other contacts,
248
as set by the user. When the account becomes connected, the
249
account manager SHOULD set this as the user's alias using <tp:dbus-ref
250
namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
251
if appropriate.
252
253
<tp:rationale>
254
In a later specification revision, we plan to separate the concepts
255
of a contact's nickname as set by themselves, and the local
256
name for them in our contact list (a "handle" or "pet name" as
257
described in XEP-0165 and its references). The terminology change
258
from alias to nickname here is a step in that direction.
259
This corresponds to NMC 4.x mc_account_get_alias.
260
</tp:rationale>
261
</tp:docstring>
262
</property>
263
264
<property name="Parameters" tp:name-for-bindings="Parameters"
265
type="a{sv}" access="read">
266
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
267
<p>A map from connection manager parameter names (as in the
268
<tp:dbus-ref
269
namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
270
interface) to their values. This property includes
271
only those parameters that are stored for this account, and SHOULD
272
only include those parameters that the user has explicitly set.
273
</p>
274
<p>This property cannot be altered using Set() - use
275
<tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
276
277
<tp:rationale>
278
This avoids NMC being tied to gconf as a matter of API.
279
</tp:rationale>
280
</tp:docstring>
281
</property>
282
283
<method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
284
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
285
Change the value of the <tp:member-ref>Parameters</tp:member-ref>
286
property. If any of the changed parameters'
287
<tp:type>Conn_Mgr_Param_Flags</tp:type> include
288
<code>DBus_Property</code>, the change will be applied to the
289
corresponding D-Bus Property on the active
290
<tp:member-ref>Connection</tp:member-ref> if there is one; changes to
291
other parameters will not take effect until the next time the account
292
is disconnected and reconnected.
293
294
<tp:rationale>
295
Migration tools that twiddle the settings of all accounts shouldn't
296
cause an automatic disconnect and reconnect, probably. I could be
297
persuaded otherwise, though. Or we could add a Reconnect() method.
298
</tp:rationale>
299
</tp:docstring>
300
301
<tp:changed version="0.17.16">
302
parameters which are also D-Bus properties can and should be updated on
303
existing Connections
304
</tp:changed>
305
306
<arg name="Set" type="a{sv}" direction="in">
307
<tp:docstring>
308
A mapping from parameter names to their values. These parameters
309
should be stored for future use.
310
</tp:docstring>
311
</arg>
312
<arg name="Unset" type="as" direction="in">
313
<tp:docstring>
314
A list of the names of parameters to be removed from the set of
315
stored values, allowing the default values to be used.
316
If the given parameters were not, in fact, stored, or even if they
317
do not exist at all, the account manager MUST accept this without
318
error.
319
</tp:docstring>
320
</arg>
321
322
<tp:possible-errors>
323
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
324
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
325
</tp:possible-errors>
326
</method>
327
328
<property name="AutomaticPresence" type="(uss)" access="readwrite"
329
tp:type="Simple_Presence" tp:name-for-bindings="Automatic_Presence">
330
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
331
<p>The presence status that this account should have if it is brought
332
online.</p>
333
334
<p>Setting this property MUST NOT actually change the account's
335
status until the next time it is (re)connected for some reason.</p>
336
337
<p>The <tp:type>Connection_Presence_Type</tp:type> in the structure
338
SHOULD NOT be Offline or Unset.</p>
339
340
<tp:rationale>
341
In ITOS2007 and ITOS2008 this is a global preference, not visible
342
on D-Bus (the "default presence"). "Automatic presence" better
343
describes when it is used.
344
</tp:rationale>
345
</tp:docstring>
346
</property>
347
348
<property name="ConnectAutomatically" type="b" access="readwrite"
349
tp:name-for-bindings="Connect_Automatically">
350
<tp:docstring>
351
If true, the account manager SHOULD attempt to put this account
352
online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
353
whenever possible (in the base
354
Account interface this is deliberately left vague). If false,
355
it MUST NOT put the account online automatically in response to,
356
for instance, connectivity changes, but SHOULD still put the account
357
online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if
358
requested by the user (for
359
instance, if the user tries to start a conversation using this
360
account).
361
362
<tp:rationale>
363
This approximately corresponds to NMC 4.x "enabled" and Decibel
364
"autoreconnect".
365
</tp:rationale>
366
</tp:docstring>
367
</property>
368
369
<property name="Connection" tp:name-for-bindings="Connection"
370
type="o" access="read">
371
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
372
Either the object path of the <tp:dbus-ref
373
namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to
374
this account, or the special value <code>'/'</code> if there is no
375
connection.
376
377
<tp:rationale>
378
Object paths aren't nullable, so we can't use an empty string.
379
</tp:rationale>
380
</tp:docstring>
381
</property>
382
383
<property name="ConnectionStatus" type="u" access="read"
384
tp:name-for-bindings="Connection_Status">
385
<tp:docstring>
386
If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
387
the status of that connection.
388
If the Connection property is the empty string, this property may
389
either be Disconnected (indicating that the account manager is not
390
attempting to bring it online), or Connecting (indicating that the
391
account manager is attempting to connect).
392
The account manager is expected to set this by observing signals
393
from the Connection.
394
395
<tp:rationale>
396
If the AM is doing some sort of backoff/delay on reconnection
397
attempts, the account's status is conceptually "Connecting" even
398
though there is no Connection. This vaguely corresponds to
399
GetCurrentStatus in NMC 4.x.
400
</tp:rationale>
401
</tp:docstring>
402
</property>
403
404
<property name="ConnectionStatusReason" type="u" access="read"
405
tp:name-for-bindings="Connection_Status_Reason">
406
<tp:docstring>
407
The reason for the last change to
408
<tp:member-ref>ConnectionStatus</tp:member-ref>.
409
The account manager is expected to set this by observing signals
410
from the Connection.
411
412
<tp:rationale>
413
If you weren't watching the Connection at the time it failed,
414
you can't tell why - unless the AM can tell you. This is part
415
of GetCurrentStatus in NMC 4.x.
416
</tp:rationale>
417
</tp:docstring>
418
</property>
419
420
<property name="CurrentPresence" type="(uss)" access="read"
421
tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence">
422
<tp:docstring>
423
The actual presence. If the connection is not online, this should be
424
(Connection_Presence_Type_Offline, "", "").
425
If the connection is online but does not support the <tp:dbus-ref
426
namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
427
interface, this should be (Connection_Presence_Type_Unset, "", "").
428
The account manager is expected to set this by observing signals
429
from the Connection.
430
431
<tp:rationale>
432
This corresponds to GetPresenceActual in NMC 4.x.
433
</tp:rationale>
434
</tp:docstring>
435
</property>
436
437
<property name="RequestedPresence" type="(uss)" access="readwrite"
438
tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence">
439
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
440
<p>The requested presence for this account. When this is changed, the
441
account manager should attempt to manipulate the connection manager to
442
make <tp:member-ref>CurrentPresence</tp:member-ref> match
443
<tp:member-ref>RequestedPresence</tp:member-ref> as closely as
444
possible. It should not be saved to any sort of persistent
445
storage.</p>
446
447
<p>When the account manager automatically connects an account,
448
it must signal this by setting the RequestedPresence to the same
449
thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>
450
451
<tp:rationale>
452
This corresponds to e.g. GetPresence and GetPresenceMessage
453
in NMC 4.x.
454
</tp:rationale>
455
</tp:docstring>
456
</property>
457
458
<property name="NormalizedName" type="s" access="read"
459
tp:name-for-bindings="Normalized_Name">
460
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
461
<p>The normalized user ID of the local user on this account (i.e. the
462
string returned when the <tp:dbus-ref
463
namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
464
method is called on the
465
result of <tp:dbus-ref
466
namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>
467
for an active connection).</p>
468
469
<p>It is unspecified whether this user ID is globally unique.</p>
470
471
<tp:rationale>
472
<p>As currently implemented, IRC user IDs are only unique within
473
the same IRCnet. On some saner protocols, the user ID includes a
474
DNS name which provides global uniqueness.</p>
475
</tp:rationale>
476
477
<p>If this value is not known yet (which will always be the case for
478
accounts that have never been online), it will be an empty
479
string.</p>
480
481
<p>It is possible that this value will change if the connection
482
manager's normalization algorithm changes, although this SHOULD
483
be avoided.</p>
484
485
<tp:rationale>
486
<p>It's not always completely clear what normalization algorithm
487
should be used; for instance, in Gabble, we currently use JIDs,
488
but it would also have been reasonable to use xmpp URIs.</p>
489
</tp:rationale>
490
</tp:docstring>
491
</property>
492
493
</interface>
494
</node>
495
<!-- vim:set sw=2 sts=2 et ft=xml: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.1