Main Page | Modules | Data Structures | Data Fields | Related Pages | Examples

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


US TV rating flags

#define VBI_RATING_D   0x08
#define VBI_RATING_L   0x04
#define VBI_RATING_S   0x02
#define VBI_RATING_V   0x01

Event types.

#define VBI_EVENT_NONE   0x0000
#define VBI_EVENT_CLOSE   0x0001
#define VBI_EVENT_TTX_PAGE   0x0002
#define VBI_EVENT_CAPTION   0x0004
#define VBI_EVENT_NETWORK   0x0008
#define VBI_EVENT_TRIGGER   0x0010
#define VBI_EVENT_ASPECT   0x0040
#define VBI_EVENT_PROG_INFO   0x0080
#define VBI_EVENT_NETWORK_ID   0x0100

Typedefs

typedef unsigned int vbi_nuid
 Unique network id (a libzvbi thing).

typedef vbi_link vbi_link
typedef vbi_program_info vbi_program_info
typedef 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.


Define Documentation

#define VBI_RATING_D   0x08
 

"sexually suggestive dialog"

#define VBI_EVENT_NONE   0x0000
 

No event.

#define VBI_RATING_L   0x04
 

"indecent language"

#define VBI_RATING_S   0x02
 

"sexual situations"

#define VBI_RATING_V   0x01
 

"violence"

#define VBI_EVENT_CLOSE   0x0001
 

The vbi decoding context is about to be closed. This event is sent by vbi_decoder_delete() and can be used to clean up event handlers.

#define VBI_EVENT_TTX_PAGE   0x0002
 

The vbi decoder received and cached another Teletext page designated by ev.ttx_page.pgno and ev.ttx_page.subno.

ev.ttx_page.roll_header flags the page header as suitable for rolling page numbers, e. g. excluding pages transmitted out of order.

The ev.ttx_page.header_update flag is set when the header, excluding the page number and real time clock, changed since the last VBI_EVENT_TTX_PAGE. Note this may happen at midnight when the date string changes. The ev.ttx_page.clock_update flag is set when the real time clock changed since the last VBI_EVENT_TTX_PAGE (that is at most once per second). They are both set at the first VBI_EVENT_TTX_PAGE sent and unset while the received header or clock field is corrupted.

If any of the roll_header, header_update or clock_update flags are set ev.ttx_page.raw_header is a pointer to the raw header data (40 bytes), which remains valid until the event handler returns. ev.ttx_page.pn_offset will be the offset (0 ... 37) of the three digit page number in the raw or formatted header. Allways call vbi_fetch_vt_page() for proper translation of national characters and character attributes, the raw header is only provided here as a means to quickly detect changes.

#define VBI_EVENT_CAPTION   0x0004
 

A Closed Caption page has changed and needs visual update. The page or "CC channel" is designated by ev.caption.pgno, see vbi_pgno for details.

When the client is monitoring this page, the expected action is to call vbi_fetch_cc_page(). To speed up rendering more detailed update information is provided in vbi_page.dirty, see vbi_page. The vbi_page will be a snapshot of the status at fetch time and not event time, vbi_page.dirty accumulates all changes since the last fetch.

#define VBI_EVENT_NETWORK   0x0008
 

Some station/network identifier has been received or is no longer transmitted (vbi_network all zero, eg. after a channel switch). ev.network is a vbi_network object, read only. The event will not repeat*) unless a different identifier has been received and confirmed.

Minimum time to identify network, when data service is transmitted:
VPS (DE/AT/CH only):0.08 s
Teletext PDC, 8/30:2 s
XDS (US only):unknown, between 0.1x to 10x seconds

*) VPS/TTX and XDS will not combine in real life, feeding the decoder with artificial data can confuse the logic.

#define VBI_EVENT_TRIGGER   0x0010
 

Triggers are sent by broadcasters to start some action on the user interface of modern TVs. Until libzvbi implements all ;-) of WebTV and SuperTeletext the information available are program related (or unrelated) URLs, short messages and Teletext page links.

This event is sent when a trigger has fired, ev.trigger points to a vbi_link structure describing the link in detail. The structure must be read only.

#define VBI_EVENT_ASPECT   0x0040
 

The vbi decoder received new information (potentially from PAL WSS, NTSC XDS or EIA-J CPR-1204) about the program aspect ratio. ev.ratio is a pointer to a vbi_ratio structure. The structure must be read only.

#define VBI_EVENT_PROG_INFO   0x0080
 

We have new information about the current or next program. ev.prog_info is a vbi_program_info pointer (due to size), read only.

Preliminary.

XXX Info from Teletext not implemented yet. XXX Change to get_prog_info. network ditto?

#define VBI_EVENT_NETWORK_ID   0x0100
 

Like VBI_EVENT_NETWORK, but this event will also be sent when the decoder cannot determine a network name.

Since:
0.2.20


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.

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.

typedef struct vbi_program_info vbi_program_info
 

Information about the current program, preliminary.


Enumeration Type Documentation

enum vbi_link_type
 

Link type.

Enumeration values:
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.

Enumeration values:
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.

Enumeration values:
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 Mon Jun 9 21:44:14 2008 for ZVBI Library by doxygen 1.3.5