diff options
| author | Vadim Dashevskiy <watcherhd@gmail.com> | 2012-07-05 12:16:42 +0000 |
|---|---|---|
| committer | Vadim Dashevskiy <watcherhd@gmail.com> | 2012-07-05 12:16:42 +0000 |
| commit | c78cb0fb36db5ac84fdc6f012074a6c1cea68b1e (patch) | |
| tree | 268188343e6825e5e6cd685a97fe8664034fc72c /plugins/AVS/docs/README | |
| parent | fd5bbf93523a1168559d002757ae977a25ada405 (diff) | |
AVS: folder structure change
git-svn-id: http://svn.miranda-ng.org/main/trunk@769 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c
Diffstat (limited to 'plugins/AVS/docs/README')
| -rw-r--r-- | plugins/AVS/docs/README | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/plugins/AVS/docs/README b/plugins/AVS/docs/README new file mode 100644 index 0000000000..d82d1d7fec --- /dev/null +++ b/plugins/AVS/docs/README @@ -0,0 +1,94 @@ +
+ Load avatars 0.0.1.0
+ --------------------
+
+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.
+
+What it does?
+-------------
+
+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".
+
+
+The included clist_nicer_plus.dll is a demonstration of how the avatar
+service works and can be used by developers. Having a central instance
+which maintains avatars saves resources and increases performance.
+
+
+// example, how to use it (FOR DEVS only)
+
+#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;
+ ...
+ ...
+}
+
+
+TODO: maybe more intelligent cache managment, including auto-expire of avatars which
+ have not been used for a while.
+
+
+Copyright and license:
+----------------------
+
+This plugin is released under the terms of the GNU general public license V2 or any later
+version.
+
+Written, 2005 by Nightwish, silvercircle@gmail.com
|