From eb47a6f070dbb096cda66e53ce2bf889ef14b2ae Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 6 Nov 2013 18:40:49 +0000 Subject: [PATCH 07/11] [temporary] update spec: fold Contacts into Connection To be replaced with an update to a newer spec. --- 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.

- @@ -541,10 +540,10 @@ USA.

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 GetContactAttributes, + as passed to GetContactByID. + As a special case, this is always present in the result of + GetContactAttributes and + GetContactByID, whether it was explicitly requested or not.

 @@ -668,6 +667,174 @@ USA.

 + + + A DBus_Interface, followed by a slash '/' character + and an identifier for an attribute defined by that interface. The + attribute identifier SHOULD be in lower case. + + + These aren't D-Bus core Properties, and we want them to look visibly + different. + + + + + + + Some of the attributes of a single contact. + + + + + The name of the attribute + + + + + + The value of the attribute + + + + + + Mapping returned by + GetContactAttributes, representing a + collection of Contacts and their requested attributes. + + + + A contact + + + + + + Attributes of that contact + + + + + + + Return any number of contact attributes for the given handles. + + + + + An array of handles representing contacts. + + + + + +

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 + im.telepathy.v1.Connection + 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 AliasesChanged).

+ + + For instance, an XMPP connection manager could download vCards + in response to a request for Aliasing1 + attributes. + + + + + + +

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 + (im.telepathy.v1.Connection/contact-id).

+ + + + + + + + + + + + Return any number of contact attributes for the given identifier. + + This is for a single identifier to make it simpler to use for the most + common use case. For multiple contacts case, + GetContactAttributes should be used. + + + + + + An identifier representing a contact. + + + + + +

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 GetContactAttributes for + details.

+ + + + + +

The contact's handle

+ + + + + +

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 + (org.freedesktop.Telepathy.Connection/contact-id).

+ + + + + + + + +

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. + The former Contacts interface + is now part of Connection. 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 @@ - (as stable API)

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 - Contacts.GetContactAttributes.

+ GetContactAttributes.

 @@ -140,7 +139,7 @@

The behavior of this parameter is similar to the same parameter in - Contacts.GetContactAttributes.

+ GetContactAttributes.

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 GetContactAttributes, 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 @@

A dictionary mapping the contact handles to contact attributes, equivalent to the result of GetContactAttributes.

diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml deleted file mode 100644 index 7471cc6..0000000 --- a/spec/Connection_Interface_Contacts.xml +++ /dev/null @@ -1,203 +0,0 @@ - - - Copyright (C) 2005-2008 Collabora Limited - Copyright (C) 2005, 2006 Nokia Corporation - Copyright (C) 2006 INdT - -

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.

- - - - - - -

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 - (Contact_Attribute), which is namespaced - by the D-Bus interface which defines it.

- - - - - A DBus_Interface, followed by a slash '/' character - and an identifier for an attribute defined by that interface. The - attribute identifier SHOULD be in lower case. - - - These aren't D-Bus core Properties, and we want them to look visibly - different. - - - - - - - Some of the attributes of a single contact. - - - - - The name of the attribute - - - - - - The value of the attribute - - - - - - Mapping returned by - GetContactAttributes, representing a - collection of Contacts and their requested attributes. - - - - A contact - - - - - - Attributes of that contact - - - - - - - Return any number of contact attributes for the given handles. - - - - - An array of handles representing contacts. - - - - - -

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 - im.telepathy.v1.Connection - 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 AliasesChanged).

- - - For instance, an XMPP connection manager could download vCards - in response to a request for Aliasing1 - attributes. - - - - - - -

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 - (im.telepathy.v1.Connection/contact-id).

- - - - - - - - - - - - Return any number of contact attributes for the given identifier. - - This is for a single identifier to make it simpler to use for the most - common use case. For multiple contacts case, - GetContactAttributes should be used. - - - - - - An identifier representing a contact. - - - - - -

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 GetContactAttributes for - details.

- - - - - -

The contact's handle

- - - - - -

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 - (org.freedesktop.Telepathy.Connection/contact-id).

- - - - - - - - - - - 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.

When using this interface, it is a little like using the - Contacts interface, but only resource-specific + GetContactAttributes 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

Attempt to normalize the given contact ID. Where possible, this SHOULD return the same thing that would be returned by GetContactByID + namespace="imt1.Connection">GetContactByID on a connected Connection.

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. - -- 1.8.4.2