Developing Grabbers/Postprocessors

Grabbers

All grabbers for V3 are written in Lua. To get started with lua programming I recommend you read http://www.lua.org/manual/5.0/ and keep http://www.lua.org/pil/index.html handy.

All grabbers are implemented by adding a sub-table to the Grabbers table. Ideally the name of the table should be in the form "Country_Source" e.g "UK_RT" for UK - Radio Times.

The table should have the following members:

1. "Name" - The name of the grabber to be displayed in the interface
2. "Version" - The version of the grabber
3. "Encoding" - The encoding of the data that the grabber will pass to the gui, should be either
   • XGUI.Encoding.UTF8
   • XGUI.Encoding.ISO8859_1
   • XGUI.Encoding.Windows1252
4. "Author" - Your name
5. "InfoURL" - The url of a page containing info about the grabber
6. "SourceURL" - The url of the listing source
7. "Passes" - A table containing the grabbing passes that will be performed during the grab. (see the next post for details)
8. "RefreshChannels"(optional) - A function which is called when the user presses "Refresh Channels" in the gui. this funtion should be in the form:
   • function RefChans(grabber)
9. "Init"(optional) - A function which is called when the program starts, this is where you can add settings to the gui and call any other initialisation funcitons you need. This function should be in the form:
   • function Init(grabber)

All lua files in the scripts directory or sub directories will be loaded when the program starts.

Pass Types

Passes are defined by adding members to the Passes table of your grabber, the first pass is "Pass1", the second is "Pass2" etc. Each pass has a function executed at the start of the pass ("Start"), a function executed for each item in the pass ("Func") and a function executed at the end of each pass ("End"). Each pass also has a Type. The following pass types are currently available:

XGUI.PassTypes.Channel

This pass type expects a function of the form: function ChannelPass(grabber,channel,maxdays) The function is passed the channels in order. channel is the ID of the channel to grab listings for, maxdays is the maximum number of days that your grabber should grab (this will be limited by the program as well this is only present to prevent wasted effort downloading listings that wont be used) The function should return XGUI.OK

XGUI.PassTypes.ChannelTime

This pass type expects a function of the form: function ChannelTimePass(grabber,channel,ctime) This pass type is used to grab listings for a channel between specified times. The following parameters must be defined:

• MaxDays: The maximum number of days the pass should work over
• Interval: The time interval between each step in the pass in minutes

XGUI.PassTypes.Program

This pass type expects a function of the form: function ProgramPass(grabber,program) The function is passed all of the programs that have been found during previous passes. The function should return the modified program. If you return XGUI.OK then the program will be deleted.

XGUI.PassTypes.RestrictedProgram

This pass type uses the same function type as XGUI.PassTypes.Program. This pass type is passed the programs that are within a specified time. The following parameters must be defined:

• StartTime: The hour of the day to start from
• StopTime: The hour of the day to stop at

Example

For example this is the code defining the Radio Times grabber:

local function Pass1Func(grabber,channel,maxdays)
   --grabber code here
   return XGUI.OK
   end

local function Pass1Start(grabber)
   print ("Please note that all data downloaded with this grabber is copyright of the Radio Times website (http://www.radiotimes.com) and the use of the data is restricted to personal use only. Also be aware that this service may not remain free and in future may become a paid-for service")
   --Read setting values
   IgnoreTBA=toboolean(XGUI.GetSetting(grabber,"IgnoreTBA",true))
   UseCache=toboolean(XGUI.GetSetting(grabber,"UseCache",true))
   return XGUI.OK
   end

local function Pass1End(grabber)
   return XGUI.OK
   end
   
local function RefChans(grabber)
   --download channels here
   return XGUI.OK
   end
   
local function Init(grabber)
   --add settings to the gui
   XGUI.AddSetting(grabber,"IgnoreTBA",XGUI.SettingType.Boolean,"true","Ignore TBA Programs")
   XGUI.AddSetting(grabber,"UseCache",XGUI.SettingType.Boolean,"true","Use Cache")
   return XGUI.OK
   end
   
Grabbers.UK_RT={
   Name = "UK - Radio Times",
   Version = "2.21",
   Author = "Alan Birtles",
   InfoURL = "http://www.birtles.org.uk/xmltv",
   SourceURL = "http://www.radiotimes.com",
   Encoding = XGUI.Encoding.Windows1252,
   Passes={
      Pass1={
         Type=XGUI.PassTypes.Channel,
         Func=Pass1Func,
         Start=Pass1Start,
         --End=Pass1End,
         },
      },
   RefreshChannels=RefChans,
   Init=Init,
   }