Added Connection.Interface.Renaming to /extensions

3 files changed, 100 insertions, 0 deletions

diff --git a/extensions/Connection_Interface_Renaming.xml b/extensions/Connection_Interface_Renaming.xml
new file mode 100644
index 000000000..d08b748d9
--- /dev/null
+++ b/extensions/Connection_Interface_Renaming.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Renaming" 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.Renaming"
+    tp:causes-havoc='not well-tested'>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <signal name="Renamed" tp:name-for-bindings="Renamed">
+      <arg name="Original" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The handle of the original identifier
+        </tp:docstring>
+      </arg>
+      <arg name="New" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The handle of the new identifier
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when the unique identifier of a contact on the server
+          changes.</p>
+
+        <p>Any channels associated with the contact's original handle will
+          continue to be to that handle, and so are no longer useful (unless
+          the contact renames back, or another contact connects with that
+          unique ID). Clients may open a similar channel associated with the
+          new handle to continue communicating with the contact.</p>
+
+        <p>For example, if a GUI client associates text
+          channels with chat windows, it should detach the old channel
+          from the chat window, closing it, and associate a channel to the
+          new handle with the same window.</p>
+
+        <p>If the contact's old handle is in any of the member lists of
+          a channel which has the groups interface, it will be removed from
+          the channel and the new handle will be added. The resulting
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>
+          signal must be emitted <em>after</em> the
+          <tp:member-ref>Renamed</tp:member-ref> signal; the reason should be
+          RENAMED.
+        </p>
+
+        <p>The handles may be either general-purpose or channel-specific.
+          If the original handle is general-purpose, the new handle must be
+          general-purpose; if the original handle is channel-specific, the
+          new handle must be channel-specific in the same channel.
+        </p>
+      </tp:docstring>
+    </signal>
+    <method name="RequestRename" tp:name-for-bindings="Request_Rename">
+      <arg direction="in" name="Identifier" type="s">
+        <tp:docstring>
+          The desired identifier
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the user's own identifier is changed on the server.
+          If successful, a <tp:member-ref>Renamed</tp:member-ref> signal will
+          be emitted for the current "self handle" as returned by <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>.</p>
+        <p>It is protocol-dependent how the identifier that's actually
+          used will be derived from the supplied identifier; some sort of
+          normalization might take place.</p>
+      </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:docstring>
+      An interface on connections to support protocols where the unique
+    identifiers of contacts can change. Because handles are immutable,
+    this is represented by a pair of handles, that representing the
+    old name, and that representing the new one.
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 843793a4c..ef8b751fb 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -14,6 +14,7 @@ EXTRA_DIST = \
     misc.xml \
     Debug.xml \
     Logger.xml \
+    Connection_Interface_Renaming.xml \
     Authentication_TLS_Certificate.xml \
     Channel_Type_Server_TLS_Connection.xml \
     $(NULL)
diff --git a/extensions/misc.xml b/extensions/misc.xml
index 39a987efc..ad0d59e92 100644
--- a/extensions/misc.xml
+++ b/extensions/misc.xml
@@ -6,6 +6,7 @@
 
 <xi:include href="Debug.xml" />
 <xi:include href="Logger.xml" />
+<xi:include href="Connection_Interface_Renaming.xml" />
 <xi:include href="Authentication_TLS_Certificate.xml" />
 <xi:include href="Channel_Type_Server_TLS_Connection.xml" />