HowtoUseGrabbers

This page describes how an application can use the Xmltv grabbers. The techniques described here requires Xmltv version 0.5.43 or later.

Find available grabbers

The first step an application shall perform is to find out which grabbers the user has installed on his system. This can be done with tv_find_grabbers:

$ > tv_find_grabbers baseline manualconfig
/usr/bin/tv_grab_au|Australia
/usr/bin/tv_grab_be|Belgium
/usr/bin/tv_grab_br|Brazil
/usr/bin/tv_grab_ch|Switzerland
...

It returns a list of all the grabbers that are installed on the system and support the baseline and manualconfig capabilities. By looking for grabbers that support these capabilities, you can be sure that the grabbers will support a common set of command-line parameters and that all the returned grabbers will behave in the same way. See XmltvCapabilities for a description of these capabilities.

Present the list of grabbers to the user (preferably using the description after the vertical bar for each grabber) and let the user select one of the grabbers.

Configure the grabber

Before a grabber can download data, it needs to be configured. This can be done by using the --configure command-line option. Currently, the --configure option communicates with the user using STDIN and STDOUT. The --config-file parameter can be used to tell the grabber where the configuration shall be written. It is recommended that you always use this parameter.

$ > tv_grab_au --configure --config-file /home/myuser/.myapp/tv_grab_au.conf
...

Download data

After the grabber has been configured, you can download data. The --days X parameter allows you to specify how many days of data you want.

$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --days 5 --quiet

It is also possible to specify if you want the days of data to start with another day. Note that many grabbers are more efficient when they are run like above instead of

$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --offset 1 --days 1 --quiet
$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --offset 2 --days 1 --quiet
$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --offset 3 --days 1 --quiet
$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --offset 4 --days 1 --quiet
$ > tv_grab_au --config-file /home/myuser/.myapp/tv_grab_au.conf --offset 5 --days 1 --quiet

even though both methods should return the same set of programs without listing the same program twice.

When downloading data, a grabber that implements the baseline capability properly will return data on STDOUT (or in a file if the --output parameter is used) and it will print any error-messages or warnings to STDERR. The --quiet parameter tells the grabber to only print warnings and errors to STDERR and not any progress information. The data returned by the grabber is in the format described on the XMLTVFormat page.

HowtoUseGrabbers

Contents