Data Service Decoder
High Level Decoding

## Functions

vbi_decoder * | vbi_decoder_new (void)
| Allocate a new data service decoder instance.
void | vbi_decoder_delete (vbi_decoder *vbi)
| Delete a data service decoder instance.
void | vbi_decode (vbi_decoder *vbi, vbi_sliced *sliced, int lines, double timestamp)
| Main function of the data service decoder.
void | vbi_channel_switched (vbi_decoder *vbi, vbi_nuid nuid)
vbi_page_type | vbi_classify_page (vbi_decoder *vbi, vbi_pgno pgno, vbi_subno *subno, char **language)
void | vbi_version (unsigned int *major, unsigned int *minor, unsigned int *micro)
void | vbi_set_log_fn (vbi_log_mask mask, vbi_log_fn *log_fn, void *user_data)

## Detailed Description

## Function Documentation

## vbi_decoder_new()

vbi_decoder * vbi_decoder_new | ( | void |  | ) |

extern

Allocate a new data service decoder instance.

Returns
  vbi_decoder pointer or `NULL` on failure, probably due to lack of memory.

## vbi_decoder_delete()

void vbi_decoder_delete | ( | vbi_decoder * | vbi | ) |

extern

Delete a data service decoder instance.

Parameters

  vbi | Decoder structure allocated with vbi_decoder_new().

References vbi_event_handler_unregister().

## vbi_decode()

void vbi_decode | ( | vbi_decoder * | vbi,
|  | vbi_sliced * | sliced,
|  | int | lines,
|  | double | time )

extern

Main function of the data service decoder.

Parameters

  vbi | Initialized vbi decoding context as returned by vbi_decoder_new().
  sliced | Array of vbi_sliced data packets to be decoded.
  lines | Number of vbi_sliced data packets, i. e. VBI lines.
  time | Timestamp associated with all sliced data packets. This is the time in seconds and fractions since 1970-01-01 00:00, for example from function gettimeofday(). time should only increment, the latest time entered is considered the current time for activity calculation.

Decodes zero or more lines of sliced VBI data from the same video frame, updates the decoder state and calls event handlers.

timestamp shall advance by 1/60 to 1/12.5 seconds whenever calling this function. Failure to do so will be interpreted as frame dropping, which starts a resynchronization cycle, eventually a channel switch may be assumed which resets even more decoder state. So even if a frame did not contain any useful data this function must be called, with lines set to zero.

Note
  This is one of the few not reentrant libzvbi functions. If multiple threads call this with the same vbi context you must implement your own locking mechanism. Never call this function from an event handler.

References vbi_sliced::data, vbi_sliced::id, and vbi_sliced::line.

## vbi_channel_switched()

void vbi_channel_switched | ( | vbi_decoder * | vbi,
|  | vbi_nuid | nuid )

extern

Parameters

  vbi | VBI decoding context.
  nuid | Set to zero for now.

Call this after switching away from the channel (RF channel, video input line, precisely: the network) from which this context used to receive vbi data, to reset the decoding context accordingly. This includes deletion of all cached Teletext and Closed Caption pages.

The decoder attempts to detect channel switches automatically, but this is not 100 % reliable, especially without receiving and decoding Teletext or VPS which frequently transmit network identifiers.

Note the reset is not executed until the next frame is about to be decoded, so you may still receive "old" events after calling this. You may also receive blank events (e. g. unknown network, unknown aspect ratio) revoking a previously sent event, until new information becomes available.

## vbi_classify_page()

vbi_page_type vbi_classify_page | ( | vbi_decoder * | vbi,
|  | vbi_pgno | pgno,
|  | vbi_subno * | subno,
|  | char ** | language )

extern

Parameters

  vbi | Initialized vbi decoding context.
  pgno | Teletext or Closed Caption page to examine, see vbi_pgno.
  subno | The highest subpage number of this page will be stored here. subno can be `NULL`.
  language | If it is possible to determine the language a page is written in, a pointer to the language name (Latin-1) will be stored here, `NULL` if the language is unknown. language can be `NULL` if this information is not needed.

Returns information about the page.

For Closed Caption pages (pgno 1 ... 8) subno will always be zero, language set or `NULL`. The return value will be `VBI_SUBTITLE_PAGE` for page 1 ... 4 (Closed Caption channel 1 ... 4), `VBI_NORMAL_PAGE` for page 5 ... 8 (Text channel 1 ... 4), or `VBI_NO_PAGE` if no data is currently transmitted on the channel.

For Teletext pages (pgno 0x100 ... 0x8FF) subno returns the highest subpage number used. Note this number can be larger (but not smaller) than the number of subpages actually received and cached. Still there is no guarantee the advertised subpages will ever appear or stay in cache.

subno | meaning
0 | single page, no subpages
1 | never
2 ... 0x3F7F | has subpages 1 ... subno
0xFFFE | has unknown number (two or more) of subpages
0xFFFF | presence of subpages unknown

language currently returns the language of subtitle pages, `NULL` if unknown or the page is not classified as `VBI_SUBTITLE_PAGE`.

Other page types are:

VBI_NO_PAGE | Page is not in transmission
VBI_NORMAL_PAGE |
VBI_SUBTITLE_PAGE |
VBI_SUBTITLE_INDEX | List of subtitle pages
VBI_NONSTD_SUBPAGES | For example a world time page
VBI_PROGR_WARNING | Program related warning (perhaps schedule change anouncements, the Teletext specification does not elaborate on this)
VBI_CURRENT_PROGR | Information about the current program
VBI_NOW_AND_NEXT | Brief information about the current and next program
VBI_PROGR_INDEX | Program index page (perhaps the front page of all program related pages)
VBI_PROGR_SCHEDULE | Program schedule page
VBI_UNKNOWN_PAGE |

Note
  The results of this function are volatile: As more information becomes available and pages are edited (e. g. activation of subtitles, news updates, program related pages) subpage numbers can grow, page types, subno 0xFFFE and 0xFFFF and languages can change.

Returns
  Page type.

References ttx_page_stat::charset_code, ttx_page_stat::page_type, and ttx_page_stat::subcode.

## vbi_version()

void vbi_version | ( | unsigned int * | major,
|  | unsigned int * | minor,
|  | unsigned int * | micro )

extern

Parameters

  major | Store major number here, can be NULL.
  minor | Store minor number here, can be NULL.
  micro | Store micro number here, can be NULL.

Returns the library version defined in the libzvbi.h header file when the library was compiled.

Since
  0.2.5

## vbi_set_log_fn()

void vbi_set_log_fn | ( | vbi_log_mask | mask,
|  | vbi_log_fn * | log_fn,
|  | void * | user_data )

extern

Parameters

  mask | Which kind of information to log. Can be `0`.
  log_fn | This function is called with log messages. Consider vbi_log_on_stderr(). Can be `NULL` to disable logging.
  user_data | User pointer passed through to the log_fn function.

Various library functions can print warnings, errors and information useful to debug the library. With this function you can enable these messages and designate a function to print them.

This function enables logging globally. You can also call the set_log_fn() function of individual modules to reduce the scope or redirect messages from that module to another log function.

Note
  The number of contents of messages may change in the future.

Since
  0.2.22