Разработчикам дополнений для CDI

<<Назад|Страница дополнений|Парк тем|Доска предложений

Руководство разработчика дополнений к CDI

Здесь не так много написано как кажется!
Мещанинов Н.

Содержание

Управляющий дополнениями (PluginMngr.dll)
Структура дополнения
Классы дополнений
Коды ошибок

Сопутствующие файлы

PluginMngr.dll

Интерфейс взаимодействия дополнения и основной программы осуществляется посредством управляющего дополнениями: библиотеки - PluginMngr.dll, - которая определяет класс дополнения и является связующим звеном между приложением и библиотекой. В этом управляющем реализованы следующие функции:

function mngrGetPluginInfo(dllname:string;var plinfo:TPluginInfo):integer;stdcall;

Эта функция позволяет CDI узнать о классе дополнения (какие они бывают читайте ниже). Для этого опрашиваемая библиотека заполняет структуру TPluginInfo

type
TPlugInInfo=record //информация для плугина
     PluginClass:integer; //класс дополнения
     PluginName:string[40]; //имя дополнения
     Editable:boolean; //не используется
     PluginInfo:string[255]; // краткое описание
end;

Классы дополнений могут быть следующими:


const
   NSFT_ASCIIDRAWER=$C0BACA;
   NSFT_EMPTY=$BA0BAB;
   NSFT_DRAW_ONCE=$EDA111;
   NSFT_HAS_CONFIG_FORM=$DA0515;
   NSFT_POLYMORPHIC=NSFT_DRAW_ONCE and NSFT_ASCIIDRAWER;

О специфике каждого из классов несколько ниже.
После того, как управляющий передал информацию о доступных дополнения, CDI сможет использовать любой из них, вызвав функцию ExecuteDrawPlugin, находящуюся также в PluginMngr.dll. Эта функция описана следующим образом:

function  ExecuteDrawPlugin(DllFile:string;SettingsFile:String;var param:plParamASCIIDRW):LongInt;stdcall;

где

`DllFile`	- полный путь к библиотеке дополнения
`SettingsFile`	- путь к файлу настроек `settings.forme`
`param`	- структура типа `plParamASCIIDRW` - параметры дополнения.

Если дополнение было корректно вызвано и не обнаружило при своем выполнении никаких ошибок, то эта функция возвращает код ERROR_SUCCESS, в противном случае - код ошибки (специфические ошибки имеют отрицательный номер и начинаются с -2, об этом ниже).

Структура дополнения

Любая библиотека должна иметь как минимум две функции: GetPluginInfo,GenerateAsciiBasedBitMap.
GetPluginInfo
Должна быть описана следующим образом:

procedure GetPluginInfo(var plgInfo:TPlugInInfo);stdcall;

Возвращает информацию о дополнении, заполняя структуру типа TPluginInfo
Примером такой функции может служить следующий участок кода:

procedure GetPluginInfo(var plgInfo:TPlugInInfo);stdcall;
begin
	//наше дополнение будет полиморфным и будет иметь форму для настроек
  plgInfo.PluginClass:= NSFT_POLYMORPHIC and NSFT_HAS_CONFIG_FORM;
  	//название 
  plgInfo.PluginName:='NSFT ASCII Drawer::Cover enumerator';
  	//краткое описание
  plgInfo.PluginInfo:='Creates covers  which contain number of the album. Use %COUNT%* for creating numerical image or 1*%VALUE% for named covers';
end;

GenerateAsciiBasedBitMap
Должна быть описана следующим образом:

function GenerateAsciiBasedBitMap(w,h:integer;AsciiString:string;Path:string;SettingsFile:String):LongInt;stdcall;

где

w,h - ширина и высота будущей обложки

AsciiString

- строка, посылаемая хостовым приложением (CDI). В этой строчке могут содержаться любые параметры, а также специфические поля-тэги. Для пользователей, давно знакомых с CDI, не секрет, что в его системе значительную роль играют тэги - зарезервированные слова, значение которых изменяется в зависимости от контекста. Не в даваясь в подробности тэговой структуры интерфейса, остановимся на тех из них, которые могут быть использованы для дополнения. Схема использования такая. Когда интерфейс натыкается на регулярное выражение, содержащее тэги, он вычисляет его значение и посылает дополнению уже вычисленную строку. Интерфейс пока умеет понимать следующие тэги:

Тэг	Значение тэга
%COUNT%	Количество альбомов в данной коллекции
%VALUE%	Параметр, по которому создается коллекция с помощью Auto Composer (см. файл справки, раздел процесс создания коллекции). Он может принимать значения Id3v1 тэгов:Artist, Album, Title, Description, Genre, Year.
%SPLIT%	Расстояние в пикселях между изображениями обложек в главном окне. Иногда необходимо в тех случаях, когда дополнение само принимает решение о размерах обложки.
%LABELSPLT%	Высота подписи к обложкам. Как правило, она составляет 10 пикселей, но, возможно, в будущем будет изменяться
%THEMEPATH%	Путь к каталогу, где хранится тема оформления

Path - путь к папке, куда сохранять изображение (для класса NSFT_DRAW_ONCE), либо имя файла изображения (для NSFT_ASCIIDRAWER)

SettingsFile - путь к файлу settings.forme,куда рекомендуется записывать служебную информацию и куда CDI сам пишет параметры каждого плугина, указываемые в его диалоге Configure Plugins

Замечание. Рассмотрим более подробно процесс вычисления регулярного выражения. Пусть регулярное выражение является следующей строкой:

%THEMEPATH%%VALUE%Something else

а коллекция создается в хронологическом порядке (т.е. согласно ID3v1 тэгу Year). Тогда вычисленная строка может принять такой вид:

c:\program files\cdi\nature\*1967*Something else

Из рассмотренного примера видно, что тэги разделяются звездочками (*) и те символы, которые не являются зарезервированными, остаются без изменений.
Каким должно быть содержание строки AsciiString должен решать разработчик дополнения.
Пример исходного текста дополнения можно скачать, щелкнув здесь (!!! переименуйте в zip и распакуйте).

Классы дополнений

Основными являются три класса, (это пока все кроме NSFT_EMPTY - его нельзя использовать, он использовался для отладки).

`NSFT_ASCIIDRAWER`	вызывается для каждого альбома в отдельности. Для дополнений такого класса нужно иметь в виду, что параметр `Path` функции `GenerateAsciiBasedBitMap` будет содержать полное имя файла будущей обложки, которую будет использовать CDI.
`NSFT_DRAW_ONCE`	вызывается только один раз, после создания коллекции. В этом случае, поле `Path` функции `GenerateAsciiBasedBitMap` будет содержать имя папки, в которую нужно будет сгенерировать обложки. Количество обложек можно передавать посредством строки `AsciiString`, которая будет содержать тэг `%COUNT%`.
`NSFT_POLYMORPHIC`	определяет полиморфное дополнение, т.е. такое, что может вести себя и как дополнения первого класса (`NSFT_ASCIIDRAWER`), так и второго (`NSFT_DRAW_ONCE`). Все механизмы определения того, к какому классу CDI отнесет такое дополнения должны быть реализованы внутри самого дополнения. Как правило, полиморфные дополнения меняют свой класс в зависимости от содержимого строки `AsciiString`. Выбор того, каким образом взаимодействовать с дополнением CDI реализует следующим образом. После того, как управляющий дополнениями указал, что используемое дополнение является полиморфным, CDI пытается использовать его как `NSFT_ASCIIDRAWER`. Если посылаемая строка `AsciiString` не соответствует этому классу, то дополнение обязано возвратить код ошибки `NSFT_ERROR_INVALID_HOST_REQUEST`, после чего, CDI запускает дополнения как `NSFT_DRAW_ONCE`. Если же при первой попытке дополнение ни разу не вернуло ошибку `NSFT_ERROR_INVALID_HOST_REQUEST`, то считается, что полиморфное дополнение успешно отработало и более не вызывается. (имеется в виду, как принадлежащее другому классу)
`NSFT_HAS_CONFIG_FORM`	Это не класс дополнения, а его свойство, которое передается вместе с классом (см. пример функции `GetPluginInfo`. ПОСМОТРЕТЬ).Означает, что данная библиотека имеет диалоговое окно, позволяющее изменять специфические настройки. О том как вызывается это окно читайте ниже.

Дополнения, имеющие диалоговые окна

Часто тех параметров, которыми можно управлять с помощью параметра AsciiString не достаточно, да и очень неудобно. Поэтому любое дополнение может иметь свое окно диалога настроек. Так, например, дополнение Covers Enumerator позволяет с помощью окна диалога выбрать шрифт, а также его цвет и цвет фона обложки. Окно диалога вызывается посредством управляющего дополнениями, в котором описана функция mngrShowPluginControl, описанная следующим образом

function mngrShowPluginControl(DllFile:string; SettingFile:String):LongInt;stdcall;

где

`DllFile`	- полный путь к библиотеке дополнения
`SettingsFile`	- путь к файлу настроек `settings.forme`

Если дополнение не имеет диалогового окна (т.е. не установлен флаг NSFT_HAS_CONFIG_FORM), то эта функция возвращает код ошибки NSFT_ERROR_INVALID_HOST_REQUEST. Дополнение, диалоговое окно которого вызывается, должно иметь следующую процедуру ShowPluginControl, заголовок которой должен выглядеть следующим образом

procedure ShowPluginControl(SettingsFile:string);stdcall;

где SettingsFile имеет тот же смысл, что и ранее.

Схематично можно изобразить взаимодействие управляющего дополнениями, CDI и дополнениями следующим образом

Вверху изображена последовательность вызова окна диалога, а внизу (красноватые стрелки) - процесса генерации обложек.

Коды ошибок

`NSFT_ERROR_INVALIDDIM=-2`	Неправильные размеры изображения (<0, слишком маленькие и т.д.)
`NSFT_ERROR_INVALID_HOST_REQUEST=-3`	Неправильный запрос хоста, т.е. CDI. Вызов данного дополнения с указанными параметрами невозможен. Такая ситуация возникает, например, если произведена попытка вызвать окно диалога у дополнения, не имеющего флага `NSFT_HAS_CONFIG_FORM`.
`NSFT_ERROR_INVALID_INTERNAL_CANVAS_OPERATION=-4`	Внутренняя ошибка дополнения, связанная с обработкой или созданием изображения.

О всех ошибках сообщайте Мещанинову Н. лично. Все рекомендации по поводу расширения классов дополнений и тэгов будут рассмотрены по адресу Nick Software.