[Telepathy] Avatar interface proposal

[Andre Magalhaes]

New version. Added method GetAvatarRequirements and fixed some
"Possible Errors" values.

BR,
Andrunko
-------------- next part --------------
diff -rN -u old-telepathy-spec/doc/order new-telepathy-spec/doc/order
--- old-telepathy-spec/doc/order	2006-06-09 11:50:40.000000000 -0300
+++ new-telepathy-spec/doc/order	2006-06-09 11:50:40.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-09 11:50:40.000000000 -0300
+++ new-telepathy-spec/telepathy/interfaces.py	2006-06-09 11:50:40.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-09 11:50:40.000000000 -0300
+++ new-telepathy-spec/telepathy/server/conn.py	2006-06-09 11:50:40.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,92 @@
         """
         pass
 
+class ConnectionInterfaceAvatars(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='', out_signature='asqqqqu')
+    def GetAvatarRequirements(self):
+        """
+        Get the requirements needed to set a new avatar. 
+
+        Returns:
+        An array of supported mimetypes, the minimum and maximum supported 
+        resolutions (width x height) and the maximum supported file size in bytes.
+
+        Possible Errors:
+        Disconnected, NetworkError, PermissionDenied, NotAvailable
+        """
+
+    @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, InvalidArgument, PermissionDenied, NotAvailable
+        """
+
+    @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      
+        """
+
+    @dbus.service.method(CONN_INTERFACE_AVATARS, in_signature='ays', out_signature='')
+    def SetAvatar(self, avatar, mimetype):
+        """
+        Set the user new avatar image. The avatar image should respect the requirements
+        obtained by GetAvatarRequirements.
+
+        Parameters:
+        avatar - the avatar image data
+        mimetype - the avatar image mimetype
+
+        Possible Errors:
+        Disconnected, NetworkError, InvalidArgument, 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-09 11:50:40.000000000 -0300
+++ new-telepathy-spec/telepathy/server/__init__.py	2006-06-09 11:50:40.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