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 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

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.


Enumeration Type Documentation

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.

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.

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.

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.

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().

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

const char * vbi_prog_type_string ( vbi_prog_classf  classf,
int  id 
)

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.

void vbi_reset_prog_info ( vbi_program_info pi  ) 

Parameters:
pi 
Convenience function to set a vbi_program_info structure to defaults.

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

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.

void vbi_event_handler_remove ( vbi_decoder *  vbi,
vbi_event_handler  handler 
)

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.

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

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.

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

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.

const char* vbi_rating_string ( vbi_rating_auth  auth,
int  id 
)

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.


Generated on Wed Jun 11 04:50:06 2008 for ZVBI Library by  doxygen 1.4.7