Updated ContactInfo interface.

1 files changed, 54 insertions, 8 deletions

diff --git a/sunshine/Connection_Interface_Contact_Info.py b/sunshine/Connection_Interface_Contact_Info.py
index 9872d98..39d2ec7 100644
--- a/sunshine/Connection_Interface_Contact_Info.py
+++ b/sunshine/Connection_Interface_Contact_Info.py
@@ -29,33 +29,79 @@ class ConnectionInterfaceContactInfo(dbus.service.Interface):
         Contact_Info_Fields forming a
         structured representation of a vCard (as defined by RFC 2426), using
         field names and semantics defined therein.
+
+      On some protocols, information about your contacts is pushed to you,
+        with change notification; on others, like XMPP, the client must
+        explicitly request the avatar, and has no way to tell whether it has
+        changed without retrieving it in its entirety. This distinction is
+        exposed by ContactInfoFlags containing
+        the Push flag.
+
+      On protocols with the Push flag set, UIs can connect to
+        ContactInfoChanged, call
+        GetContactInfo once at login for the set
+        of contacts they are interested in, and then be sure they will receive
+        the latest contact info. On protocols like XMPP, clients can do the
+        same, but will receive (at most) opportunistic updates if the info is
+        retrieved for other reasons. Clients may call
+        RequestContactInfo or
+        RefreshContactInfo to force a contact's
+        info to be updated, but MUST NOT do so unless this is either in
+        response to direct user action, or to refresh their own cache after a
+        number of days.
+
+      
+        We don't want clients to accidentally cause a ridiculous amount of
+          network traffic.
+      
     """
 
     def __init__(self):
-        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT')
+        self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.ContactInfo')
 
-    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT', in_signature='au', out_signature='a{ua(sasas)}')
+    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo', in_signature='au', out_signature='a{ua(sasas)}')
     def GetContactInfo(self, Contacts):
         """
         Request information on several contacts at once.  This SHOULD only
         return cached information, omitting handles for which no information is
-        cached from the returned map.  For contacts without cached information,
-        the information SHOULD be requested from the network, with the result
-        signalled later by ContactInfoChanged.
+        cached from the returned map.
+      
+        """
+        raise NotImplementedError
+  
+    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo', in_signature='au', out_signature='')
+    def RefreshContactInfo(self, Contacts):
+        """
+        Retrieve information for the given contact, requesting it from the
+        network if an up-to-date version is not cached locally. This method
+        SHOULD return immediately, emitting
+        ContactInfoChanged when the contacts'
+        updated contact information is returned.
+
+        
+          This method allows a client with cached contact information to
+          update its cache after a number of days.
+        
       
         """
         raise NotImplementedError
   
-    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT', in_signature='u', out_signature='a(sasas)')
+    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo', in_signature='u', out_signature='a(sasas)')
     def RequestContactInfo(self, Contact):
         """
         Retrieve information for a contact, requesting it from the network if
         it is not cached locally.
+
+        
+          This method is appropriate for an explicit user request to show
+          a contact's information; it allows a UI to wait for the contact
+          info to be returned.
+        
       
         """
         raise NotImplementedError
   
-    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT', in_signature='a(sasas)', out_signature='')
+    @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactInfo', in_signature='a(sasas)', out_signature='')
     def SetContactInfo(self, ContactInfo):
         """
         Set new contact information for this connection, replacing existing
@@ -67,7 +113,7 @@ class ConnectionInterfaceContactInfo(dbus.service.Interface):
         """
         raise NotImplementedError
   
-    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT', signature='ua(sasas)')
+    @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactInfo', signature='ua(sasas)')
     def ContactInfoChanged(self, Contact, ContactInfo):
         """
         Emitted when a contact's information has changed or been received for