Avatar service

From Miranda NG
Plugin:AVS/en
Jump to navigation Jump to search
Avatar service
No image
Filename AVS.dll
Authors Nightwish, Pescuma
Download links
Stable version: 32-bit, 64-bit
Development version: 32-bit, 64-bit

Loads and manages contact pictures for other plugins.

About

This is a service plugin, which means, it doesn't provide anything useful on its own except for a few service(s) and event(s) which can be used by other plugins. It loads avatars on demand and maintains an internal cache of avatar bitmap handles. It also handles avatar changes transparently and can notify event subscribers about avatar changes.

How it works

The service MS_AV_GETAVATARBITMAP returns a pointer to a cache entry, if an avatar is present for that contact. The service MAY return 0, in which case, there is no valid avatar yet. However, that doesn't mean there isn't ANY avatar, just that the avatar is not yet ready for use. When someone calls the service requesting an avatar, the plugin will try to get the avatar (if possible) and notify all subscribers via a hookable event as soon as the avatar is ready. If the avatar is already in the cache, it simply returns the cached entry.

Whenever an avatar changes, the plugin fires an event, passing the contacts handle in wParam and a data structure with the avatar information in lParam. Plugins which use the bitmap handles returned by MS_AV_GETAVATARBITMAP MUST subscribe to ME_AV_AVATARCHANGED, because the original bitmap handle may become invalid when the avatar changes.

Fetching avatars is done in a separate thread with reasonable delays to avoid getting into troubles with flood protection(s). Avatars are cached "in memory".

How to use it

#include "m_avatars.h"

struct avatarCacheEntry *ace = 0;
HBITMAP hbmAvatar = 0;

ace = (struct avatarCacheEntry *)CallService(MS_AV_GETAVATARBITMAP, (WPARAM)hContact, 0);

/*
   now, check the return value. if it is 0, then the avatar is not yet ready or unavailble
   for that contact. if it was only "not ready", your plugin will be notified by the
   hookable event ME_AV_AVATARCHANGED
   
   if the return value is != 0, then it is a valid bitmap handle. DON'T DESTROY IT IN YOUR CODE
*/


/*
 * event function
 * initialise with:
 * HANDLE hEvent = HookEvent(ME_AV_AVATARCHANGED, AvatarChanged);
 */
 
static int AvatarChanged(WPARAM wParam, LPARAM lParam)
{
        struct avatarCacheEntry *ace = (struct avatarCacheEntry *)lParam;
        HANDLE hContact = (HANDLE)wParam;
        
        if(ace == NULL)
                return 0;
        if(ace->cbSize != sizeof(struct avatarCacheEntry))
                return 0;               // safety check(s)

        HBITMAP hbmAvatar = ace->hbmPic;
        ...
        ...                
}