View source

==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 {{program|tv_find_grabbers}}:

<pre>
$ > 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
...
</pre>

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 <code>--configure</code> command-line option. Currently, the <code>--configure</code> option communicates with the user using STDIN and STDOUT. The <code>--config-file</code> 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 <code>--days X</code> 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

<pre>
$ > 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
</pre>

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 <code>--output</code> parameter is used) and it will print any error-messages or warnings to STDERR. The <code>--quiet</code> 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.