[Telepathy-commits] [telepathy-mission-control/master] Account, Account_Manager, Account_Interface_Avatar: update from telepathy-spec 0.17.22
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Mar 25 12:42:20 PDT 2009
No substantive changes, except the special DBus_Property behaviour (which
MC already implements).
---
xml/Account.xml | 103 +++++++++++++++++++++++++------------
xml/Account_Interface_Avatar.xml | 2 +
xml/Account_Manager.xml | 49 +++++++++++++-----
3 files changed, 106 insertions(+), 48 deletions(-)
diff --git a/xml/Account.xml b/xml/Account.xml
index e5b755f..9dc34ad 100644
--- a/xml/Account.xml
+++ b/xml/Account.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -33,8 +33,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
that appears in the connection manager's well-known bus name and
object path</li>
<li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
- ConnectionManager.ListProtocols, but with "-" replaced with "_"
- (i.e. the same as in the object-path of a Connection)</li>
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
+ but with "-" replaced with "_"
+ (i.e. the same as in the object-path of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li>
<li><em>acct</em> is an arbitrary string of ASCII letters, digits
and underscores, starting with a letter or underscore, which
uniquely identifies this account</li>
@@ -123,9 +126,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This account has been removed.
<tp:rationale>
- This is redundant with AccountRemoved, but it's still worth having,
+ This is redundant with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
+ but it's still worth having,
to avoid having to bind to AccountManager.AccountRemoved to tell
- you whether your Account is valid - ideally, an account-editing UI
+ you whether your Account is valid — ideally, an account-editing UI
should only care about a single Account.
</tp:rationale>
</tp:docstring>
@@ -142,7 +147,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<arg name="Properties" type="a{sv}">
<tp:docstring>
- A map from property names in this namespace (e.g. Nickname) to
+ A map from property names in this namespace (e.g.
+ <tp:member-ref>Nickname</tp:member-ref>) to
values. Properties whose values have not changed SHOULD be
omitted, but this need not be done.
</tp:docstring>
@@ -223,14 +229,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
to be be bother by error messages, or change the account
configuration: temporarily disabling the account is quicker.</li>
</ul>
+ </tp:rationale>
- <p>The AccountManager SHOULD allow this property to be set on invalid
- accounts, but MUST NOT attempt to put invalid accounts online
- even if they become Enabled.</p>
+ <p>The AccountManager SHOULD allow this property to be set on invalid
+ accounts, but MUST NOT attempt to put invalid accounts online
+ even if they become Enabled.</p>
- <tp:rationale>
- <p>There doesn't seem to be any good reason not to allow this.</p>
- </tp:rationale>
+ <tp:rationale>
+ <p>There doesn't seem to be any good reason not to allow this.</p>
</tp:rationale>
</tp:docstring>
</property>
@@ -240,7 +246,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
The nickname to set on this account for display to other contacts,
as set by the user. When the account becomes connected, the
- account manager SHOULD set this as the user's alias using SetAliases
+ account manager SHOULD set this as the user's alias using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
if appropriate.
<tp:rationale>
@@ -258,12 +265,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
type="a{sv}" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A map from connection manager parameter names (as in the
- ConnectionManager interface) to their values. This property includes
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+ interface) to their values. This property includes
only those parameters that are stored for this account, and SHOULD
only include those parameters that the user has explicitly set.
</p>
<p>This property cannot be altered using Set() - use
- UpdateParameters instead.</p>
+ <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
<tp:rationale>
This avoids NMC being tied to gconf as a matter of API.
@@ -272,10 +281,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</property>
<method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
- <tp:docstring>
- Change the value of the Parameters property. Any changes will not
- take effect until the next time the account is disconnected and
- reconnected.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Change the value of the <tp:member-ref>Parameters</tp:member-ref>
+ property. If any of the changed parameters'
+ <tp:type>Conn_Mgr_Param_Flags</tp:type> include
+ <code>DBus_Property</code>, the change will be applied to the
+ corresponding D-Bus Property on the active
+ <tp:member-ref>Connection</tp:member-ref> if there is one; changes to
+ other parameters will not take effect until the next time the account
+ is disconnected and reconnected.
<tp:rationale>
Migration tools that twiddle the settings of all accounts shouldn't
@@ -284,6 +298,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:rationale>
</tp:docstring>
+ <tp:changed version="0.17.16">
+ parameters which are also D-Bus properties can and should be updated on
+ existing Connections
+ </tp:changed>
+
<arg name="Set" type="a{sv}" direction="in">
<tp:docstring>
A mapping from parameter names to their values. These parameters
@@ -330,11 +349,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="Connect_Automatically">
<tp:docstring>
If true, the account manager SHOULD attempt to put this account
- online with the AutomaticPresence whenever possible (in the base
+ online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
+ whenever possible (in the base
Account interface this is deliberately left vague). If false,
it MUST NOT put the account online automatically in response to,
for instance, connectivity changes, but SHOULD still put the account
- online with the AutomaticPresence if requested by the user (for
+ online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if
+ requested by the user (for
instance, if the user tries to start a conversation using this
account).
@@ -347,9 +368,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<property name="Connection" tp:name-for-bindings="Connection"
type="o" access="read">
- <tp:docstring>
- Either the object path of the connection to this account,
- or the special value '/' if there is no connection.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the object path of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to
+ this account, or the special value <code>'/'</code> if there is no
+ connection.</p>
+
+ <p>If this object path is not '/', the Connection's well-known bus
+ name can be derived from this object path by removing the first '/'
+ and replacing subsequent '/' characters with '.'.</p>
<tp:rationale>
Object paths aren't nullable, so we can't use an empty string.
@@ -360,7 +387,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<property name="ConnectionStatus" type="u" access="read"
tp:name-for-bindings="Connection_Status">
<tp:docstring>
- If the Connection property is non-empty, the status of that connection.
+ If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
+ the status of that connection.
If the Connection property is the empty string, this property may
either be Disconnected (indicating that the account manager is not
attempting to bring it online), or Connecting (indicating that the
@@ -380,7 +408,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<property name="ConnectionStatusReason" type="u" access="read"
tp:name-for-bindings="Connection_Status_Reason">
<tp:docstring>
- The reason for the last change to ConnectionStatus.
+ The reason for the last change to
+ <tp:member-ref>ConnectionStatus</tp:member-ref>.
The account manager is expected to set this by observing signals
from the Connection.
@@ -397,7 +426,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
The actual presence. If the connection is not online, this should be
(Connection_Presence_Type_Offline, "", "").
- If the connection is online but does not support the Presence
+ If the connection is online but does not support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
interface, this should be (Connection_Presence_Type_Unset, "", "").
The account manager is expected to set this by observing signals
from the Connection.
@@ -412,14 +442,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The requested presence for this account. When this is changed, the
- account manager should attempt to manipulate the connection manager
- to make CurrentPresence match RequestedPresence as closely as
+ account manager should attempt to manipulate the connection manager to
+ make <tp:member-ref>CurrentPresence</tp:member-ref> match
+ <tp:member-ref>RequestedPresence</tp:member-ref> as closely as
possible. It should not be saved to any sort of persistent
storage.</p>
<p>When the account manager automatically connects an account,
it must signal this by setting the RequestedPresence to the same
- thing as the AutomaticPresence.</p>
+ thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>
<tp:rationale>
This corresponds to e.g. GetPresence and GetPresenceMessage
@@ -432,9 +463,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="Normalized_Name">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The normalized user ID of the local user on this account (i.e. the
- string returned when the InspectHandle method is called on the
- result of GetSelfHandle() for an active connection).</p>
-
+ string returned when the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ method is called on the
+ result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>
+ for an active connection).</p>
+
<p>It is unspecified whether this user ID is globally unique.</p>
<tp:rationale>
diff --git a/xml/Account_Interface_Avatar.xml b/xml/Account_Interface_Avatar.xml
index 3d0c2a9..6c85b8e 100644
--- a/xml/Account_Interface_Avatar.xml
+++ b/xml/Account_Interface_Avatar.xml
@@ -20,6 +20,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</p>
</tp:license>
<interface name="org.freedesktop.Telepathy.Account.Interface.Avatar">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface extends the core Account interface to provide a
user-settable avatar image.</p>
diff --git a/xml/Account_Manager.xml b/xml/Account_Manager.xml
index b92913e..6fb9b08 100644
--- a/xml/Account_Manager.xml
+++ b/xml/Account_Manager.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account_Manager"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -63,7 +63,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="Valid_Accounts">
<tp:docstring>
A list of the valid (complete, usable) accounts. Change notification
- is via AccountValidityChanged.
+ is via <tp:member-ref>AccountValidityChanged</tp:member-ref>.
<tp:rationale>
This split between valid and invalid accounts makes it easy to
@@ -78,7 +78,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="Invalid_Accounts">
<tp:docstring>
A list of incomplete or otherwise unusable accounts. Change
- notification is via AccountValidityChanged.
+ notification is via
+ <tp:member-ref>AccountValidityChanged</tp:member-ref>.
</tp:docstring>
</property>
@@ -88,7 +89,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:rationale>
This is effectively change notification for the valid and invalid
- accounts lists.
+ accounts lists. On emission of this signal, the Account indicated
+ will no longer be present in either of the lists.
</tp:rationale>
</tp:docstring>
@@ -127,9 +129,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<method name="CreateAccount" tp:name-for-bindings="Create_Account">
<tp:docstring>
- Request the creation of a new account. The account manager SHOULD NOT
- allow invalid accounts to be created. Accounts created through this
- API SHOULD have an empty PresetParameters property.
+ Request the creation of a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The
+ account manager SHOULD NOT allow invalid accounts to be created.
</tp:docstring>
<arg name="Connection_Manager" direction="in" type="s"
@@ -145,19 +147,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
<arg name="Display_Name" direction="in" type="s">
- <tp:docstring>The initial value of the new account's DisplayName
- property. The account manager MAY modify this to make it unique,
- for instance by appending a number or the 'account'
- parameter.</tp:docstring>
+ <tp:docstring>The initial value of the new account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ property. The account manager SHOULD modify this to make it unique if
+ an Account already exists with the same display name, for instance by
+ appending a number or the 'account' parameter. Account manager
+ implementations SHOULD accept an empty string but account editing user
+ interfaces should avoid passing an empty string for this parameter.
+
+ <tp:rationale>
+ <p>The account creation UI may ask the user for a name for the new
+ account. If the author of the UI chooses not to do this, the
+ account creation UI is better able to suggest a default display
+ name because it has protocol-specific knowledge which the account
+ manager does not.</p>
+
+ <p>The account manager always knows the complete list of accounts so
+ it can easily tell whether it should append something to the
+ display name to avoid presenting two identically-named accounts to
+ the user.</p>
+ </tp:rationale>
+ </tp:docstring>
</arg>
<arg name="Parameters" direction="in" type="a{sv}">
<tp:docstring>Initial parameter values, as would be passed to
- RequestConnection.</tp:docstring>
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring>
</arg>
<arg name="Account" direction="out" type="o">
- <tp:docstring>The new account.</tp:docstring>
+ <tp:docstring>The new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring>
</arg>
<tp:possible-errors>
--
1.5.6.5
More information about the telepathy-commits
mailing list