Программный интерфейс приложения для плагинов The Bat! общего назначения (CP API)

Внимание: Данный перевод не является официальным!

1. Общие замечания

Начиная с версии 2 в The Bat! была введена возможность расширения функциональности за счёт дополнительных подключаемых модулей (плагинов). Данный документ описывает основные принципы использования подобных модулей, а также то, какая функциональность может/должна быть в них реализована.

2. Подключаемые модули (плагины)

Подключаемый модуль для The Bat! является 32-разрядной библиотекой динамической компоновки (DLL). Стандартное расширение файла для плагинов общего назначения это .TBP (TBP расшифровывается как The Bat Plugin – плагин для The Bat). Ниже приведён список функций, которые могут быть реализованы в подключаемом модуле (имена функций чувствительны к регистру):

• TBP_Initialize
• TBP_Finalize
• TBP_GetName
• TBP_GetVersion
• TBP_GetStatus
• TBP_GetInfo
• TBP_NeedConfig
• TBP_Setup
• TBP_SetConfigData
• TBP_GetConfigData
• TBP_NeedCOM
• TBP_GetSpamScore
• TBP_FeedSpam
• TBP_GetMacroList
• TBP_ExecMacro

В минимальной реализации плагина должны быть реализованы следующие функции:

• TBP_GetName
• TBP_GetStatus

3. Соглашения по программированию

3.1. Модель вызова

Функции плагина должны быть реализованы с использованием стандартной модели вызова Win32 API, определяемой как WINAPI в языке С и stdcallв языке Object Pascal

3.2. Безопасность многозадачности

Любая функция плагина может быть вызвана одновременно из разных потоков, поэтому все функции должны поддерживать многопоточный режим и обеспечивать надлежащий уровень защиты внутренних данных. Если автор плагина не желает поддерживать полноценную многозадачность, простейшим выходом в этой ситуации может быть использование критических секций (EnterCriticalSection в начале функции и LeaveCriticalSection в конце, убедитесь, что критическая секция инициализируется в точке входа DLL или в функции TBP_Initialize, и что код между EnterCriticalSection и LeaveCriticalSection защищён от исключений)

3.3. Строки, завершающиеся нулевым символом

Если это не оговорено особо, длина строковых буферов НЕ ДОЛЖНА включать завершающий нулевой символ, а также этот символ НЕ ДОЛЖЕН добавляться при передаче любых строковых данных от плагинов.

3.4. Контроль «переполнения буфера»

В целях безопасности настоятельно рекомендуется не использовать локальные массивы переменных и буферы для извлечения данных из объектов, предоставляемых The Bat! Память под все буферы, передаваемые функциям плагина выделяется динамически, но всё же настоятельно рекомендуется обратить особое внимание на проблему «переполнения буфера», чтобы данные программы были в безопасности.

4. Языки программирования

Для создания подключаемых модулей может быть использован любой язык программирования, который может быть использован для создания модулей Win32 DLL, удовлетворяющий соглашениям об именах, моделях вызова и многозадачной безопасности, определяемым в данном документе.

В этом документе находятся определения функций на языках C и Object Pascal

5. Функции

5.1. Функции общего назначения.

Функции, описанные в этом разделе являются общими для всех типов плагинов. Они используются для передачи общей информации о плагине и обеспечивают надлежащий способ инициализации, завершения и конфигурирования плагина.

5.1.1. TBP_Initialize

Синтаксис:

Описание:

Данная функция вызывается для инициализации плагина. В процессе работы The Bat! она вызывается лишь однажды, сразу же после загрузки подключаемого модуля. Используйте TBP_Initialize для инициализации внутренних данных, необходимых для нормальной работы плагина.

Возвращаемые значения:

Нет. Если во время вызова TBP_Initialize возникает ошибка, критическая для дальнейшей работы плагина, то функция TBP_GetStatus должна вернуть код ошибки.

5.1.2. TBP_Finalize

Синтаксис:

Описание:

Данная функция вызывается один раз, перед тем, как плагин выгружается из памяти. Используйте TBP_Finalize для освобождения памяти, удаления временных файлов и т.д.

Возвращаемые значения:

Нет.

5.1.3. TBP_GetName

Синтаксис:

Описание:

Данная функция вызывается, чтобы получить имя плагина.

Параметры:

Возвращаемые значения:

5.1.4. TBP_GetVersion

Синтаксис:

Описание:

Данная функция вызывается, чтобы получить имя версии плагина. Одобряется возвращать в этой функции любую значимую информацию о текущем состоянии плагина вдобавок к имени версии.

Параметры:

Возвращаемые значения:

5.1.5. TBP_GetStatus

Синтаксис:

Описание:

Данная фуркция вызывается, чтобы определить, что плагин функционирует должным образом.

Возвращаемые значения:

5.1.6. TBP_GetInfo

Синтаксис:

Описание:

Данная функция вызывается, чтобы получить дополнительную информацию о плагине. Эта информация будет отображена когда пользователь нажмёт кнопку «Информация» в окне настройки плагинов.

Замечание: Если текст с информацией начинается тэгом <HTML>, он будет отображён как документ HTML.

Параметры:

Возвращаемые значения:

5.1.7. TBP_NeedConfig

Синтаксис:

Описание:

Данная функция вызывается, чтобы определить, может ли плагин быть настроен из The Bat! Пользователь может настроить плагин, нажав на кнопку «Настроить» в окне настройки плагинов.

Возвращаемые значения:

5.1.8. TBP_Setup

Синтаксис:

Описание:

Данная функция может быть вызвана для настройки плагина из окна настройки The Bat! через нажатие кнопки «Настроить», или сразу же после установки плагина. TBP_Setup может быть вызвана The Bat! только в том случае, если TBP_ConfigNeeded вернула нулевой результат. Хэндл вызывающего окна может быть получен при помощи функции Win32 API GetActiveWindow.

Возвращаемые значения:

5.1.9. TBP_SetConfigData

Синтаксис:

Описание:

Данная функция используется для передачи плагину данных о конфигурации из файла конфигурации плагинов.

Никаких специальных требований к формату конфигурационных данных нет; они трактуются как двоичные данные и могут содержать любые символы.

Функция TBP_SetConfigData вызывается после загрузки и инициализации плагина во время запуска программы.

Параметры:

Возвращаемые значения:

5.1.10. TBP_GetConfigData

Синтаксис:

Описание:

Данная функция используется для получения данных о конфигурации плагина после того, как он был настроен при помощи функции TBP_Setup, с целью соранить эти данные в файле конфигурации плагинов.

Никаких специальных требований к формату конфигурационных данных нет; они трактуются как двоичные данные и могут содержать любые символы.

Функция TBP_GetConfigData вызывается в том случае, если функция TBP_Setup вернула нулевое значение.

Параметры:

Возвращаемые значения:

5.1.11. TBP_NeedCOM

Синтаксис:

Описание:

Данная функция вызывается, чтобы запросить плагин о необходимости инициализировать подсистему COM, т.е. о необходимости вызвать функцию CoInitialize перед использованием функций плагина в потоке.

Если в плагине реализованы функции, работающие с интерфейсом ITBPDataProvider, значение, возвращаемое этой функцией игнорируется, поскольку COM будет инициализирован в любом случае.

Возвращаемые значения:

5.2. Анти-спам

Данный раздел содержит информацию об анти-спамовых функциях плагинов.

5.2.1. TBP_GetSpamScore

Синтаксис:

Описание:

Данная функция вычисляет спамовую оценку письма. Функция TBP_GetSpamScore вызывается для каждого плагина непосредственно перед сохранением письма в базу писем после его получения. Общая оценка вычисляется согласно настройкам пользователя. TBP_GetSpamScore должна возвращать оценку, присвоенную плагином письму, по 100-балльной шкале. Нулевая оценка означает, что письмо было расценено как легитимное, 100 баллов присваиваются письмам, которые безусловно являются спамом. Если возвращается отрицательная оценка, The Bat! расценивает это как указание, что письмо не было обработано плагином, и не учитывает эту оценку пои подсчёте итоговой оценки для данного письма (например, если установлено два плагина, и один из них вернул -1 а другой – 80, то средняя оценка будет 80; если оба вернули -1, средняя оценка будет 0)

Функция TBP_GetSpamScore также может быть использована для любой предварительной обработки письма (например, для извлечения некоторых данных из всех входящих писем и сохранения их в базе данных).

Параметры:

Возвращаемые значения:

5.2.2. TBP_FeedSpam

Синтаксис:

Описание:

Данная функция может быть реализована в плагине с целью «обучения» его спамовым и не-спамовым письмам согласно предпочтениям пользователя. Функция TBP_FeedSpam вызывается, когда пользователь выделяет письма и использует команды “Mark as Junk” («Пометить как нежелательное») или “Mark as not Junk” («Пометить как желательное»).

Реализация функции TBP_FeedSpam не является обязательной и зависит от алгоритма, используемого для определения спама.

Плагин должен сохранять собранные данные отдельно от конфигурационных данных, передаваемых функцией TBP_GetConfigData

Параметры:

Возвращаемые значения:

5.2.3. Функция обратного вызова (callback) TBPGetDataProc

Синтаксис:

Описание:

Функция обратного вызова (callback) TBPGetDataProc передаётся как параметр при вызове функций TBP_GetSpamScore и

TBP_FeedSpam для обеспечения доступа к данным обрабатываемого письма.

При помощи этой функции возможно получить практически всю необходимую информацию о письме без необходимости анализировать исходное письмо в «сыром» виде. Данные, возвращаемые этой функцией могут считаться текстовыми (хотя некоторые части могут быть закодированы согласно различным стандартам)

Параметры:

Возвращаемые значения:

5.2.4. Идентификаторы свойств письма

Нижеследующая таблица описывает определённые в настоящий момент идентификаторы частей письма

Другие идентификаторы, которые могут быть использованы плагином (с понятными именами и значениями) таковы:

Примечание: Идентификаторы с именами на «midxC_» используются для получения значений, соответствующих RFC параметрам Content-Type (тип содержимого)

5.3. Пользовательские макросы

Данный раздел содержит описания функций, позволяющих добавить новые макросы в существующий набор макросов шаблонов (найти полный список встроенных макросов можно в справке The Bat!)

5.3.1. TBP_GetMacroList

Синтаксис:

Описание:

Данная функция вызывается с целью получить разделённый символами переноса строки  (CR LF или “\n\r”) список макросов, реализованных в плагине. Этот список используется Шаблонным Процессором The Bat! для нахождения плагинов, реализующих неизвестные макросы. Учтите, что плагины не могут перезаписывать какие-либо встроенные макросы, поэтому перед именованием макроса обязательно следует убедиться, что имена новых макросов не конфликтуют со встроенными.

Имя макроса может состоять из любого количества символов; множество допустимых знаков ограничено Латинскими буквами и десятичными цифрами. Регистр в именах значения не имеет.

Параметры:

Возвращаемые значения:

5.3.2. TBP_ExecMacro

Синтаксис:

Описание:

Данная функция вызывается каждый раз, когда Шаблонный Процессор выполняет макрос, зарегистрированный плагином. Плагин должен выполнить макрос согласно собственным правилам и вернуть либо индекс объекта Шаблона, в котором следует заменить текст, либо отрицательное число, в случае, если макрос заменён пустой строкой.

Параметры:

Возвращаемые значения:

5.3.3. Индекс объектов шаблона

Ниже приведён список индексов, которые могут быть использованы для задания и получения информации для параметра-объекта Template, передаваемого в функцию TBP_ExecMacro. Назначение индексов должно быть понятно из их имён.

Строковые индексы (строковые данные доступны через методы ITBPDataProvider::GetDataByID и ITBPDataProvider::SetDataByID):

Целочисленные и булевые индексы (целочисленные данные доступны через методы ITBPDataProvider::GetIntValue и ITBPDataProvider::SetIntValue). Для булевых данных нулевое значение означает «Ложь», любое ненулевое означает «Истина».

Замечатие по поводу использования метода ITBPDataProvider::SetDataByID: постарайтесь, насколько это возможно, использовать метод ITBPDataProvider::ExecuteMacro для установки стандартных свойств шаблона.

6. Универсальный интерфейс обмена данными ITBPDataProvider

ITBPDataProvider является универсальным интерфейсом для обмена данными и командами между The Bat! и плагинами. Этот интерфейс поддерживается всеми объектами The Bat!, которые доступны либо будут доступны плагинам для упрощения (и тем самым повышения надёжности) связи с плагинами.

Синтаксис:

6.1.  ITBPDataProvider::GetDataByID

Синтаксис:

Описание:

Данная функция предназначена для получения данных от объекта. Каждое читаемое свойство объекта должно быть по крайней мере доступным для чтения при помощи этой функции. Формат получаемых данных определяется типом, возвращаемым методом GetIDType и описанным в разделе 6.5

Параметры:

Возвращаемые значения:

6.2. ITBPDataProvider::SetDataByID

Синтаксис:

Описание:

Данная функция предназначена для назначения данных свойствам объекта. Формат данных, которые могут быть сохранены в свойствах, определяется типом, возвращаемым методом GetIDType

Примечание: некоторые объекты могут предоставлять к своим свойствам доступ только для чтения

Параметры:

Возвращаемые значения:

6.3. ITBPDataProvider::GetIntValue

Синтаксис:

Описание:

Данная функция возвращает целочисленное значение свойства. Даже в том случае, если свойство не является численным, предполагается, что реализация постарается преобразовать необходимые данные в числовой формат. Например, если строковое свойство содержит ‘1001’, результат выполнения GetIntValue с ID-значением этого свойства должен быть 1001. Булевые данные должны быть преобразованы в целочисленные значения согласно общепринятым соглашениям (0 (нуль) означает Ложь, любое не нулевое значение означает Истину)

Параметры:

Возвращаемые значения:

Функция всегда должна возвращать значение, соответствующее запрошенному индексу (ID) свойства. Для несуществующих свойств должен возвращаться 0 (нуль)

6.4. ITBPDataProvider::SetIntValue

Синтаксис:

Описание:

Данная функция предназначена для присваивания 32-битных целочисленных значений заданному свойству объекта.

Примечание: некоторые объекты могут предоставлять к своим свойствам доступ только для чтения

Параметры:

Возвращаемые значения:

6.5. ITBPDataProvider::GetIDType

Синтаксис:

Описание:

Данная функция возвращает идентификатор типа для свойства, заданного параметром ID;

Параметры:

Возвращаемые значения:

Идентификатор типа свойства

Ниже приведён список определённых в настоящий момент типов идентификаторов:

Отрицательное значение                          Свойство ещё не определено

6.6. ITBPDataProvider::ItemCount

Синтаксис:

Описание:

Данная функция возвращает число сохранённых свойств для объекта-списка (такого, как параметр Params в функции TBP_ExecMacro)

Параметры:

Нет

Возвращаемые значения:

Число заданных свойств.

6.7. ITBPDataProvider::ExecuteMacro

Синтаксис:

Описание:

Данная функция предназначена для обеспечения удобного расширенного доступа к возможностям, предоставляемым объектом. Каждый объект, реализующий интерфейс ITBPDataProvider может включать собственный набор макросов, документированных именно для этого объекта.

Ниже приведён список объектов с документированным поведением метода ExecuteMacro:

Параметры:

Возвращаемые значения:

Должны быть отдельно документированы для каждой реализации.