path: root/sunshine
diff options
authorKrzysztof Klinikowski <>2010-05-25 22:29:32 +0200
committerKrzysztof Klinikowski <>2010-05-25 22:29:32 +0200
commitcb04b42c3aa5b8c485eee6e8e9298c0f7807ad76 (patch)
tree39781effed165ae587524d6d3712b316be64f774 /sunshine
parentdf4c6c623e6217bed542f4a345834c2db5845060 (diff)
Updated ContactInfo interface.
Diffstat (limited to 'sunshine')
1 files changed, 54 insertions, 8 deletions
diff --git a/sunshine/ b/sunshine/
index 9872d98..39d2ec7 100644
--- a/sunshine/
+++ b/sunshine/
@@ -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