diff options
Diffstat (limited to 'spec/Connection_Interface_Aliasing.xml')
| -rw-r--r-- | spec/Connection_Interface_Aliasing.xml | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml new file mode 100644 index 0000000..9675771 --- /dev/null +++ b/spec/Connection_Interface_Aliasing.xml @@ -0,0 +1,185 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Aliasing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </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.Connection.Interface.Aliasing"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:mapping name="Alias_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are aliases.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:mapping> + + <tp:struct name="Alias_Pair" array-name="Alias_Pair_List"> + <tp:docstring> + A pair (contact handle, alias) as seen in the + <tp:member-ref>AliasesChanged</tp:member-ref> signal. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:struct> + + <signal name="AliasesChanged" tp:name-for-bindings="Aliases_Changed"> + <arg name="Aliases" type="a(us)" tp:type="Alias_Pair[]"> + <!-- FIXME: if we break API, this could be an Alias_Map, a{us} --> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array containing structs of: + <ul> + <li>the handle representing the contact</li> + <li>the new alias</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when a contact's alias (or that of the user) is changed. + </tp:docstring> + </signal> + <tp:flags name="Connection_Alias_Flags" value-prefix="Connection_Alias_Flag" type="u"> + <tp:flag suffix="User_Set" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The aliases of contacts on this connection may be changed by the + user of the service, not just by the contacts themselves. This is + the case on Jabber, for instance.</p> + <p>It is possible that aliases can be changed by the contacts too - + which alias takes precedence is not defined by this + specification, and depends on the server and/or connection manager + implementation.</p> + <p>This flag only applies to the aliases of "globally valid" contact + handles. At this time, clients should not expect to be able to + change the aliases corresponding to any channel-specific + handles. If this becomes possible in future, a new flag will + be defined.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="GetAliasFlags" tp:name-for-bindings="Get_Alias_Flags"> + <arg direction="out" type="u" tp:type="Connection_Alias_Flags" + name="Alias_Flags"> + <tp:docstring> + An integer with a bitwise OR of flags from ConnectionAliasFlags + </tp:docstring> + </arg> + <tp:docstring> + Return a bitwise OR of flags detailing the behaviour of aliases on this + connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + <method name="RequestAliases" tp:name-for-bindings="Request_Aliases"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as" name="Aliases"> + <tp:docstring> + A list of aliases in the same order as the contact handles + </tp:docstring> + </arg> + <tp:docstring> + Request the value of several contacts' aliases at once. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + <method name="GetAliases" tp:name-for-bindings="Get_Aliases"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="a{us}" tp:type="Alias_Map" name="Aliases"> + <tp:docstring> + A dictionary mapping contact handles to aliases + </tp:docstring> + </arg> + <tp:docstring> + Request the value of several contacts' aliases at once. This SHOULD + only return cached aliases, falling back on the contact identifier + (i.e. the string corresponding to the handle) if none is present. Also + if there was no cached alias, a request SHOULD be started of which the + result is later signalled by + <tp:member-ref>AliasesChanged</tp:member-ref>. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + <method name="SetAliases" tp:name-for-bindings="Set_Aliases"> + <arg direction="in" name="Aliases" type="a{us}" tp:type="Alias_Map"> + <tp:docstring> + A dictionary mapping integer handles of contacts + to strings of the new alias to set. + </tp:docstring> + </arg> + <tp:docstring> + Request that the alias of the given contact be changed. Success will be + indicated by emitting an <tp:member-ref>AliasesChanged</tp:member-ref> + signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is + not set, this method will only ever succeed if the contact is the + user's own handle (as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:contact-attribute name="alias" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same string that would be returned by + <tp:member-ref>GetAliases</tp:member-ref> + (always present with some value, possibly the + same as Connection/contact-id, if information from the + Aliasing interface was requested) + </p> + </tp:docstring> + </tp:contact-attribute> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols where contacts have an + alias which they can change at will. Provides a method for the user to set + their own alias, and a signal which should be emitted when a contact's + alias is changed or first discovered.</p> + + <p>On connections where the user is allowed to set aliases for contacts and + store them on the server, the <tp:member-ref>GetAliasFlags</tp:member-ref> + method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the + <tp:member-ref>SetAliases</tp:member-ref> method may be called on contact + handles other than the user themselves.</p> + + <p>Aliases are intended to be used as the main displayed name for the + contact, where available.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |