From f920ef497f3299ae24fe783ce03bdd93b419f764 Mon Sep 17 00:00:00 2001
From: Kirill Volinsky <mataes2007@gmail.com>
Date: Fri, 18 May 2012 22:02:50 +0000
Subject: plugins folders renaming
git-svn-id: http://svn.miranda-ng.org/main/trunk@60 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c
---
plugins/Avs/README | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 94 insertions(+)
create mode 100644 plugins/Avs/README
(limited to 'plugins/Avs/README')
diff --git a/plugins/Avs/README b/plugins/Avs/README
new file mode 100644
index 0000000000..d82d1d7fec
--- /dev/null
+++ b/plugins/Avs/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
--
cgit v1.2.3