ZVBI Library  0.2.33
Data Structures | Typedefs | Enumerations | Functions
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

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.

Information about the current program, preliminary.


Enumeration Type Documentation

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.

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.

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.

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

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:
classfFrom vbi_program_info.type_classf.
idFrom 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:
vbiInitialized vbi decoding context.
event_maskEvents the handler is waiting for.
handlerEvent handler function.
user_dataPointer 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:
vbiInitialized vbi decoding context.
handlerEvent 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:
vbiInitialized vbi decoding context.
event_maskEvents the handler is waiting for.
handlerEvent handler function.
user_dataPointer 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:
vbiInitialized vbi decoding context.
handlerEvent handler function.
user_dataPointer 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:
authFrom vbi_program_info.rating_auth.
idFrom 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.