General

Listing data is transfered between modules as an ordered set of five-tuples, in the following format:

Time values are on the form YYYYMMDDHHMMSS TIMEZONE.

Example:

It is not unusual that shows lack a description, so the case when description is undefined must be handled by the applications involved.

The flow of listing data

If you are going to develop stuff in the Televinken framework, it might be useful to know what files are involved where. In the following figure, the components to the left of the dashed line represents the programs you execute. The others are part of the "inner workings" of Televinken.

The import utility, fetch_listings.pl will ask every import module it knows about what channels it knows about, and import those. Overlaps (for example both svt.pm and dagenstv.pm knows how to fetch SVT1) are dealt with by just accepting the first successful import. If an import fails, the next one that knows about the channel we are trying to fetch will be asked.

When done, fetch_listings.pl will write the listing to storage via listing_storage.pm. This is actually just a wrapper around one or more of the storage modules. This approach has two advantages I can think of; First, I don't have to rewrite every cgi script if I should want to change storage system. Secondly, I can use several storage modules for different purposes. The default configuration is to use the flat_file.pm storage module for storing and fetching, but also use xmltv.pm for just storage.

That should have explained fetch_listings.pl and listing_storage.pm, and to some extent import_modules/* and storage_modules/*. What else is hidden in the tarball?

*.cgi

Scripts that will output lots of HTML if treated correctly. The user-end of Televinken.

tvdiv.pm

A collection of utility functions for the cgi programs. Time conversion, movie guess, html code several pages has in common etc.

tvinst.pm

The routines that deal with user settings for the cgi programs. If you are looking for the default values, this is where to look. This is also the cookie-monster of the system.

The import modules

fetch_listings.pl talks to the import modules, in the cleverly named directory import_modules/.

Each import module implements the following:

new

Your everyday constructor.

channels

A function that returns an array with the name of all channels this module knows how to import.

source($channel)

Given a channel name, returns (one of) the url(s) that will be used to get listing data.

fetchchannel($channel)

Given a channel name, fetch the listing data and return it in the format defined earlier.

When I started gathering listings for several days ahead, some changes where made. Each module that knows how to get listings for several day must have a sub named multiple_dates, and fetchchannel is then fetchchannel($channel, $date) (with $date on the form YYYY-MM-DD).

If you want to create your own import module, I recommend using one of the current as a skeleton. A usually start with import_modules/tv4.pm when I write a new one. I usually go through these steps:

• Replace $host,$importid etc. with more suitable data.
• Change the channels hash to match your source. Start with one channel, and add the others when everything seems to work.
• Now, time to fetch data. I put the entire html document into a string with get_webpage($host,$port,$doc). Terribly uneffective memory-wise, but it seems to work in real life. Then, I do the following:
  • Remove all linefeeds.
  • Identify the timestamps (for example <B>18:30</B>) and replace it with a linefeed, the time and some kind of separator.
• Now, chop up the string at linefeeds. We get an array with one show per element (the first element will contain junk, remove it).
• Identify what separates the show title from its description, replace that with a separator.
• Remove all other html.
• Chop at separators, add to an array of shows.
• If the shows has no ending time, iterate over the array and set it to the start time of the next show.
• The function remove_overlap can be useful, some sources has overlapping shows.

So far, only one source use HTTP POST instead of HTTP GET. Check import_modules/eskilstunakuriren.pm if you need an example.

Storage

All scripts will talk to listing_storage.pm, which is a wrapper for one or more storage modules. These modules implement the following:

new

Cnstrctr!

store_sources

Stores a hash, (channel name -> url) in some way.

fetch_sources

Builds a hash as above, and returns it.

store

Gets an array of listing data (format as above) and stores it in some way.

fetch

Takes an array of channels, a start time and an end time. Returns the corresponding tv listing data.