[Telepathy] Avatar interface proposal

[Rob Taylor]

This seems like a good start. ATM I just have a couple of comments, but
I think that we might need some more thought on this, especially in
terms of bus bandwidth usage..

Andre Magalhaes wrote:
> Hi all,
> 
> So lets start the cooperation :).
> After some discussion on #telepathy channel with other developers, i
> came up with a interface for retrieving avatar images. Here is the
> first version of it.
> Please comment on it. I am not sure if the GetAvatar should have a
> avatar_id as a parameter, as it's clearly not necessary.
> 
> 
> org.freedesktop.Telepathy.Connection.Interface.Avatar
> 
>    An interface for requesting a contact avatar on a given
>    connection.
> 
> Methods:
> GetAvatarId (u: contact ) -> u: avatar_id
> 
>        Get the avatar id for a given contact. This id should be used
> to check if
>        the avatar has been updated.

I would say:
GetAvatarId (u: contact ) -> s: avatar_id

The avatar id should be a unique, or statistically nearly unique
identifier for a given image. It should also be valid over multiple
sessions. e.g. a hash of the image data.

I've made this s: here for enough significant bits ;)

>        Parameters:
>        contact - an integer handle for the contact to request the avatar
> for
> 
>        Returns:
>        SHA1 hash of the avatar image data itself

Unique id. I don't think its necessary to specify the type of hash -
especially as we don't specify the image format ;) ;)


>        Possible Errors:
>        Disconnected, NetworkError, InvalidHandle, PermissionDenied,
> NotAvailable
> 
> GetAvatar ( u: contact, u: avatar_id ) -> s: avatar

this should be
GetAvatar ( u: contact, s: avatar_id ) -> ab: avatar


>        Get the avatar for a given contact.
> 
>        Parameters:
>        contact - an integer handle for the contact to request the avatar
> for
>        avatar_id - SHA1 hash of the avatar image data itself

see above.

>        Returns:
>        A Base64 encoded avatar image


The image *does not* have to be base64 encoded, you can send binary
blobs over DBus as an array of bytes. base64 encoding just wastes time,
memory and power ;)

The format of the image needs to be specified - is this raw 32bit rbga?,
jpg, png? or do we actually want to put a mimetype in there? The answer
to this isn't obvious to me.


>        Possible Errors:
>        Disconnected, NetworkError, InvalidHandle, PermissionDenied,
> NotAvailable
> 
> Signals:
> AvatarUpdated ( u: contact, u: new_avatar_id )

s:new_avatar_id.

>        Emitted when the avatar for the user has been updated. Note
> that this signal will only be emitted when the avatar has changed in
> the Connection lifetime. To user the contact new avatar use GetAvatar
> with the new avatar id as argument.
> 
>        Parameters:
>        contact - an integer handle of the contact ID on the server
>        new_avatar_id - SHA1 hash of the new avatar image data itself

Again, see above


Thanks,
Rob Taylor