[next] telepathy-spec: Remove InspectHandles
Xavier Claessens
xclaesse at kemper.freedesktop.org
Thu Jun 7 07:24:04 PDT 2012
Module: telepathy-spec
Branch: next
Commit: 490816714ef5a4b13a9e1eb779d9990fb78b5d15
URL: http://cgit.freedesktop.org/telepathy/telepathy-spec/commit/?id=490816714ef5a4b13a9e1eb779d9990fb78b5d15
Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date: Thu May 31 15:50:42 2012 +0200
Remove InspectHandles
Identifiers are always given together with handles, so it must never
be needed to inspect an handle.
---
spec/Account.xml | 6 +---
spec/Channel.xml | 35 ------------------------------
spec/Channel_Interface_Group1.xml | 4 +--
spec/Channel_Type_Room_List1.xml | 3 +-
spec/Channel_Type_Text.xml | 8 ++----
spec/Connection.xml | 43 +-----------------------------------
6 files changed, 9 insertions(+), 90 deletions(-)
diff --git a/spec/Account.xml b/spec/Account.xml
index b700b8f..0df5b0b 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -667,10 +667,8 @@ 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 <tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>
- method is called on the value of the <tp:dbus-ref
- namespace="im.telepathy1.Connection">SelfHandle</tp:dbus-ref>
+ value of the <tp:dbus-ref
+ namespace="im.telepathy1.Connection">SelfID</tp:dbus-ref>
property for an active connection).</p>
<p>It is unspecified whether this user ID is globally unique.</p>
diff --git a/spec/Channel.xml b/spec/Channel.xml
index b688397..136b077 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -109,22 +109,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
room, etc. with which this channel communicates), or the empty
string if the TargetHandle is 0.</p>
- <tp:rationale>
- <p>The presence of this property avoids the following race
- condition:</p>
-
- <ul>
- <li>New channel C is signalled with target handle T</li>
- <li>Client calls <tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
- [T])</li>
- <li>Channel C closes, removing the last reference to handle T</li>
- <li><tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
- [T]) returns an error</li>
- </ul>
- </tp:rationale>
-
<p>If this is present in a channel request,
<tp:member-ref>TargetHandleType</tp:member-ref>
MUST be present and not Handle_Type_None, and
@@ -303,25 +287,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member-ref>InitiatorHandle</tp:member-ref>
property (i.e. the initiator's identifier in the IM protocol).</p>
- <tp:rationale>
- <p>The presence of this property avoids the following race
- condition:</p>
-
- <ul>
- <li>New Call channel C is signalled with initiator
- handle I</li>
- <li>Client calls <tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
- [I])</li>
- <li>Channel C closes, removing the last reference to handle I</li>
- <li><tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
- [I]) returns an error</li>
- <li>Client can indicate that a call was missed, but not who
- called!</li>
- </ul>
- </tp:rationale>
-
<p>It does not make sense for this property to be in channel
requests - the initiator will always be the local user - so it
MUST NOT be accepted.</p>
diff --git a/spec/Channel_Interface_Group1.xml b/spec/Channel_Interface_Group1.xml
index ca2201d..1204c32 100644
--- a/spec/Channel_Interface_Group1.xml
+++ b/spec/Channel_Interface_Group1.xml
@@ -614,9 +614,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
<tp:member type="s" name="Identifier">
<tp:docstring>
- The same string that would be returned by <tp:dbus-ref
- namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>
- for this handle.
+ The normalized contact identifier.
</tp:docstring>
</tp:member>
</tp:mapping>
diff --git a/spec/Channel_Type_Room_List1.xml b/spec/Channel_Type_Room_List1.xml
index f462e3a..4b5ccd6 100644
--- a/spec/Channel_Type_Room_List1.xml
+++ b/spec/Channel_Type_Room_List1.xml
@@ -76,8 +76,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dl>
<dt>handle-name (s)</dt>
- <dd>The identifier of the room (as would be returned by
- <tp:dbus-ref namespace="im.telepathy1.Connection">InspectHandles</tp:dbus-ref>)</dd>
+ <dd>The identifier of the room</dd>
<dt>name (s)</dt>
<dd>The human-readable name of the room if different from the handle</dd>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index b78c2c3..b50beb8 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -603,11 +603,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
who sent the message could not be determined.</dd>
<dt>message-sender-id (s)</dt>
- <dd>The identifier of the contact who sent the message,
- i.e. the result of calling <tp:dbus-ref
- namespace="imt1.Connection">InspectHandles</tp:dbus-ref>
- on <code>message-sender</code>. If omitted, clients MUST
- fall back to looking at <code>message-sender</code>.</dd>
+ <dd>The identifier of the contact who sent the message. If empty or
+ omitted, the contact who sent the message could not be
+ determined.</dd>
<dt>sender-nickname (s)</dt>
<dd>The nickname chosen by the sender of the message, which can be
diff --git a/spec/Connection.xml b/spec/Connection.xml
index a20d9f2..a3bf83e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -145,45 +145,6 @@ USA.</p>
<tp:added version="0.19.2"/>
</property>
- <method name="InspectHandles" tp:name-for-bindings="Inspect_Handles">
- <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
- <tp:docstring>
- The type of handle to be inspected
- </tp:docstring>
- </arg>
-
- <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
- <tp:docstring>
- An array of integer handles of this type
- </tp:docstring>
- </arg>
-
- <arg direction="out" type="as" name="Identifiers">
- <tp:docstring>
- An array of identifiers corresponding to the given handles, in the same order.
- </tp:docstring>
- </arg>
-
- <tp:docstring>
- Return a string representation for a number of handles of a given
- type.
- </tp:docstring>
-
- <tp:possible-errors>
- <tp:error name="im.telepathy1.Error.Disconnected"/>
- <tp:error name="im.telepathy1.Error.InvalidArgument">
- <tp:docstring>
- The handle type is invalid
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy1.Error.InvalidHandle">
- <tp:docstring>
- One of the given handles is not valid
- </tp:docstring>
- </tp:error>
- </tp:possible-errors>
- </method>
-
<tp:enum name="Handle_Type" type="u">
<tp:enumvalue suffix="None" value="0">
<tp:docstring>
@@ -586,8 +547,8 @@ USA.</p>
<tp:contact-attribute name="contact-id" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same string that would be returned by
- <tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
+ <p>The normalized contact's identifier. Not necessarily the same string
+ as passed to GetContactByID. As a special case,
this is always present in the result of <tp:dbus-ref
namespace="im.telepathy1.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
whether it was explicitly requested or not.</p>
More information about the telepathy-commits
mailing list