Events
High Level Decoding

## Data Structures

struct | vbi_network
| Network description. More...
struct | vbi_link
struct | vbi_aspect_ratio
| Information about the picture aspect ratio and open subtitles. More...
struct | vbi_program_info
struct | vbi_event
| Event union. More...

## Typedefs

typedef unsigned int | vbi_nuid
| Unique network id (a libzvbi thing).
typedef struct vbi_link | vbi_link
typedef struct vbi_program_info | vbi_program_info
typedef struct vbi_event | vbi_event
| Event union.
typedef void(* | vbi_event_handler) (vbi_event *event, void *user_data)

## Enumerations

enum | vbi_link_type { VBI_LINK_NONE = 0 , VBI_LINK_MESSAGE , VBI_LINK_PAGE , VBI_LINK_SUBPAGE , VBI_LINK_HTTP , VBI_LINK_FTP , VBI_LINK_EMAIL , VBI_LINK_LID , VBI_LINK_TELEWEB }
| Link type. More...
enum | vbi_itv_type { VBI_WEBLINK_UNKNOWN = 0 , VBI_WEBLINK_PROGRAM_RELATED , VBI_WEBLINK_NETWORK_RELATED , VBI_WEBLINK_STATION_RELATED , VBI_WEBLINK_SPONSOR_MESSAGE , VBI_WEBLINK_OPERATOR }
| ITV link type. More...
enum | vbi_subt { VBI_SUBT_NONE , VBI_SUBT_ACTIVE , VBI_SUBT_MATTE , VBI_SUBT_UNKNOWN }
| Open subtitle information. More...
enum | vbi_rating_auth { VBI_RATING_AUTH_NONE = 0 , VBI_RATING_AUTH_MPAA , VBI_RATING_AUTH_TV_US , VBI_RATING_AUTH_TV_CA_EN , VBI_RATING_AUTH_TV_CA_FR }
| Program rating source. More...
enum | vbi_prog_classf { VBI_PROG_CLASSF_NONE = 0 , VBI_PROG_CLASSF_EIA_608 , VBI_PROG_CLASSF_ETS_300231 }
| Program classification schemes. More...
enum | vbi_audio_mode { VBI_AUDIO_MODE_NONE = 0 , VBI_AUDIO_MODE_MONO , VBI_AUDIO_MODE_STEREO , VBI_AUDIO_MODE_STEREO_SURROUND , VBI_AUDIO_MODE_SIMULATED_STEREO , VBI_AUDIO_MODE_VIDEO_DESCRIPTIONS , VBI_AUDIO_MODE_NON_PROGRAM_AUDIO , VBI_AUDIO_MODE_SPECIAL_EFFECTS , VBI_AUDIO_MODE_DATA_SERVICE , VBI_AUDIO_MODE_UNKNOWN }
| Type of audio transmitted on one (mono or stereo) audio track. More...

## Functions

const char * | vbi_prog_type_string (vbi_prog_classf classf, int id)
void | vbi_reset_prog_info (vbi_program_info *pi)
vbi_bool | vbi_event_handler_add (vbi_decoder *vbi, int event_mask, vbi_event_handler handler, void *user_data)
void | vbi_event_handler_remove (vbi_decoder *vbi, vbi_event_handler handler)
vbi_bool | vbi_event_handler_register (vbi_decoder *vbi, int event_mask, vbi_event_handler handler, void *user_data)
void | vbi_event_handler_unregister (vbi_decoder *vbi, vbi_event_handler handler, void *user_data)
const char * | vbi_rating_string (vbi_rating_auth auth, int id)

## Detailed Description

Typically the transmission of VBI data like a Teletext or Closed Caption page spans several VBI lines or even video frames. So internally the data service decoder maintains caches accumulating data. When a page or other object is complete it calls the respective event handler to notify the application.

Clients can register any number of handlers needed, also different handlers for the same event. They will be called in the order registered from the vbi_decode() function. Since they block decoding, they should return as soon as possible. The event structure and all data pointed to from there must be read only. The data is only valid until the handler returns.

## Typedef Documentation

## vbi_nuid

typedef unsigned int vbi_nuid

Unique network id (a libzvbi thing).

0 = unknown network, bit 31 reserved for preliminary nuids. Other network codes are arbitrary.

## vbi_link

typedef struct vbi_link vbi_link

General purpose link description for ATVEF (ITV, WebTV in the United States) and EACEM (SuperTeletext et al in Europe) triggers, Teletext TOP and FLOF navigation, and for links "guessed" by libzvbi from the text (e. g. page numbers and URLs). Usually not all fields will be used.

## vbi_program_info

typedef struct vbi_program_info vbi_program_info

Information about the current program, preliminary.

## Enumeration Type Documentation

## vbi_link_type

enum vbi_link_type

Link type.

Enumerator
VBI_LINK_NONE | vbi_resolve_link() may return a link of this type on failure.
VBI_LINK_MESSAGE | Not really a link, only vbi_link->name will be set. (Probably something like "Help! Help! The station is on fire!")
VBI_LINK_PAGE | Points to a Teletext page, vbi_link->pgno and vbi_link->subno, eventually vbi_link->nuid and a descriptive text in vbi_link->name.
VBI_LINK_SUBPAGE | Also a Teletext page link, but this one is used exclusively to link subpages of the page containing the link.
VBI_LINK_HTTP | vbi_link->url is a HTTP URL (like "http://zapping.sf.net"), eventually accompanied by a descriptive text vbi_link->name.
VBI_LINK_FTP | vbi_link->url is a FTP URL (like "ftp://foo.bar.com/baz"), eventually accompanied by a descriptive text vbi_link->name.
VBI_LINK_EMAIL | vbi_link->url is an e-mail address (like "mailto:foo@bar"), eventually accompanied by a descriptive text vbi_link->name.
VBI_LINK_LID | Is a trigger link id. Not useful, just ignore.
VBI_LINK_TELEWEB | Is a SuperTeletext link, ignore.

## vbi_itv_type

enum vbi_itv_type

ITV link type.

Some ITV (WebTV, ATVEF) triggers include a type id intended to filter relevant information. The names should speak for themselves. EACEM triggers always have type `VBI_WEBLINK_UNKNOWN`.

## vbi_subt

enum vbi_subt

Open subtitle information.

Open because they have been inserted into the picture, as opposed to closed subtitles (closed caption) encoded in the vbi.

Enumerator
VBI_SUBT_NONE | No open subtitles.
VBI_SUBT_ACTIVE | Inserted in active picture.
VBI_SUBT_MATTE | Inserted in upper or lower letterbox bar.
VBI_SUBT_UNKNOWN | Presence of open subtitles unknown.

## vbi_rating_auth

enum vbi_rating_auth

Program rating source.

If program rating information is available (also known in the U. S. as V-Chip data), this describes which rating scheme is being used: U. S. film, U. S. TV, Canadian English or French TV. You can convert the rating code to a string with vbi_rating_string().

When the scheme is `VBI_RATING_TV_US`, additionally the DLSV rating flags will be set.

## vbi_prog_classf

enum vbi_prog_classf

Program classification schemes.

libzvbi understands two different program classification schemes, the EIA-608 based in the United States and the ETS 300 231 based one in Europe. You can convert the program type code into a string with vbi_prog_type_string().

## vbi_audio_mode

enum vbi_audio_mode

Type of audio transmitted on one (mono or stereo) audio track.

Enumerator
VBI_AUDIO_MODE_NONE | No sound.
VBI_AUDIO_MODE_MONO | Mono audio.
VBI_AUDIO_MODE_STEREO | Stereo audio.
VBI_AUDIO_MODE_STEREO_SURROUND | Surround.
VBI_AUDIO_MODE_SIMULATED_STEREO | ?
VBI_AUDIO_MODE_VIDEO_DESCRIPTIONS | Spoken descriptions of the program for the blind, on a secondary audio track.
VBI_AUDIO_MODE_NON_PROGRAM_AUDIO | Unrelated to the current program.
VBI_AUDIO_MODE_SPECIAL_EFFECTS | ?
VBI_AUDIO_MODE_DATA_SERVICE | ?
VBI_AUDIO_MODE_UNKNOWN | We have no information what is transmitted.

## Function Documentation

## vbi_prog_type_string()

const char * vbi_prog_type_string | ( | vbi_prog_classf | classf,
|  | int | id )

extern

Parameters

  classf | From vbi_program_info.type_classf.
  id | From vbi_program_info.type_id.

Translate a vbi_program_info program type code into a Latin-1 string, currently English only.

Returns
  Static pointer to the string (don't free()), or `NULL` if this code is undefined.

## vbi_reset_prog_info()

void vbi_reset_prog_info | ( | vbi_program_info * | pi | ) |

extern

Parameters

  pi |

Convenience function to set a vbi_program_info structure to defaults.

References vbi_aspect_ratio::film_mode, vbi_aspect_ratio::first_line, vbi_aspect_ratio::open_subtitles, vbi_aspect_ratio::ratio, VBI_AUDIO_MODE_UNKNOWN, and VBI_SUBT_UNKNOWN.

## vbi_event_handler_add()

vbi_bool vbi_event_handler_add | ( | vbi_decoder * | vbi,
|  | int | event_mask,
|  | vbi_event_handler | handler,
|  | void * | user_data )

extern

Parameters

  vbi | Initialized vbi decoding context.
  event_mask | Events the handler is waiting for.
  handler | Event handler function.
  user_data | Pointer passed to the handler.

Deprecated
  Replaces all existing handlers with this handler function, ignoring user_data. Use vbi_event_handler_register() in new code.

Returns
  FALSE on failure.

Examples
  examples/network.c, and examples/pdc1.c.

Referenced by vbi_event_handler_remove().

## vbi_event_handler_remove()

void vbi_event_handler_remove | ( | vbi_decoder * | vbi,
|  | vbi_event_handler | handler )

extern

Parameters

  vbi | Initialized vbi decoding context.
  handler | Event handler function.

Deprecated
  This functions lacks a user_data parameter. Use vbi_event_handler_register() in new code.

References vbi_event_handler_add().

## vbi_event_handler_register()

vbi_bool vbi_event_handler_register | ( | vbi_decoder * | vbi,
|  | int | event_mask,
|  | vbi_event_handler | handler,
|  | void * | user_data )

extern

Parameters

  vbi | Initialized vbi decoding context.
  event_mask | Events the handler is waiting for.
  handler | Event handler function.
  user_data | Pointer passed to the handler.

Registers a new event handler. event_mask can be any 'or' of VBI_EVENT_ symbols, -1 for all events and 0 for none. When the handler with user_data is already registered, its event_mask will be changed. Any number of handlers can be registered, also different handlers for the same event which will be called in registration order.

Apart of adding handlers this function also enables and disables decoding of data services depending on the presence of at least one handler for the respective data. A `VBI_EVENT_TTX_PAGE` handler for example enables Teletext decoding.

This function can be safely called at any time, even from a handler.

Returns
  `FALSE` on failure.

Examples
  examples/pdc2.c.

Referenced by vbi_event_handler_unregister().

## vbi_event_handler_unregister()

void vbi_event_handler_unregister | ( | vbi_decoder * | vbi,
|  | vbi_event_handler | handler,
|  | void * | user_data )

extern

Parameters

  vbi | Initialized vbi decoding context.
  handler | Event handler function.
  user_data | Pointer passed to the handler.

Unregisters an event handler.

Apart of removing a handler this function also disables decoding of data services when no handler is registered to consume the respective data. Removing the last `VBI_EVENT_TTX_PAGE` handler for example disables Teletext decoding.

This function can be safely called at any time, even from a handler removing itself or another handler, and regardless if the handler has been successfully registered.

References vbi_event_handler_register().

Referenced by vbi_decoder_delete().

## vbi_rating_string()

const char * vbi_rating_string | ( | vbi_rating_auth | auth,
|  | int | id )

extern

Parameters

  auth | From vbi_program_info.rating_auth.
  id | From vbi_program_info.rating_id.

Translate a vbi_program_info program rating code into a Latin-1 string, native language.

return Static pointer to the string (don't free()), or `NULL` if this code is undefined.