Attachment 88777 Details for Bug 50093 – [spec next 1/2] Flatten Connection.I.Contacts into Connection

[patch] [spec next 1/2] Flatten Connection.I.Contacts into Connection

0003-Flatten-Connection.I.Contacts-into-Connection.patch (text/plain), 22.81 KB, created by Simon McVittie on 2013-11-06 19:41:27 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-11-06 19:41:27 UTC

Size: 22.81 KB

patch

obsolete

>From 5c196b3447dd24596c5591eb581412a3d8fb2566 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Wed, 6 Nov 2013 18:39:54 +0000
>Subject: [PATCH 3/4] Flatten Connection.I.Contacts into Connection
>
>---
> spec/Connection.xml | 179 +++++++++++++++++++++++-
> spec/Connection_Interface_Addressing1.xml | 5 +-
> spec/Connection_Interface_Contact_List1.xml | 4 +-
> spec/Connection_Interface_Contacts.xml | 203 ----------------------------
> spec/Connection_Interface_Resources1.xml | 4 +-
> spec/Protocol.xml | 2 +-
> spec/all.xml | 1 -
> 7 files changed, 181 insertions(+), 217 deletions(-)
> delete mode 100644 spec/Connection_Interface_Contacts.xml
>
>diff --git a/spec/Connection.xml b/spec/Connection.xml
>index 51a2ca7..1af4786 100644
>--- a/spec/Connection.xml
>+++ b/spec/Connection.xml
>@@ -23,7 +23,6 @@ USA.
> </tp:license>
> <interface name="im.telepathy.v1.Connection">
> <tp:requires interface="im.telepathy.v1.Connection.Interface.Requests"/>
>- <tp:requires interface="im.telepathy.v1.Connection.Interface.Contacts"/>
> 
> <method name="Connect" tp:name-for-bindings="Connect">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>@@ -541,10 +540,10 @@ USA.
> <tp:contact-attribute name="contact-id" type="s">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> The normalized contact's identifier. Not necessarily the same string
>- as passed to <tp:dbus-ref
>- namespace="imt1.Connection.Interface.Contacts">GetContactByID</tp:dbus-ref>.
>- As a special case, this is always present in the result of <tp:dbus-ref
>- namespace="im.telepathy.v1.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
>+ as passed to <tp:member-ref>GetContactByID</tp:member-ref>.
>+ As a special case, this is always present in the result of
>+ <tp:member-ref>GetContactAttributes</tp:member-ref> and
>+ <tp:member-ref>GetContactByID</tp:member-ref>,
> whether it was explicitly requested or not.
> </tp:docstring>
> </tp:contact-attribute>
>@@ -668,6 +667,174 @@ USA.
> </arg>
> </method>
> 
>+ <tp:simple-type name="Contact_Attribute" type="s">
>+ <tp:docstring>
>+ A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
>+ and an identifier for an attribute defined by that interface. The
>+ attribute identifier SHOULD be in lower case.
>+
>+ <tp:rationale>
>+ These aren't D-Bus core Properties, and we want them to look visibly
>+ different.
>+ </tp:rationale>
>+ </tp:docstring>
>+ </tp:simple-type>
>+
>+ <tp:mapping name="Single_Contact_Attributes_Map">
>+ <tp:docstring>
>+ Some of the attributes of a single contact.
>+ </tp:docstring>
>+
>+ <tp:member type="s" tp:type="Contact_Attribute" name="Attribute">
>+ <tp:docstring>
>+ The name of the attribute
>+ </tp:docstring>
>+ </tp:member>
>+
>+ <tp:member type="v" name="Value">
>+ <tp:docstring>
>+ The value of the attribute
>+ </tp:docstring>
>+ </tp:member>
>+ </tp:mapping>
>+
>+ <tp:mapping name="Contact_Attributes_Map">
>+ <tp:docstring>Mapping returned by
>+ <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a
>+ collection of Contacts and their requested attributes.</tp:docstring>
>+
>+ <tp:member type="u" tp:type="Contact_Handle" name="Contact">
>+ <tp:docstring>
>+ A contact
>+ </tp:docstring>
>+ </tp:member>
>+
>+ <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map"
>+ name="Attributes">
>+ <tp:docstring>
>+ Attributes of that contact
>+ </tp:docstring>
>+ </tp:member>
>+ </tp:mapping>
>+
>+ <method name="GetContactAttributes"
>+ tp:name-for-bindings="Get_Contact_Attributes">
>+ <tp:docstring>
>+ Return any number of contact attributes for the given handles.
>+ </tp:docstring>
>+
>+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
>+ <tp:docstring>
>+ An array of handles representing contacts.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="in" name="Interfaces" type="as"
>+ tp:type="DBus_Interface[]">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ A list of strings indicating which D-Bus interfaces the calling
>+ process is interested in. All supported attributes from these
>+ interfaces, whose values can be obtained without additional network
>+ activity, will be in the reply.
>+
>+ Attributes from the interface
>+ <tp:dbus-ref>im.telepathy.v1.Connection</tp:dbus-ref>
>+ are always returned, and need not be requested explicitly.
>+
>+ As well as returning cached information immediately, the
>+ connection MAY start asynchronous requests to obtain better
>+ values for the contact attributes. If better values are later
>+ obtained by this process, they will be indicated with the usual
>+ signals (such as <tp:dbus-ref
>+ namespace="im.telepathy.v1.Connection.Interface.Aliasing1">AliasesChanged</tp:dbus-ref>).
>+
>+ <tp:rationale>
>+ For instance, an XMPP connection manager could download vCards
>+ in response to a request for <tp:dbus-ref
>+ namespace="im.telepathy.v1.Connection.Interface">Aliasing1</tp:dbus-ref>
>+ attributes.
>+ </tp:rationale>
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="out" type="a{ua{sv}}" name="Attributes"
>+ tp:type="Contact_Attributes_Map">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ A dictionary mapping the contact handles to contact attributes.
>+ If any of the requested handles are in fact invalid, they are
>+ simply omitted from this mapping. If contact attributes are not
>+ immediately known, the behaviour is defined by the interface;
>+ the attribute should either be omitted from the result or
>+ replaced with a default value.
>+
>+ Each contact's attributes will always include at least the
>+ identifier that would be obtained by inspecting the handle
>+ (<code>im.telepathy.v1.Connection/contact-id</code>).
>+ </tp:docstring>
>+ </arg>
>+
>+ <tp:possible-errors>
>+ <tp:error name="im.telepathy.v1.Error.Disconnected"/>
>+ </tp:possible-errors>
>+ </method>
>+
>+ <method name="GetContactByID"
>+ tp:name-for-bindings="Get_Contact_By_ID">
>+ <tp:added version="0.27.0"/>
>+ <tp:docstring>
>+ Return any number of contact attributes for the given identifier.
>+ <tp:rationale>
>+ This is for a single identifier to make it simpler to use for the most
>+ common use case. For multiple contacts case,
>+ <tp:member-ref>GetContactAttributes</tp:member-ref> should be used.
>+ </tp:rationale>
>+ </tp:docstring>
>+
>+ <arg direction="in" name="Identifier" type="s">
>+ <tp:docstring>
>+ An identifier representing a contact.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="in" name="Interfaces" type="as"
>+ tp:type="DBus_Interface[]">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ A list of strings indicating which D-Bus interfaces the calling
>+ process is interested in. All supported attributes from these
>+ interfaces, whose values can be obtained without additional network
>+ activity, will be in the reply.
>+ See <tp:member-ref>GetContactAttributes</tp:member-ref> for
>+ details.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="out" name="Handle" type="u" tp:type="Contact_Handle">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The contact's handle
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="out" type="a{sv}" name="Attributes"
>+ tp:type="Single_Contact_Attributes_Map">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ All supported attributes of the contact on
>+ the given interfaces that can be returned without network
>+ round-trips. If contact attributes are not immediately known, the
>+ behaviour is defined by the interface; the attribute should either
>+ be omitted from the result or replaced with a default value.
>+
>+ The contact's attributes will always include at least the
>+ identifier that would be obtained by inspecting the handle
>+ (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).
>+ </tp:docstring>
>+ </arg>
>+
>+ <tp:possible-errors>
>+ <tp:error name="im.telepathy.v1.Error.Disconnected"/>
>+ <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
>+ </tp:possible-errors>
>+ </method>
>+
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> This models a connection to a single user account on a communication
> service. Its basic capability is to provide the facility to request and
>@@ -747,6 +914,8 @@ USA.
> and signals have been removed from this interface including
> anything to do with handle reference counting.</tp:changed>
> 
>+ <tp:changed version="0.99.UNRELEASED">The former Contacts interface
>+ is now part of Connection.</tp:changed>
> </interface>
> </node>
> 
>diff --git a/spec/Connection_Interface_Addressing1.xml b/spec/Connection_Interface_Addressing1.xml
>index 84aacfd..c1e9e79 100644
>--- a/spec/Connection_Interface_Addressing1.xml
>+++ b/spec/Connection_Interface_Addressing1.xml
>@@ -18,7 +18,6 @@
> </tp:license>
> <interface name="im.telepathy.v1.Connection.Interface.Addressing1">
> <tp:requires interface="im.telepathy.v1.Connection"/>
>- <tp:requires interface="im.telepathy.v1.Connection.Interface.Contacts"/>
> <tp:added version="0.25.2">(as stable API)</tp:added>
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> This interface deals with the multiple address types that can
>@@ -71,7 +70,7 @@
> 
> The behavior of this parameter is similar to the same
> parameter in
>- <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.
>+ <tp:dbus-ref namespace="im.telepathy.v1.Connection">GetContactAttributes</tp:dbus-ref>.
> </tp:docstring>
> </arg>
> 
>@@ -140,7 +139,7 @@
> 
> The behavior of this parameter is similar to the same
> parameter in
>- <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.
>+ <tp:dbus-ref namespace="im.telepathy.v1.Connection">GetContactAttributes</tp:dbus-ref>.
> </tp:docstring>
> </arg>
> 
>diff --git a/spec/Connection_Interface_Contact_List1.xml b/spec/Connection_Interface_Contact_List1.xml
>index d70da6c..eff1f15 100644
>--- a/spec/Connection_Interface_Contact_List1.xml
>+++ b/spec/Connection_Interface_Contact_List1.xml
>@@ -164,7 +164,7 @@
> A list of strings indicating which D-Bus interfaces the calling
> process is interested in. Equivalent to the corresponding argument
> to <tp:dbus-ref
>- namespace="im.telepathy.v1.Connection.Interface.Contacts"
>+ namespace="im.telepathy.v1.Connection"
> >GetContactAttributes</tp:dbus-ref>,
> except that if this list does not contain the ContactList
> interface itself, it is treated as though that interface was also
>@@ -177,7 +177,7 @@
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> A dictionary mapping the contact handles to contact attributes,
> equivalent to the result of <tp:dbus-ref
>- namespace="im.telepathy.v1.Connection.Interface.Contacts"
>+ namespace="im.telepathy.v1.Connection"
> >GetContactAttributes</tp:dbus-ref>.
> 
> </tp:docstring>
>diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
>deleted file mode 100644
>index 2a700d0..0000000
>--- a/spec/Connection_Interface_Contacts.xml
>+++ /dev/null
>@@ -1,203 +0,0 @@
>-<?xml version="1.0" ?>
>-<node name="/Connection_Interface_Contacts" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
>- <tp:copyright> Copyright (C) 2005-2008 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">
>- 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.
>-
>- 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.
>-
>- 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.
>- </tp:license>
>- <interface name="im.telepathy.v1.Connection.Interface.Contacts">
>- <tp:requires interface="im.telepathy.v1.Connection"/>
>- <tp:added version="0.17.9"/>
>-
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- This interface allows many attributes of many contacts to be
>- obtained in a single D-Bus round trip.
>-
>- Each contact attribute has an string identifier
>- (<tp:type>Contact_Attribute</tp:type>), which is namespaced
>- by the D-Bus interface which defines it.
>- </tp:docstring>
>-
>- <tp:simple-type name="Contact_Attribute" type="s">
>- <tp:docstring>
>- A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
>- and an identifier for an attribute defined by that interface. The
>- attribute identifier SHOULD be in lower case.
>-
>- <tp:rationale>
>- These aren't D-Bus core Properties, and we want them to look visibly
>- different.
>- </tp:rationale>
>- </tp:docstring>
>- </tp:simple-type>
>-
>- <tp:mapping name="Single_Contact_Attributes_Map">
>- <tp:docstring>
>- Some of the attributes of a single contact.
>- </tp:docstring>
>-
>- <tp:member type="s" tp:type="Contact_Attribute" name="Attribute">
>- <tp:docstring>
>- The name of the attribute
>- </tp:docstring>
>- </tp:member>
>-
>- <tp:member type="v" name="Value">
>- <tp:docstring>
>- The value of the attribute
>- </tp:docstring>
>- </tp:member>
>- </tp:mapping>
>-
>- <tp:mapping name="Contact_Attributes_Map">
>- <tp:docstring>Mapping returned by
>- <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a
>- collection of Contacts and their requested attributes.</tp:docstring>
>-
>- <tp:member type="u" tp:type="Contact_Handle" name="Contact">
>- <tp:docstring>
>- A contact
>- </tp:docstring>
>- </tp:member>
>-
>- <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map"
>- name="Attributes">
>- <tp:docstring>
>- Attributes of that contact
>- </tp:docstring>
>- </tp:member>
>- </tp:mapping>
>-
>- <method name="GetContactAttributes"
>- tp:name-for-bindings="Get_Contact_Attributes">
>- <tp:docstring>
>- Return any number of contact attributes for the given handles.
>- </tp:docstring>
>-
>- <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
>- <tp:docstring>
>- An array of handles representing contacts.
>- </tp:docstring>
>- </arg>
>-
>- <arg direction="in" name="Interfaces" type="as"
>- tp:type="DBus_Interface[]">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- A list of strings indicating which D-Bus interfaces the calling
>- process is interested in. All supported attributes from these
>- interfaces, whose values can be obtained without additional network
>- activity, will be in the reply.
>-
>- Attributes from the interface
>- <tp:dbus-ref>im.telepathy.v1.Connection</tp:dbus-ref>
>- are always returned, and need not be requested explicitly.
>-
>- As well as returning cached information immediately, the
>- connection MAY start asynchronous requests to obtain better
>- values for the contact attributes. If better values are later
>- obtained by this process, they will be indicated with the usual
>- signals (such as <tp:dbus-ref
>- namespace="im.telepathy.v1.Connection.Interface.Aliasing1">AliasesChanged</tp:dbus-ref>).
>-
>- <tp:rationale>
>- For instance, an XMPP connection manager could download vCards
>- in response to a request for <tp:dbus-ref
>- namespace="im.telepathy.v1.Connection.Interface">Aliasing1</tp:dbus-ref>
>- attributes.
>- </tp:rationale>
>- </tp:docstring>
>- </arg>
>-
>- <arg direction="out" type="a{ua{sv}}" name="Attributes"
>- tp:type="Contact_Attributes_Map">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- A dictionary mapping the contact handles to contact attributes.
>- If any of the requested handles are in fact invalid, they are
>- simply omitted from this mapping. If contact attributes are not
>- immediately known, the behaviour is defined by the interface;
>- the attribute should either be omitted from the result or
>- replaced with a default value.
>-
>- Each contact's attributes will always include at least the
>- identifier that would be obtained by inspecting the handle
>- (<code>im.telepathy.v1.Connection/contact-id</code>).
>- </tp:docstring>
>- </arg>
>-
>- <tp:possible-errors>
>- <tp:error name="im.telepathy.v1.Error.Disconnected"/>
>- </tp:possible-errors>
>- </method>
>-
>- <method name="GetContactByID"
>- tp:name-for-bindings="Get_Contact_By_ID">
>- <tp:added version="0.27.0"/>
>- <tp:docstring>
>- Return any number of contact attributes for the given identifier.
>- <tp:rationale>
>- This is for a single identifier to make it simpler to use for the most
>- common use case. For multiple contacts case,
>- <tp:member-ref>GetContactAttributes</tp:member-ref> should be used.
>- </tp:rationale>
>- </tp:docstring>
>-
>- <arg direction="in" name="Identifier" type="s">
>- <tp:docstring>
>- An identifier representing a contact.
>- </tp:docstring>
>- </arg>
>-
>- <arg direction="in" name="Interfaces" type="as"
>- tp:type="DBus_Interface[]">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- A list of strings indicating which D-Bus interfaces the calling
>- process is interested in. All supported attributes from these
>- interfaces, whose values can be obtained without additional network
>- activity, will be in the reply.
>- See <tp:member-ref>GetContactAttributes</tp:member-ref> for
>- details.
>- </tp:docstring>
>- </arg>
>-
>- <arg direction="out" name="Handle" type="u" tp:type="Contact_Handle">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- The contact's handle
>- </tp:docstring>
>- </arg>
>-
>- <arg direction="out" type="a{sv}" name="Attributes"
>- tp:type="Single_Contact_Attributes_Map">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- All supported attributes of the contact on
>- the given interfaces that can be returned without network
>- round-trips. If contact attributes are not immediately known, the
>- behaviour is defined by the interface; the attribute should either
>- be omitted from the result or replaced with a default value.
>-
>- The contact's attributes will always include at least the
>- identifier that would be obtained by inspecting the handle
>- (<code>im.telepathy.v1.Connection/contact-id</code>).
>- </tp:docstring>
>- </arg>
>-
>- <tp:possible-errors>
>- <tp:error name="im.telepathy.v1.Error.Disconnected"/>
>- <tp:error name="im.telepathy.v1.Error.InvalidHandle"/>
>- </tp:possible-errors>
>- </method>
>- </interface>
>-</node>
>-
>diff --git a/spec/Connection_Interface_Resources1.xml b/spec/Connection_Interface_Resources1.xml
>index 170e61f..ad5e4b0 100644
>--- a/spec/Connection_Interface_Resources1.xml
>+++ b/spec/Connection_Interface_Resources1.xml
>@@ -45,8 +45,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> attempts to change this.
> 
> When using this interface, it is a little like using the
>- <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface"
>- >Contacts</tp:dbus-ref> interface, but only resource-specific
>+ <tp:dbus-ref namespace="im.telepathy.v1.Connection"
>+ >GetContactAttributes</tp:dbus-ref> method, but only resource-specific
> attributes are ever returned. The resource-specific contact
> attributes are decided on by the CM, but XMPP's are listed
> below:
>diff --git a/spec/Protocol.xml b/spec/Protocol.xml
>index c77f508..610ecfc 100644
>--- a/spec/Protocol.xml
>+++ b/spec/Protocol.xml
>@@ -373,7 +373,7 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID;im
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> Attempt to normalize the given contact ID. Where possible, this
> SHOULD return the same thing that would be returned by <tp:dbus-ref
>- namespace="imt1.Connection.Interface.Contacts">GetContactByID</tp:dbus-ref>
>+ namespace="imt1.Connection">GetContactByID</tp:dbus-ref>
> on a connected <tp:dbus-ref namespace="im.telepathy.v1"
> >Connection</tp:dbus-ref>.
> 
>diff --git a/spec/all.xml b/spec/all.xml
>index 3f3ad63..f55c262 100644
>--- a/spec/all.xml
>+++ b/spec/all.xml
>@@ -48,7 +48,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> 
> </tp:docstring>
> <xi:include href="Connection.xml"/>
>- <xi:include href="Connection_Interface_Contacts.xml"/>
> <xi:include href="Connection_Interface_Requests.xml"/>
> 
> <tp:section name="Contact list interfaces">
>-- 
>1.8.4.2
>

Actions: View | Splinter Review

Attachments on bug 50093: 88777 | 88778 | 88780 | 88781 | 88782 | 88783 | 88784 | 88785 | 88786 | 88828 | 88829 | 88830 | 88831 | 91666 | 91667 | 91669 | 91670 | 91671 | 91672 | 91673 | 91676 | 91679 | 91680 | 91681 | 91682 | 91683 | 91684 | 91685 | 91686 | 91687

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.