diff options
-rw-r--r-- | spec/Connection_Interface_Contact_Groups.xml | 128 | ||||
-rw-r--r-- | spec/Connection_Interface_Contact_List.xml | 85 | ||||
-rw-r--r-- | spec/all.xml | 2 |
3 files changed, 132 insertions, 83 deletions
diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml index 856dec178..5282a8272 100644 --- a/spec/Connection_Interface_Contact_Groups.xml +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -18,15 +18,63 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT3"/> - <tp:added version="0.19.6">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/> + <tp:added version="0.21.0">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for connections in which contacts can be placed in user-defined groups.</p> + + <p>The most basic functionality of this interface is to list and monitor + a contact's set of groups. To do this, use the + <tp:member-ref>GroupsChanged</tp:member-ref> signal, and the + <tp:token-ref>groups</tp:token-ref> contact attribute (this should + usually be done by connecting to the GroupsChanged signal, then + calling <tp:dbus-ref + namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref> with this interface + included in the Interfaces argument). Simple user interfaces can + limit themselves to displaying that information, and ignore the rest + of this interface: to ensure that this works, + <tp:member-ref>GroupsChanged</tp:member-ref> is emitted for every + change, even if that change could be inferred from another signal + such as <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> + + <p>Looking at contacts' lists of groups is sufficient to present a + user interface resembling XMPP's data model, in which groups behave + like tags applied to contacts, and so an empty group cannot exist + or is not interesting. However, some protocols model groups as + objects in their own right. User interfaces may either track + the set of groups via the <tp:member-ref>Groups</tp:member-ref> + property and the <tp:member-ref>GroupsCreated</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals, or ignore + this extra information.</p> + + <p>Similarly, in some protocols it is possible to rename a group as + a single atomic operation. Simpler user interfaces will + see the new name being created, the old name being removed, and the + members moving to the new name, via the signals described above. + More advanced user interfaces can optionally distinguish between an + atomic rename and a create/remove pair, and display renamed groups + differently, by monitoring the + <tp:member-ref>GroupRenamed</tp:member-ref> signal.</p> + + <p>This interface also provides various methods to manipulate + user-defined groups, which can be expected to work if + <tp:member-ref>GroupStorage</tp:member-ref> is not None.</p> + + <p>Depending on the protocol, some methods might be implemented by + more than one protocol operation; for instance, in a + "contact-centric" protocol like XMPP, + <tp:member-ref>SetContactGroups</tp:member-ref> is a single + protocol operation and <tp:member-ref>SetGroupMembers</tp:member-ref> + requires a protocol operation per contact, whereas in a more + "group-centric" protocol it might be the other way around. User + interfaces SHOULD call whichever method most closely resembles the + way in which the user's action was represented in the UI, and + let the connection manager deal with the details.</p> </tp:docstring> <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups" @@ -65,6 +113,26 @@ </tp:docstring> </tp:contact-attribute> + <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed"> + <tp:docstring> + Emitted when contacts' groups change. + </tp:docstring> + + <arg name="Contact" type="au" tp:type="Contact_Handle"> + <tp:docstring>The relevant contacts.</tp:docstring> + </arg> + + <arg name="Added" type="as"> + <tp:docstring>The names of groups to which the contacts were + added.</tp:docstring> + </arg> + + <arg name="Removed" type="as"> + <tp:docstring>The names of groups from which the contacts were + removed.</tp:docstring> + </arg> + </signal> + <property name="Groups" type="as" access="read" tp:name-for-bindings="Groups"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -80,7 +148,7 @@ receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p> <p>This property's value is not meaningful until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> has become Success.</p> </tp:docstring> </property> @@ -99,7 +167,9 @@ <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a group is renamed.</p> + <p>Emitted when a group is renamed, in protocols where this can + be distinguished from group creation, removal and membership + changes.</p> <p>Immediately after this signal is emitted, <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the @@ -110,7 +180,7 @@ <tp:rationale> <p>Emitting these extra signals, in this order, means that clients that are interested in the set of groups that exist (but treat a - rename and a create/remove pair identically) to ignore the + rename and a create/remove pair identically) can ignore the GroupRenamed signal entirely.</p> </tp:rationale> @@ -166,26 +236,6 @@ </arg> </signal> - <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed"> - <tp:docstring> - Emitted when contacts' groups change. - </tp:docstring> - - <arg name="Contact" type="au" tp:type="Contact_Handle"> - <tp:docstring>The relevant contacts.</tp:docstring> - </arg> - - <arg name="Added" type="as"> - <tp:docstring>The names of groups to which the contacts were - added.</tp:docstring> - </arg> - - <arg name="Removed" type="as"> - <tp:docstring>The names of groups from which the contacts were - removed.</tp:docstring> - </arg> - </signal> - <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Add the given contact to the given groups (creating new groups @@ -213,11 +263,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> @@ -274,11 +324,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> @@ -324,11 +374,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> @@ -368,11 +418,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> @@ -414,11 +464,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> @@ -457,11 +507,11 @@ this method call MUST be emitted before the method returns.</p> <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >ContactListState</tp:dbus-ref> changes to Success. If the ContactListState is Failure, this method SHOULD raise the same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3" + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" >GetContactListAttributes</tp:dbus-ref>.</p> </tp:docstring> diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index 3366b57e2..d602c19f1 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -18,10 +18,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT3" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.19.12">(draft 3)</tp:added> + <tp:added version="0.21.0">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for connections that have any concept of a list of @@ -35,7 +34,7 @@ <p>In some protocols (like link-local XMPP), while there might not be any server or roster, it's possible to list "nearby" contacts.</p> - <p>In Telepathy 0.18 and older, we represented contact lists as a + <p>In Telepathy 0.20 and older, we represented contact lists as a collection of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" >ContactList</tp:dbus-ref> channels. This is remarkably difficult to @@ -100,7 +99,6 @@ <property name="ContactListState" tp:name-for-bindings="Contact_List_State" type="u" tp:type="Contact_List_State" access="read"> - <tp:added version="0.19.12">(in draft 3)</tp:added> <tp:docstring> The progress made in retrieving the contact list. Change notification is via @@ -110,7 +108,6 @@ <signal name="ContactListStateChanged" tp:name-for-bindings="Contact_List_State_Changed"> - <tp:added version="0.19.12">(in draft 3)</tp:added> <tp:docstring> Emitted when <tp:member-ref>ContactListState</tp:member-ref> changes. @@ -125,8 +122,6 @@ <method name="GetContactListAttributes" tp:name-for-bindings="Get_Contact_List_Attributes"> - <tp:changed version="0.19.12">(semantics changed in draft - 3)</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Return some contact attributes for a list of contacts associated with the user. This list MUST include at least:</p> @@ -384,7 +379,6 @@ <property name="ContactListPersists" tp:name-for-bindings="Contact_List_Persists" type="b" access="read"> - <tp:changed version="0.19.12">(renamed in draft 3)</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.</p> @@ -439,10 +433,45 @@ </property> <tp:enum name="Contact_Metadata_Storage_Type" type="u"> - <tp:docstring> - Values of this enumeration indicate the extent to which metadata - such as aliases and group memberships can be stored for the contacts - on a particular connection. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection.</p> + + <p>On some protocols, certain metadata (for instance, contact aliases) + can only be stored for contacts on the contact list, or contacts + with a particular contact list state.</p> + + <p>To make it easier to deal with such protocols, if clients set + metadata on a contact who is not in the required state, the + Connection MUST cache the metadata for the duration of the session. + If clients request the attributes of that contact after the + appropriate "set" method has returned successfully, the Connection + MUST return the new (cached) value.</p> + + <p>If the contact is later placed in the required state to store + metadata (for instance, if subscription to the contact's presence + is requested, on a protocol like MSN where the alias has storage type + Subscribed_Or_Pending), the connection MUST store the cached + metadata at that time.</p> + + <tp:rationale> + <p>If the Connection didn't cache changes in this way, a client + intending to change the alias on MSN would have to wait until + the server acknowledged the subscription request; in the meantime, + other clients would still display the old alias.</p> + </tp:rationale> + + <p>The only exception to that general rule is that if the Connection + cannot store particular metadata at all (i.e. the + storage type is None), it MUST reject attempts to set it.</p> + + <tp:rationale> + <p>If the implementation knows that metadata can't be stored at + all, it's useful to report that, which can be done + synchronously. In general, user interfaces should detect + storage type None and not display editing controls at all.</p> + </tp:rationale> </tp:docstring> <tp:enumvalue suffix="None" value="0"> @@ -471,23 +500,6 @@ <tp:rationale> <p>Contact aliases and groups on MSN have this behaviour.</p> </tp:rationale> - - <p>If this type of metadata is set on a contact with subscribe=No - or subscribe=Rejected, the Connection MUST cache it until - disconnected, and return it if requested. If subscription to the - contact's presence is subsequently requested, making it possible - to store this metadata, the Connection MUST store the cached - value at that time.</p> - - <tp:rationale> - <p>This supports the recommended calling pattern for adding a - new contact, in which alias and groups are set (without - necessarily waiting for a reply) before requesting the - contact's presence. Until the subscription request is - processed by the server, the alias and groups will be cached - in memory; when the subscription request has been processed, - the connection manager will store the metadata on the server.</p> - </tp:rationale> </tp:docstring> </tp:enumvalue> @@ -500,19 +512,6 @@ <p>No service with this behaviour is currently known, but it's a stricter form of Subscribed_Or_Pending.</p> </tp:rationale> - - <p>If this type of metadata is set on a contact with subscribe != Yes, - the Connection MUST cache it until disconnected, and return it - if requested. If subscription to the contact's presence is - subsequently allowed, making it possible to store this metadata, - the Connection MUST store the cached value at that time.</p> - - <tp:rationale> - <p>The same rationale applies as for Subscribed_Or_Pending, - except that metadata must be stored until the subscription - request is not only processed by the server, but also allowed - by the remote user.</p> - </tp:rationale> </tp:docstring> </tp:enumvalue> diff --git a/spec/all.xml b/spec/all.xml index 68cd56fc8..96ed5de7d 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.20.1</tp:version> +<tp:version>0.21.0</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> |