Программирование плагинов к The Bat!

English version here >>>

Официальная документация от RitLabs.

Здесь вы можете скачать официальную документацию по плагинам для The Bat!, выпущенную 10 сентября 2003г. компанией RitLabs (RTF-документ на английском языке)

Перевод официальной документации — от меня :)

Находящийся здесь документ является русскоязычным авторским переводом официальной документации по плагинам для The Bat!, выпущенной 10 сентября 2003 г. компанией RitLabs.

Поскольку перевод не является официальным, я посчитал полезным "подчистить" некоторые спорные косметические детали (например, два раздела 5.2.1, случайный алиас TBP_NeedConfig на TBP_ConfigNeeded, и, наконец, путаница с константами в разделе 5.3.3 — эта ошибка была исправлена при содействии RitLabs, но пока ещё не "зафиксировалась" в официальной документации).

Заголовочные файлы для C++

На основании официальной документации был написан заголовочный файл C++ для использования в плагинах. Заметьте, что файл готовился в Visual C++, поэтому, возможно, вам нужно будет адаптировать его под собственные нужды. ВНИМАНИЕ! 21 сентября файл был обновлён — исправлена присутствовавшая там ранее ошибка (которая, в свою очередь, была прямым отображением ошибки в разделе 5.3.3 оф. документации). Если вы скачивали файл ранее, то теперь не забудьте обновить его.

Скачать архив с заголовочными файлами (cpapi.zip). (3кб)

В архиве находятся файлы cpapi.h и cpapi.def. Первый, собственно, является заголовочным. Второй — файл определений экспортируемых функций. Его необходимо включить в проект MS Visual C++, чтобы избежать т.н. "декорации имён" при компиляции плагина.

Простейшие плагины-примеры

Здесь вы можете скачать исходные тексты простейших плагинов, которые вы можете использовать в качестве примера и краткого руководства при написании собственных плагинов.

• TBPtest (Delphi) (3кб)
• TestPlug (C++) (10кб)

Дополнительные "полезности" для разработчиков

Пока "полезность" только одна: система перевода плагинов RITLNG. В настоящий момент система предназначена для разработчиков, пишущих на Visual C++ (Delphi, С++Builder не поддерживаются).

Система перевода предназначена для облегчения локализации (перевода) интерфейса плагинов на другие языки. Работа системы основана на использовании формата .LNG - "родного" для The Bat! формата файлов локализации. Таким образом, перевод плагинов на другие языки и последующая локализация могут осуществляться сторонними переводчиками без участия начального разработчика плагина. Всё, что нужно от разработчика - подключить библиотеку системы перевода к своему плагину.

Система состоит из двух частей. Первая (основная) часть - библиотека, встраиваемая в плагин. Библиотека и хедер-файл для неё находятся в архиве RITLNG, ссылка дана ниже. В библиотеке реализованы 4 основные функции, обеспечивающие инициализацию, перечисление доступных языков, локализацию и заключительное освобождение ресурсов программы. Вторая часть системы - LNGXtractor - небольшая утилита, предназначенная для извлечения языковых ресурсов из уже скомпилированного плагина. По сути эта утилита создаёт исходные файлы, необходимые для перевода и создания .LNG-файла при помощи бесплатного LNGCompiler. Поскольку эта утилита применяется к уже скомпилированному файлу, то эта операция может быть выполнена опять же, переводчиками - без участия разработчика (за исключением случаев, когда конечный файл чем-нибудь сжимается - например, UPX или ASP).

Как подключить систему к своему плагину? Всё, что нужно - включить в проект находящийся в библиотеке хедер-файл, а также подключить саму библиотеку (файл .lib) в опциях компилятора.

В текст своего плагина необходимо внести примерно следующие изменения:

• в заголовке - #include "lng.h"
• в тексте функции TBP_Initialize (или TBP_SetConfigData, если параметры локализации будут храниться средствами API) добавляется вызов функции RITLNG::LNG_OpenRes, которой передаётся полный к языковому .lng-файлу для данного плагина. Если функция вернула "true", то там же вызывается функция RITLNG::LNG_SetLanguage, которой передаётся идентификатор нужного языка (идентификаторы перечислены в хедер-файле.
• в тексте функции TBP_Finalize добавляется вызов функции RITLNG::LNG_Free, которая очищает все использованные структуры памяти перед выходом.

(Посмотрите хедер-файл - он снабжён довольно подробными комментариями!). Подразумевается, что ваш плагин написан грамотно с точки зрения использования ресурсов: а именно, все диалоги, как положено, созданы в редакторе ресурсов Visual Studio (т.е. не "рисуются" программно при помощи неких хитрых процедур), а все строки находятся в строковых ресурсах (т.е. нет строк, "вкодированных" прямо в текст программы, но все возможные строковые сообщения грузятся из ресурсов через LoadString). В оригинальной версии плагин необходимо писать на английском языке (или любом другом, но чтобы как минимум первые 6 букв любой строки в любом ресурсе не содержали кириллицы или символов других (не-латинских) локалей. Это ограничение связано с тем, что при извлечении ресурса его имя включает первые 6 знаков из его содержимого, и если требование не будет выполнено, то LNGCompiler может не открыть впоследствии созданный файл (как следствие - ресурсы не смогут быть переведены). Следует оговорить место, где плагин будет разыскивать файл .lng, или же сделать настройки, позволяющие задать это место явно. Также следует явно оговорить, что плагин создан с использованием системы перевода RITLNG (чтобы переводчикам не пришлось делать "мартышкин труд" - ресурсы извлекаются и переводятся для любой программы, но если она не поддерживает подобную локализацию, то это будет ни к чему).

Что делать переводчикам?

При помощи LNGXtractor, ссылка на который даётся ниже, извлечь из готового плагина требуемые ресурсы. Затем открыть полученные файлы (.lnc и .inc) в LNGCompiler (http://sourceforge.net/projects/lngcompiler/) и перевести на другой языке. Наконец, при помощи того же LNGCompiler создать файл .lng из своего перевода - и подключить его к плагину способом, предусмотренным автором плагина.

Наконец, вот ссылки на библиотеку и средство извлечения ресурсов:

• RITLNG.zip (33кб)
• LNGXtractor.zip (13кб)

Ссылки на плагины для The Bat! различного назначения

• Vampirex (антиспам по ключевым словам с поддержкой регулярных выражений)
• MyMacros (Плагин макросов различного назначения с исходниками)
• Bayes Filter Plugin (Open Source) (антиспам по Байесу)
• BayesIt! (антиспам по Байесу)
• %IP (на самом деле, не знаю, как называется: плугин экспортирует макрос %IP, который возвращяет локальный ip адрес. Может кому пригодиться). Плагин впервые опубликован на форуме http://forum.nobat.ru