This document describes how a PVR application (or any other application that wants to utilize XMLTV data) can interact with the XMLTV grabbers.
Before the grabber can download any data, it must be configured. This can be done in two different ways depending on which capabilities the grabber supports. It is possible to detect which capabilities a grabber supports by using the --capabilities option. See XmltvCapabilities.
Grabbers that support apiconfig
If a grabber supports the apiconfig capability, it can provide the PVR application with a set of questions that the user must answer before the grabber can download data. These questions are described in the xmltv-configuration format defined in ?XmltvConfigurationDtd. The PVR application must then write the user's answer to a configuration file in the format described in XmltvConfigurationFile.
The PVR application shall start by performing the following commands:
rm $PVRHOME/grabber.conf
touch $PVRHOME/grabber.conf
grabber --config-file $PVRHOME/grabber.conf --configure-api \
--output /tmp/stage.xml
This will write an xml-file containing a set of questions that the user must answer. The PVR application shall write his answers to the file $PVRHOME/grabber.conf in the format specified in README.configfile.
It may be necessary to do the configuration in several steps. This is indicated by the tag in stage.xml. As long as the stage attribute is different from "select-channels", the user must answer the questions posed and then move on to the next stage:
while $nextstage != channels:
grabber --config-file $PVRHOME/grabber.conf --configure-api \
--stage $nextstage --output /tmp/stage.xml
The stage "select-channels" can be handled in the same way as the other stages, i.e. with --stage select-channels. Some PVR applications may however wish to handle this stage separately. They can request a list of all the available channels given the entered configuration information using
grabber --config-file $PVRHOME/grabber.conf --list-channels
The data returned from this command is a standard XMLTV file with only channel entries.
The PVR application can then choose which channels to download data for by writing entries to the configuration file as described in XmltvConfigurationFile.