extensions/Connection_Interface_Renaming.xml

   1 <?xml version="1.0" ?>
   2 <node name="/Connection_Interface_Renaming" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   3   <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
   4   <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
   5   <tp:copyright> Copyright (C) 2006 INdT </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.</p>
  20   </tp:license>
  21   <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming"
  22     tp:causes-havoc='not well-tested'>
  23     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
  24     <signal name="Renamed" tp:name-for-bindings="Renamed">
  25       <arg name="Original" type="u" tp:type="Contact_Handle">
  26         <tp:docstring>
  27           The handle of the original identifier
  28         </tp:docstring>
  29       </arg>
  30       <arg name="New" type="u" tp:type="Contact_Handle">
  31         <tp:docstring>
  32           The handle of the new identifier
  33         </tp:docstring>
  34       </arg>
  35       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  36         <p>Emitted when the unique identifier of a contact on the server
  37           changes.</p>
  38
  39         <p>Any channels associated with the contact's original handle will
  40           continue to be to that handle, and so are no longer useful (unless
  41           the contact renames back, or another contact connects with that
  42           unique ID). Clients may open a similar channel associated with the
  43           new handle to continue communicating with the contact.</p>
  44
  45         <p>For example, if a GUI client associates text
  46           channels with chat windows, it should detach the old channel
  47           from the chat window, closing it, and associate a channel to the
  48           new handle with the same window.</p>
  49
  50         <p>If the contact's old handle is in any of the member lists of
  51           a channel which has the groups interface, it will be removed from
  52           the channel and the new handle will be added. The resulting
  53           <tp:dbus-ref
  54             namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>
  55           signal must be emitted <em>after</em> the
  56           <tp:member-ref>Renamed</tp:member-ref> signal; the reason should be
  57           RENAMED.
  58         </p>
  59
  60         <p>The handles may be either general-purpose or channel-specific.
  61           If the original handle is general-purpose, the new handle must be
  62           general-purpose; if the original handle is channel-specific, the
  63           new handle must be channel-specific in the same channel.
  64         </p>
  65       </tp:docstring>
  66     </signal>
  67     <method name="RequestRename" tp:name-for-bindings="Request_Rename">
  68       <arg direction="in" name="Identifier" type="s">
  69         <tp:docstring>
  70           The desired identifier
  71         </tp:docstring>
  72       </arg>
  73       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  74         <p>Request that the user's own identifier is changed on the server.
  75           If successful, a <tp:member-ref>Renamed</tp:member-ref> signal will
  76           be emitted for the current "self handle" as returned by <tp:dbus-ref
  77             namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>.</p>
  78         <p>It is protocol-dependent how the identifier that's actually
  79           used will be derived from the supplied identifier; some sort of
  80           normalization might take place.</p>
  81       </tp:docstring>
  82       <tp:possible-errors>
  83         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
  84         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
  85         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
  86         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
  87         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
  88       </tp:possible-errors>
  89     </method>
  90     <tp:docstring>
  91       An interface on connections to support protocols where the unique
  92     identifiers of contacts can change. Because handles are immutable,
  93     this is represented by a pair of handles, that representing the
  94     old name, and that representing the new one.
  95     </tp:docstring>
  96   </interface>
  97 </node>
  98 <!-- vim:set sw=2 sts=2 et ft=xml: -->