[Telepathy] improvements to avatar and aliasing interfaces

[Dafydd Harries]

Ar 18/05/2007 am 16:37, ysgrifennodd Dafydd Harries:
> Ar 08/05/2007 am 18:20, ysgrifennodd Dafydd Harries:
> > Our preferred solution is as follows: add a method similar to RequestAvatar,
> > but that returns immediately, and causes a signal to be emitted with the
> > avatar data at a later point. Drawbacks: might wake up clients that already
> > have the avatar contained in the signal. This can be mitigated by
> > disconnecting from the signal when you don't have any avatar requests pending.
> 
> There doesn't seem to be much objection to taking this approach, so I think
> we'll go for this:
> 
>  method RequestAvatars (au: contacts) -> ()
>  signal AvatarReceived (u: contact, s: type, s: token, ay: avatar)

Here's a patch to the spec that does almost exactly this, except:

 - AvatarReceived -> AvatarRetrieved
 - moved type argument to the end of AvatarRetrieved signal, in order to more
   closely mirror RequestAvatar's return type

diff -rN -up old-telepathy-spec/spec/Connection_Interface_Avatars.xml new-telepathy-spec/spec/Connection_Interface_Avatars.xml
--- old-telepathy-spec/spec/Connection_Interface_Avatars.xml	2007-05-23 17:54:48.000000000 +0100
+++ new-telepathy-spec/spec/Connection_Interface_Avatars.xml	2007-05-23 17:54:49.000000000 +0100
@@ -38,6 +38,32 @@ Foundation, Inc., 51 Franklin Street, Fi
         avatar should be requested with RequestAvatar.
       </tp:docstring>
     </signal>
+    <signal name="AvatarRetrieved">
+      <arg name="contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The contact whose avatar has been retrieved
+        </tp:docstring>
+      </arg>
+      <arg name="token" type="s">
+        <tp:docstring>
+          The token corresponding to the avatar
+        </tp:docstring>
+      </arg>
+      <arg name="avatar" type="ay">
+        <tp:docstring>
+          An array of bytes containing the image data
+        </tp:docstring>
+      </arg>
+      <arg name="type" type="s">
+        <tp:docstring>
+          A string containing the image MIME type (eg image/jpeg), or empty if
+          unknown
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Emitted when the avatar for a contact has been retrieved.
+      </tp:docstring>
+    </signal>
     <method name="GetAvatarRequirements">
       <arg direction="out" type="as">
         <tp:docstring>
@@ -133,6 +159,19 @@ Foundation, Inc., 51 Franklin Street, Fi
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
+    <method name="RequestAvatars">
+      <arg direction="in" name="contacts" type="au"
+        tp:type="Contact_Handle[]">
+        <tp:docstring>
+          The contacts to retrieve avatars for
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Request avatars for a number of contacts. The AvatarRetrieved signal
+        is emitted for each avatar retrieved. If retrieving an avatar fails,
+        the AvatarRetrieved signal is not emitted.
+      </tp:docstring>
+    </method>
     <method name="SetAvatar">
       <arg direction="in" name="avatar" type="ay">
         <tp:docstring>

-- 
Dafydd