diff options
Diffstat (limited to 'qt4/spec/Account_Manager.xml')
| -rw-r--r-- | qt4/spec/Account_Manager.xml | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/qt4/spec/Account_Manager.xml b/qt4/spec/Account_Manager.xml new file mode 100644 index 000000000..cd82e7f53 --- /dev/null +++ b/qt4/spec/Account_Manager.xml @@ -0,0 +1,296 @@ +<?xml version="1.0" ?> +<node name="/Account_Manager" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <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 +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.AccountManager"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The account manager is a central service used to store account + details.</p> + + <p>The current account manager is defined to be the process that owns + the well-known bus name org.freedesktop.Telepathy.AccountManager on + the session bus. This process must export an + /org/freedesktop/Telepathy/AccountManager object with the + AccountManager interface.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of AccountManager implementation, implementations SHOULD NOT + register as an activatable service for the AccountManager's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs can + detect whether Telepathy is in use by checking whether the + AccountManager's well-known name is in use at runtime.</p> + </tp:docstring> + <tp:added version="0.17.2"/> + + <!-- Missing functionality compared with NMC 4.x: + * look up accounts by conditions (can be done client-side, less + efficiently, so not a blocker) + * global presence/... changes (can be done client-side, less efficiently - + we should add this) + * count used channels (what's this for?) + * get "average" status (not well-defined, UIs can do this) + * request channels (out of scope: Channel Dispatcher will do this) + * register filters (completely out of scope: Channel Dispatcher again) + --> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:docstring> + A list of the interfaces provided by the account manager object. + </tp:docstring> + </property> + + <property name="ValidAccounts" type="ao" access="read" + tp:name-for-bindings="Valid_Accounts"> + <tp:docstring> + A list of the valid (complete, usable) <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change + notification is via + <tp:member-ref>AccountValidityChanged</tp:member-ref>. + + <tp:rationale> + This split between valid and invalid accounts makes it easy to + ignore the invalid ones. The only things that should be manipulating + invalid accounts are account-editing UIs, which might be able to + rescue them. + </tp:rationale> + </tp:docstring> + </property> + + <property name="InvalidAccounts" type="ao" access="read" + tp:name-for-bindings="Invalid_Accounts"> + <tp:docstring> + A list of incomplete or otherwise unusable <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change + notification is via + <tp:member-ref>AccountValidityChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="AccountRemoved" tp:name-for-bindings="Account_Removed"> + <tp:docstring> + The given account has been removed. + + <tp:rationale> + This is effectively change notification for the valid and invalid + accounts lists. On emission of this signal, the Account indicated + will no longer be present in either of the lists. + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o"> + <tp:docstring> + An Account, which must not be used any more. + </tp:docstring> + </arg> + </signal> + + <signal name="AccountValidityChanged" + tp:name-for-bindings="Account_Validity_Changed"> + <tp:docstring> + The validity of the given account has changed. New accounts are + also indicated by this signal, as an account validity change + (usually to True) on an account that did not previously exist. + + <tp:rationale> + This is effectively change notification for the valid and invalid + accounts lists. + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o"> + <tp:docstring> + An <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Valid" type="b"> + <tp:docstring> + True if the account is now valid. + </tp:docstring> + </arg> + </signal> + + <property name="SupportedAccountProperties" + tp:name-for-bindings="Supported_Account_Properties" + type="as" tp:type="DBus_Qualified_Member[]" access="read"> + <tp:added version="0.17.24"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the fully qualified names of properties that can be set + via the Properties argument to + <tp:member-ref>CreateAccount</tp:member-ref> when an account is + created.</p> + + <tp:rationale> + <p>Examples of good properties to support here include + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>. + </p> + + <p>Examples of properties that would make no sense here include + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>. + </p> + </tp:rationale> + + <p>This property MUST NOT include include the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> + properties, which are set using separate arguments.</p> + + <p>This property MAY include the names of properties that, after + account creation, will be read-only: this indicates that the property + can be set at account creation but not changed later.</p> + + <tp:rationale> + <p>For example, an account manager might support migration tools that + use this to preserve the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref> + property, even though that property is usually read-only.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="CreateAccount" tp:name-for-bindings="Create_Account"> + <tp:docstring> + 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> + <tp:changed version="0.17.24">added the Properties argument</tp:changed> + + <arg name="Connection_Manager" direction="in" type="s" + tp:type="Connection_Manager_Name"> + <tp:docstring> + The name of the connection manager, e.g. "salut". + </tp:docstring> + </arg> + + <arg name="Protocol" direction="in" type="s" + tp:type="Protocol"> + <tp:docstring>The protocol, e.g. "local-xmpp".</tp:docstring> + </arg> + + <arg name="Display_Name" direction="in" type="s"> + <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 + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring> + </arg> + + <arg name="Properties" direction="in" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The values of any other properties to be set immediately on the + new Account.</p> + + <p>Only the properties mentioned in + <tp:member-ref>SupportedAccountProperties</tp:member-ref> are + acceptable here. In particular, the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> + properties are never allowed here, since they are set using the other + arguments to this method.</p> + + <p>Account manager implementations SHOULD support creating accounts + with an empty value for this argument.</p> + </tp:docstring> + </arg> + + <arg name="Account" direction="out" type="o"> + <tp:docstring>The new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Connection_Manager is not installed or does not + implement the given Protocol, or one of the properties in the + Properties argument is unsupported.</p> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Parameters provided omit a required parameter + or provide unsupported parameter, or the type of one + of the Parameters or Properties is inappropriate.</p> + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> + |