[Telepathy] Avatar interface proposal

[Andre Magalhaes]

On 6/8/06, Robert McQueen <robert.mcqueen at collabora.co.uk> wrote:
> Andre Magalhaes wrote:
> > Oops, bug fix release.
> >
> > Added a comment about the missing token, and changed the signal
> > AvatarUpdate token parameter to be a string.
>
> Looks good, doc fixes in the header will make Raphael happy. :)
Done.

> > Can we add this to 0.13.1??? How will we work with this? Who is going
> > to integrate? ...
>
> A patch against the telepathy-spec tree would be easiest for us to merge.
Attached

BR
Andrunko
-------------- next part --------------
diff -rN -u old-telepathy-spec/doc/order new-telepathy-spec/doc/order
--- old-telepathy-spec/doc/order	2006-06-08 13:56:30.000000000 -0300
+++ new-telepathy-spec/doc/order	2006-06-08 13:56:30.000000000 -0300
@@ -1,6 +1,7 @@
 org.freedesktop.Telepathy.ConnectionManager
 org.freedesktop.Telepathy.Connection
 org.freedesktop.Telepathy.Connection.Interface.Aliasing
+org.freedesktop.Telepathy.Connection.Interface.Avatars
 org.freedesktop.Telepathy.Connection.Interface.Capabilities
 org.freedesktop.Telepathy.Connection.Interface.ContactInfo
 org.freedesktop.Telepathy.Connection.Interface.Forwarding
diff -rN -u old-telepathy-spec/telepathy/interfaces.py new-telepathy-spec/telepathy/interfaces.py
--- old-telepathy-spec/telepathy/interfaces.py	2006-06-08 13:56:30.000000000 -0300
+++ new-telepathy-spec/telepathy/interfaces.py	2006-06-08 13:56:30.000000000 -0300
@@ -2,6 +2,7 @@
 #
 # Copyright (C) 2005 Collabora Limited
 # Copyright (C) 2005 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
@@ -22,6 +23,7 @@
 CONN_INTERFACE = 'org.freedesktop.Telepathy.Connection'
 
 CONN_INTERFACE_ALIASING = 'org.freedesktop.Telepathy.Connection.Interface.Aliasing'
+CONN_INTERFACE_AVATARS = 'org.freedesktop.Telepathy.Connection.Interface.Avatars'
 CONN_INTERFACE_CAPABILITIES = 'org.freedesktop.Telepathy.Connection.Interface.Capabilities'
 CONN_INTERFACE_CONTACT_INFO = 'org.freedesktop.Telepathy.Connection.Interface.ContactInfo'
 CONN_INTERFACE_FORWARDING = 'org.freedesktop.Telepathy.Connection.Interface.Forwarding'
diff -rN -u old-telepathy-spec/telepathy/server/conn.py new-telepathy-spec/telepathy/server/conn.py
--- old-telepathy-spec/telepathy/server/conn.py	2006-06-08 13:56:30.000000000 -0300
+++ new-telepathy-spec/telepathy/server/conn.py	2006-06-08 13:56:30.000000000 -0300
@@ -2,6 +2,7 @@
 #
 # Copyright (C) 2005 Collabora Limited
 # Copyright (C) 2005 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
@@ -595,6 +596,80 @@
         """
         pass
 
+class ConnectionInterfaceAtatars(dbus.service.Interface):
+    """
+    An interface for requesting contact avatars on a given connection.
+    """
+    def __init__(self):
+        self._interfaces.add(CONN_INTERFACE_AVATARS)
+
+    @dbus.service.method(CONN_INTERFACE_AVATARS, in_signature='au', out_signature='as')
+    def GetAvatarTokens(self, contacts):
+        """
+        Get the avatars unique tokens for the given contacts. These tokens 
+        can be persisted across connections, and should be used by the client
+        to check if the avatars have been updated. 
+        The client should save the tokens when it first launches, and compare the
+        saved tokens with the tokens returned by subsequent calls of 
+        GetAvatarTokens. If some token has changed, the client should save the 
+        new token and call RequestAvatar for the corresponding contact.
+        This is usefull for saving bandwidth and bus traffic.
+
+        Parameters:
+        contacts - an array of the handle representing contacts
+
+        Returns:
+        a dictionary of contact handles to avatar tokens in the same order. 
+        A empty token means that no avatar is set for the corresponding
+        contact.
+        
+        Possible Errors:
+        Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable
+        """
+        pass
+
+    @dbus.service.method(CONN_INTERFACE_AVATARS, in_signature='u', out_signature='ays')
+    def RequestAvatar(self, contact):
+        """
+        Request the avatar for a given contact.
+
+        Parameters:
+        contact - an integer handle for the contact to request the avatar for
+
+        Returns:
+        The avatar image data and the corresponding mimetype.
+
+        Possible Errors:
+        Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable      
+        """
+        pass
+
+    @dbus.service.method(CONN_INTERFACE_AVATARS, in_signature='ays', out_signature='')
+    def SetAvatar(self, avatar, mimetype):
+        """
+        Set the user new avatar image.
+
+        Parameters:
+        avatar - the avatar image data
+        mimetype - the avatar image mimetype
+
+        Possible Errors:
+        Disconnected, NetworkError, InvalidHandle, PermissionDenied, NotAvailable
+        """
+
+    @dbus.service.signal(CONN_INTERFACE_AVATARS, signature='us')
+    def AvatarUpdated(self, contact, new_avatar_token):
+        """
+        Emitted when the avatar for a contact has been updated. Note
+        that this signal will only be emitted when the avatar has changed in
+        the connection lifetime. To request the contact new avatar use 
+        RequestAvatar.
+
+        Parameters:
+        contact - an integer handle for the contact that the avatar has changed
+        new_avatar_token - new avatar unique token
+        """
+        pass
 
 class ConnectionInterfaceCapabilities(dbus.service.Interface):
     """
diff -rN -u old-telepathy-spec/telepathy/server/__init__.py new-telepathy-spec/telepathy/server/__init__.py
--- old-telepathy-spec/telepathy/server/__init__.py	2006-06-08 13:56:30.000000000 -0300
+++ new-telepathy-spec/telepathy/server/__init__.py	2006-06-08 13:56:30.000000000 -0300
@@ -3,6 +3,7 @@
 
 Copyright (C) 2005 Collabora Limited
 Copyright (C) 2005 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