Разработка плагинов

[nostra]

Personal Video Database и все плагины существующие на данный момент написаны на Delphi. Весь код в этом документе представлен тоже на Delphi, но это не должно составить больших проблем перевести его на C++ или какой-нибудь другой язык.

Для того чтобы Вам было проще начать с созданием плагина, Вы можете загрузить несколько примеров разных типов плагинов. [Загрузить]
Чтобы скомпилировать примеры Вам понадобятся компоненты TntWare Components. Я предоставил одну из последних бесплатных версий этих компонентов для загрузки. [Загрузить]

[nostra]

Константы

Типы плагинов:

    PLUGIN_UNKNOWN = 0; //На практике - не используется
    PLUGIN_GENERAL = 1; //Не используется на данный момент
    PLUGIN_WEBIMPORT = 2; //Плагин импортирует информацию из интеренет
    PLUGIN_GENIMPORT = 3; //Плагин импортирует фильмы из других БД
    PLUGIN_WEBPICIMPORT = 4; //Плагин импортирует постеры из интернет
    PLUGIN_WEBCOVERIMPORT = 5; //Плагин импортирует обложки из интеренет
    PLUGIN_WEBPEOPLEIMPORT = 6; //Плагин импортирует информацию о людях из интернет
    PLUGIN_EXPORT = 7; //Экспорт

Резултаты работы ф-ций:

    PLUGIN_RESPONSE_ERROR = 0; //произошла ошибка
    PLUGIN_RESPONSE_OK = 1; //Всё нормально, не нужны ни какие дальнейшие действия
    PLUGIN_RESPONSE_LIST = 2; //Плагин создал список для выбора пользоватетелем
    PLUGIN_RESPONSE_DOWNLOAD = 3; //Программа должна сделать новый запрос серверу
    PLUGIN_RESPONSE_OKPHOTO = 4; //Используется при импорте информации о людях и сигнализирует, что должна быть загружена фотография

Типы URL-ов (возвращается ф-цией GetURL):

    WEB_URL_NONE = -1; //URL не нужен
    WEB_URL_SEARCH = 0; //NewURL это ссылка для поиска
    WEB_URL_DIRECT = 1; //NewURL это прямая ссылка на фильм

Типы обложек:

    ctFront = 0;
    ctCD = 1;

Типы данных:

    dtMovies = 0;
    dtActors = 1;


Формат XML для передачи данных фильма/персоны:

XML_MOVIE	'movie';
XML_NUMBER	'num';
XML_TITLE	'title';
XML_ORIGTITLE	'origtitle';
XML_AKA	'aka';
XML_YEAR	'year';
XML_GENRE	'genre';
XML_COUNTRY	'country';
XML_STUDIO	'studio';
XML_RELEASE	'release';
XML_MPAA	'mpaa';
XML_LOCATION	'location';
XML_CATEGORY	'category';
XML_TAGLINE	'tagline';
XML_DESCRIPTION	'description';
XML_MEDIACOUNT	'count';
XML_MEDIATYPE	'type';
XML_RATING	'rating';
XML_IMDBRATING	'imdbrating';
XML_OTHERRATING	'orating';
XML_OTHERNAME	'orname';
XML_RIPTYPE	'rip';
XML_DURATION	'length';
XML_LANGUAGES	'langs';
XML_TRANSLATION	'translation';
XML_RESOLUTION	'resolution';
XML_VIDEOCODEC	'videocodec';
XML_VIDEOBITRATE	'videobitrate';
XML_AUDIOCODEC	'audiocodec';
XML_AUDIOBITRATE	'audiobitrate';
XML_SIZE	'size';
XML_URL	'url';
XML_PATH	'path';
XML_COMMENT	'comment';
XML_DATE	'dateadded';
XML_BARCODE	'code';
XML_MEDIALABEL	'label';
XML_LOAN	'loan';
XML_SUBS	'subs';
XML_FRAMERATE	'framerate';
XML_LABEL	'label';
XML_FEATURES	'features';
XML_VIEWED	'viewed';
XML_BOOKMARKED	'bookmark';
XML_WISH	'wish';
XML_EPISODES	'episodes';
XML_SEASON	'season';
XML_EPISODE	'episode';
XML_EPNUM	'epnum';
XML_CUSTOMVALUE	'custom';
XML_CUSTOM	'value';
XML_CUSTOMID	'customid';
XML_LOANDATE	'loandate';
XML_VIEWDATE	'viewdate';
XML_TAGS	'tags';
XML_AWARDS	'awards';
XML_EVENT	'event';
XML_RESULT	'result';
XML_AWARD	'award';
XML_AWARD_CAT	'cat';
XML_LINKS	'links';
XML_ACTORS	'actors';
XML_DIRECTORS	'directors';
XML_PRODUCERS	'producers';
XML_COMPOSERS	'composers';
XML_WRITERS	'writers';
XML_CAREERTYPE	'careertype';
XML_HUMAN	'human';
XML_NAME	'name';
XML_TRANSNAME	'transname';
XML_ALTNAMES	'altnames';
XML_BIRTHDAY	'birthday';
XML_BIRTHPLACE	'birthplace';
XML_BIO	'bio';
XML_FILMOGRAPHY	'filmography';
XML_TYPE	'category';
XML_ROLE	'role';
XML_DEATH	'death';
XML_IMAGES	'images';
XML_IMGTYPE	'imgtype';
XML_IMGPATH	'imgpath';
XML_IMGFORMAT	'imgformat';
XML_IMGDATA	'imgdata';

 

[nostra]

Типы

Типы используемые в импорте фильмов/людей (не из сети):

   TPluginImpGenMovieCallback = function (Movie : PWideChar) : BOOL;
  TPluginImpGenPersonCallback = function (Person : PWideChar) : BOOL;


Типы используемые в экспорте фильмов/людей (не из сети):

   TExpValueCallback = function (ValueIndex : Integer; IsCustomIndex : Boolean) : PWideChar;
  TExpNextCallback = function : BOOL;

[nostra]

Ф-ции общие для всех типов плагинов

function GetType : SHORT; stdcall;

Эта ф-ция должна присутствовать во всех плагинах и возвращать тип плагинов.


function GetName(const LangID : Integer) : PWideChar; stdcall;

    LangID - Выбранный на данный момент язык интерфейса

Эта ф-ция должна присутствовать во всех плагинах и возвращать название плагина.


function GetDescription(const LangID : Integer) : PWideChar; stdcall;

    LangID - Выбранный на данный момент язык интерфейса

Эта ф-ция должна присутствовать во всех плагинах и возвращать описание плагина.


function GetVersionSupported : DWORD; stdcall;

Эта ф-ция должна присутствовать во всех плагинах. Ф-ция должна возвращать минимальную версию Personal Video Database с которой она совместима. 0 - все версии.

Версии должны быть следующего формата:
001005000000 = 1005000 = "1.5.0.0"
000009000000 = 9000000 = "0.9.0.0"


function GetPluginVersion : PCHAR; stdcall;

Возвращает версию плагина. Эта ф-ция не должна обязательно присутствовать.


function CheckPVDVerion(const V : Integer) : BOOL; stdcall;

Эта ф-ция не обязательна. Personal Video Database передаёт версию программы в эту ф-ция. Ф-ция должна возвращать True если плагин совместим с переданой версией и False если нет.


function GetPluginLanguage : Integer; stdcall;

Должна возвращать язык плагина. Если она отсутствует, то предполагается, что язык - Английский.


function GetAbout(const LangID : Integer) : PWideChar; stdcall;

    LangID - Выбранный на данный момент язык интерфейса

Возвращает информацию о плагине. Ф-ция не обязательна.


function CanConfig : BOOL; stdcall;

Эта ф-ция должна возвращать True если плагин имеет настройки и False если нет.


function Configure(const LangID : Integer; AppHandle : HWND; CustomFields : PWideChar) : BOOL; stdcall;

    LangID - Выбранный на данный момент язык интерфейса
    AppHandle - Handle окна программы
    CustomFields - Список названий пользовательских полей (#0 - разделитель, #8#0 - конец списка)

Эта ф-ция вызывается когда пользователь хочет настроить плагин. Возвращайте True если настройка прошла без ошибок.

function BeginWork : Integer; stdcall;

Обязательная ф-ция. Вызывается вначале работы с плагином.

procedure EndWork; stdcall;

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

[nostra]

Импорт из интернет (информация и постеры)



function GetURL(const isEpisode : Boolean; const CurrentURL : PCHAR; out NewURL : PCHAR) : Integer; stdcall;

    isEpisode - Ищет ли пользователь серию или фильм
    CurrentURL - адрес указаный в поле URL фильма
    NewURL - В эту переменную нужно передать новый адрес (для поиска (на пр. "http://imdb.com/find?s=tt&q=%s") или загрузки)

Обязательная ф-ция.


function GetCodePage : Cardinal; stdcall;

Ф-ция должна возвращать номер кодовой страницы нужной для формирования запросов HTTP.


function Parse(URL : PCHAR; Data : PWideChar) : SHORT; stdcall;

    URL - Адрес страницы в интернет
    Data - Ответ веб-сервера (обычно HTML), который должен быть обработан в плагине.

Ф-ция вызывается каждый раз когда Personal Video Database получает веб-страницу от сервера.


function GetResultsCount : Integer; stdcall;

Эта ф-ция вызывается если ф-ция Parse вернула PLUGIN_RESPONSE_LIST ранее. Нужно вернуть размер списка.


function GetSelection(const N : Integer; out Title, Title2 : PWideChar; out URL, Preview, Browse : PCHAR; out Year : Smallint) : BOOL; stdcall;

    N - Номер в списке
    Title, Title2, Year, URL, PreviewURL, BrowseURL - Определяют названия и год (если есть) для выбора и адресса.. PreviewURL используется только если импортируются постеры и имеется предпросмотр.

Ф-ция должна вернуть True, если всё прошло без ошибок и False в противном случае.


function GetMovie(const N : Integer; var AMovieInfo : PWideChar) : BOOL; stdcall;
function GetHuman(const N : Integer; var AHumanInfo : PWideChar) : Integer; stdcall;

    N - Номер фильма/человека в списке

Если пользователь выбрал фильм/человека из списка, то будет вызвана эта ф-ция для полученя данных. Данные должны быть переданы в виде XML. Формат XML описан выше.

Ф-ция должна вернуть True, если всё прошло без ошибок и False в противном случае. (фильмы)
Результат ф-ции PLUGIN_RESPONSE_ERROR .. PLUGIN_RESPONSE_OKPHOTO (люди)


procedure GetLoginInfo(out ScriptURL : PCHAR; out Params : PCHAR); stdcall;

    ScriptURL - Адрес скрипта для логина
    Params - Параметры для скрипта

Нужна только в том случае если нужна авторизация на веб странице.


function GetReferrer : PCHAR;

Имплементируйте эту ф-цию если веб сервис не работает со стандартным Refferer-ом.


function GetSelectTitle(const LangID : Integer) : PWideChar; stdcall;

    LangID - Выбранный на данный момент язык интерфейса

Имплементируйте эту ф-цию если хотите устанавливать текст заголовка окна выбора фильмов.

[nostra]

Плагины импорта данных из другиз баз

function GetFilter(AppHandle : HWND; const LangID : Integer; CustomFields : PWideChar) : PWideChar; stdcall

    AppHandle - Handle окна программы
    LangID - Выбранный на данный момент язык интерфейса
    CustomFields - Список названий пользовательских полей (#0 - разделитель, #8#0 - конец списка)

Ф-ция должна возвращать фильтр для диалога выбора файла для импорта.


procedure Parse(AppHandle : HWND; const LangID : Integer; FileName : PWideChar; MovieCallback : TPluginImpGenMovieCallback; HumanCallback : TPluginImpGenHumanCallback; CustomFields : PWideChar); stdcall;

    AppHandle - Handle окна программы
    LangID - Выбранный на данный момент язык интерфейса
    FileName - Имя файла
    MovieCallback - Callback процедура, которая должна быть вызвана из плагина для добавления фильма в базу.
    HumanCallback - Callback процедура, которая должна быть вызвана из плагина для добавления человека в базу.
    CustomFields - Список названий пользовательских полей (#0 - разделитель, #8#0 - конец списка)

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

[nostra]

Импорт обложек из интернет

function GetURL(const CurrentURL : PCHAR; out NewURL : PCHAR; const ASearchText : PChar) : Integer; stdcall;

То же что и другая одноименной ф-ции для импорта информации, но с дополнительным параметром ASearchText, чтобы можно было подготовить запрос полностью в плагине (если нужно).


function GetCurrentType : SHORT; stdcall;

Возвращает тип обложки (TCoverType) над которой сейчас работает плагин.


procedure SetSelection(const AVal : Integer); stdcall;

Используется программой, чтобы сообщить плагины номер выбранного пользователем фильма из списка.