Programming own plugins

[nostra]

Personal Video Database and all plugins currently included in the installation package are written in Delphi. So, all function declarations here are in Object Pascal. It should be easy, thou, to translate them into C++ or some other language without problems.

Feel free to download some samples of different plugin types. [Download]
To compile the samples you will need TntWare Components. I have uploaded an older version of these components, because the new ones are not free any more. [Download]

[nostra]

Constants

Plugin types:

    PLUGIN_UNKNOWN = 0; //You do not need this one actually
    PLUGIN_GENERAL = 1; //Is not currently used
    PLUGIN_WEBIMPORT = 2; //Plugin is importing information from a web service
    PLUGIN_GENIMPORT = 3; //Plugin is importing information from other type of database
    PLUGIN_WEBPICIMPORT = 4; //Plugin is importing Posters from a web service
    PLUGIN_WEBCOVERIMPORT = 5; //Plugin is importing Cover and Disc images from a web service
    PLUGIN_WEBPEOPLEIMPORT = 6; //Plugin is importing information about people from a web service
    PLUGIN_EXPORT = 7; //Export plugin

Plugin responses:

    PLUGIN_RESPONSE_ERROR = 0; //An error acquired while parsing the result
    PLUGIN_RESPONSE_OK = 1; //Everything ok, nothing more to be done
    PLUGIN_RESPONSE_LIST = 2; //Plugin generated a list which should be read by the program
    PLUGIN_RESPONSE_DOWNLOAD = 3; //The program should request a page from the web
    PLUGIN_RESPONSE_OKPHOTO = 4; //Used in plugins importing info about people and signalizes that the program needs to download a photo

URL types (result of GetURL function):

    WEB_URL_NONE = -1; //There is no need to download anything
    WEB_URL_SEARCH = 0; //NewURL is a link to search movie
    WEB_URL_DIRECT = 1; //NewURL is a direct URL of the movie

Cover types:

    ctFront = 0;
    ctCD = 1;

Data types:

    dtMovies = 0;
    dtActors = 1;

XML Tags used to pass movie/person data from import plugins to the main application:

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]

Types

Types for movie general import plugins:

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

Types for human general export plugins:

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

[nostra]

Common functions for all types of plugins

function GetType : SHORT; stdcall;

This function must be present in all plugins. It should return the type of the plugin.


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

    LangID - Currently selected user interface language

This function must be present in all plugins. It should return a short name of the plugin.


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

    LangID - Currently selected user interface language

This function must be present in all plugins. It should return the description of the plugin.


function GetVersionSupported : DWORD; stdcall;

This function must be present in all plugins. It should return minimum supported Personal Video Database version. Use 0 for all versions.

Version is assumed to be a number like:
001005000000 = 1005000 = "1.5.0.0"
000009000000 = 9000 = "0.9.0.0"


function GetPluginVersion : PCHAR; stdcall;

Returns the version of the plugin. This function is not obligatory and can be absent in the plugin.


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

This function is also not obligatory. If Personal Video Database finds this function it passes it's version to it. The function should return True if the plugin is compatible with the passed version of the program and False otherwise.

   
function GetPluginLanguage : Integer; stdcall;

Returns the language of the plugin. It is useful especially for Web Import plugins to pass the language of the information they are getting from Web. If this function is not present English is assumed.

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

    LangID - Currently selected user interface language

Returns information about the plugin. Not obligatory.

   
function CanConfig : BOOL; stdcall;

This function must return True if the plugin is configurable and False otherwise. If no such function is found in the plugin False is assumed.


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

    LangID - Currently selected user interface language
    AppHandle - Handle of the application window
    CustomFields - List of custom fields (#0 - separator, #8#0 - end of the list)

This function is called when a user wants to configure a plugin. Return True if configuration was successful.

function BeginWork : Integer; stdcall;

Obligatory function. It is called each time the main program starts to work with the plugin.

procedure EndWork; stdcall;

Obligatory function. Called each time the work with the plugin is finished.

[nostra]

Web import plugins (information and posters)

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

    isEpisode - should plugin search for a normal movie or tv episode
    CurrentURL - URLs specified for the movie separated with Space
    NewURL - This variable is used to pass a new URL to the application (to search (for ex. "http://imdb.com/find?s=tt&q=%s") or just download)

This function must be present.

function GetCodePage : Cardinal; stdcall;

This function must return code page need to format HTTP requests.

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

    URL - Address of this page
    Data - Response from the Web service (normally HTML) which should be processed by the plugin.

This function is always called when Personal Video Database gets a web page from the Server.

   
function GetResultsCount : Integer; stdcall;

This function is called when the Parse function returned PLUGIN_RESPONSE_LIST previously to get the count of items in the list.

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

    N - Item in the list that should be copied into the next 3 parameters.
    Title, Title2, Year, URL, PreviewURL, BrowseURL - Data which represents movie or poster. PreviewURL is only used when posters have a preview image.

The function should return True if everything went ok, False otherwise.


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

    N - Number of the movie/human in the list

If user select a movie/human from the list or only one movie/human is in the list this function will be called to get the data.
Movie information should be passed back as XML . The function should return True if everything was ok and False otherwise. (movies)
Result can be PLUGIN_RESPONSE_ERROR .. PLUGIN_RESPONSE_OKPHOTO (people)

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

    ScriptURL - Address of the login script
    Params - Parameters that should be passed to the script

This procedure is only needed if the web service the plugin is working with need such information.

   
function GetReferrer : PCHAR;

Implement this function and return a String with Referrer if the Web service works only wit special one.

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

    LangID - Currently selected user interface language

Implement this function if you want to set a special Selection Window title.

[nostra]

General import plugins

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

    AppHandle - Handle of the application window
    LangID - Currently selected user interface language
    CustomFields - List of custom fields (#0 - separator, #8#0 - end of the list)

This function must return a filter for the File Open Dialog, when selecting a file to import from.


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

    LangID - Currently selected user interface language
    AppHandle - Handle of the application window
    FileName - Name of the file to import from.
    MovieCallback - A callback procedure that should be called from the plugin every time a movie should be added to the database.
    HumanCallback - A callback procedure that should be called from the plugin every time a human should be added to the database.
    CustomFields - List of custom fields (#0 - separator, #8#0 - end of the list)

This procedure must be present in this type of plugins. It is called just after the user selected the file to import from.

[nostra]

Cover and Disc image Plugins

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

The same as for other web import plugins, but with additional parameter ASearchText, so you can prepare the search request in the plugin.

   
function GetCurrentType : SHORT; stdcall;

This function must return the type of cover (TCoverType) plugin is working with at the moment.


procedure SetSelection(const AVal : Integer); stdcall;

When user selects one of the movies from the list the program passes index of selected movie to the plugin using this procedure.