Exporting formatted Teletext and Closed Caption pages
[High Level Decoding]
Data Structures |
struct | vbi_export_info |
| Information about an export module. More...
|
union | vbi_option_value |
| Result of an option query. More...
|
union | vbi_option_value_ptr |
| Option menu types. More...
|
struct | vbi_option_info |
| Information about an export option. More...
|
Modules |
| Internal export module interface |
| Teletext and Closed Caption page render functions |
Typedefs |
typedef struct vbi_export | vbi_export |
| Export module instance, an opaque object.
|
Enumerations |
enum | vbi_option_type {
VBI_OPTION_BOOL = 1,
VBI_OPTION_INT,
VBI_OPTION_REAL,
VBI_OPTION_STRING,
VBI_OPTION_MENU
} |
Functions |
vbi_export_info * | vbi_export_info_enum (int index) |
vbi_export_info * | vbi_export_info_keyword (const char *keyword) |
vbi_export_info * | vbi_export_info_export (vbi_export *) |
vbi_export * | vbi_export_new (const char *keyword, char **errstr) |
void | vbi_export_delete (vbi_export *) |
vbi_option_info * | vbi_export_option_info_enum (vbi_export *, int index) |
vbi_option_info * | vbi_export_option_info_keyword (vbi_export *, const char *keyword) |
vbi_bool | vbi_export_option_set (vbi_export *, const char *keyword,...) |
vbi_bool | vbi_export_option_get (vbi_export *, const char *keyword, vbi_option_value *value) |
vbi_bool | vbi_export_option_menu_set (vbi_export *, const char *keyword, int entry) |
vbi_bool | vbi_export_option_menu_get (vbi_export *, const char *keyword, int *entry) |
vbi_bool | vbi_export_stdio (vbi_export *, FILE *fp, vbi_page *pg) |
vbi_bool | vbi_export_file (vbi_export *, const char *name, vbi_page *pg) |
char * | vbi_export_errstr (vbi_export *) |
Detailed Description
Once libzvbi received, decoded and formatted a Teletext or Closed Caption page you will want to render it on screen, print it as text or store it in various formats.
Fortunately you don't have to do it all by yourself. libzvbi provides export modules converting a vbi_page into the desired format or rendering directly into memory.
A minimalistic export example:
Typedef Documentation
Enumeration Type Documentation
- Enumerator:
VBI_OPTION_BOOL |
A boolean value, either TRUE (1) or FALSE (0).
Type:
| int
|
Default:
| def.num
|
Bounds:
| min.num (0) ... max.num (1), step.num (1)
|
Menu:
| NULL
|
|
VBI_OPTION_INT |
A signed integer value. When only a few discrete values rather than a range are permitted menu points to a vector of integers. Note the option is still set by value, not by menu index. Setting the value may fail, or it may be replaced by the closest possible.
Type:
| int
|
Default:
| def.num or menu.num[def.num]
|
Bounds:
| min.num ... max.num, step.num or menu
|
Menu:
| NULL or menu.num[min.num ... max.num], step.num (1)
|
|
VBI_OPTION_REAL |
A real value, optional a vector of suggested values.
Type:
| double
|
Default:
| def.dbl or menu.dbl[def.num]
|
Bounds:
| min.dbl ... max.dbl, step.dbl or menu
|
Menu:
| NULL or menu.dbl[min.num ... max.num], step.num (1)
|
|
VBI_OPTION_STRING |
A null terminated string. Note the menu version differs from VBI_OPTION_MENU in its argument, which is the string itself. For example:
menu.str[0] = "red"
menu.str[1] = "blue"
... and the option may accept other color strings not explicitely listed
Type:
| char *
|
Default:
| def.str or menu.str[def.num]
|
Bounds:
| not applicable
|
Menu:
| NULL or menu.str[min.num ... max.num], step.num (1)
|
|
VBI_OPTION_MENU |
Choice between a number of named options. For example:
menu.str[0] = "up"
menu.str[1] = "down"
menu.str[2] = "strange"
Type:
| int
|
Default:
| def.num
|
Bounds:
| min.num (0) ... max.num, step.num (1)
|
Menu:
| menu.str[min.num ... max.num], step.num (1). The menu strings are nationalized N_("text"), client applications are encouraged to localize with dgettext("zvbi", menu.str[n]). For details see info gettext.
|
|
Function Documentation
- Parameters:
-
| index | Index into the export module list, 0 ... n. |
Enumerates all available export modules. You should start at index 0, incrementing.
Some modules may depend on machine features or the presence of certain libraries, thus the list can vary from session to session.
- Returns:
- Static pointer to a vbi_export_info structure (no need to be freed),
NULL
if the index is out of bounds.
- Parameters:
-
Similar to vbi_export_info_enum(), but this function attempts to find an export module by keyword.
- Returns:
- Static pointer to a vbi_export_info structure,
NULL
if the named export module has not been found.
- Parameters:
-
Returns the export module info for the given export object.
- Returns:
- A static vbi_export_info pointer or
NULL
if export is NULL
.
vbi_export* vbi_export_new |
( |
const char * |
keyword, |
|
|
char ** |
errstr | |
|
) |
| | |
- Parameters:
-
| keyword | Export module identifier as in vbi_export_info. |
| errstr | If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed. |
Creates a new export module instance to export a vbi_page in the respective module format. As a special service you can initialize options by appending to the
- Parameters:
-
- Returns:
- Pointer to a newly allocated vbi_export object which must be freed by calling vbi_export_delete().
NULL
is returned and the errstr may be set (else NULL) if some problem occurred.
- Parameters:
-
This function frees all resources associated with the vbi_export object.
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| index | Index in the option table 0 ... n. |
Enumerates the options available for the given export module. You should start at index 0, incrementing.
- Returns:
- Static pointer to a vbi_option_info structure,
NULL
if index is out of bounds.
vbi_bool vbi_export_option_set |
( |
vbi_export * |
export, |
|
|
const char * |
keyword, |
|
|
|
... | |
|
) |
| | |
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| keyword | Keyword identifying the option, as in vbi_option_info. |
| ... | New value to set. |
Sets the value of the named option. Make sure the value is casted to the correct type (int, double, char *).
Typical usage of vbi_export_option_set():
Mind that options of type VBI_OPTION_MENU
must be set by menu entry number (int), all other options by value. If necessary it will be replaced by the closest value possible. Use function vbi_export_option_menu_set() to set options with menu by menu entry.
- Returns:
TRUE
on success, otherwise the option is not changed.
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| keyword | Keyword identifying the option, as in vbi_option_info. |
| value | A place to store the current option value. |
This function queries the current value of the named option. When the option is of type VBI_OPTION_STRING value.str must be freed with free() when you don't need it any longer. When the option is of type VBI_OPTION_MENU then value.num contains the selected entry.
- Returns:
TRUE
on success, otherwise value unchanged.
vbi_bool vbi_export_option_menu_set |
( |
vbi_export * |
export, |
|
|
const char * |
keyword, |
|
|
int |
entry | |
|
) |
| | |
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| keyword | Keyword identifying the option, as in vbi_option_info. |
| entry | Menu entry to be selected. |
Similar to vbi_export_option_set() this function sets the value of the named option, however it does so by number of the corresponding menu entry. Naturally this must be an option with menu.
- Returns:
TRUE
on success, otherwise the option is not changed.
vbi_bool vbi_export_option_menu_get |
( |
vbi_export * |
export, |
|
|
const char * |
keyword, |
|
|
int * |
entry | |
|
) |
| | |
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| keyword | Keyword identifying the option, as in vbi_option_info. |
| entry | A place to store the current menu entry. |
Similar to vbi_export_option_get() this function queries the current value of the named option, but returns this value as number of the corresponding menu entry. Naturally this must be an option with menu.
- Returns:
TRUE
on success, otherwise value remained unchanged.
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| fp | Buffered i/o stream to write to. |
| pg | Page to be exported. |
This function writes the pg contents, converted to the respective export module format, to the stream fp. The caller is responsible for opening and closing the stream, don't forget to check for i/o errors after closing. Note this function may write incomplete files when an error occurs.
You can call this function as many times as you want, it does not change vbi_export state or the vbi_page.
- Returns:
TRUE
on success.
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
| name | File to be created. |
| pg | Page to be exported. |
This function writes the pg contents, converted to the respective export format, into a new file of the given name. When an error occured the incomplete file will be deleted.
You can call this function as many times as you want, it does not change vbi_export state or the vbi_page.
- Returns:
TRUE
on success.
- Parameters:
-
| export | Pointer to a initialized vbi_export object. |
- Returns:
- After an export function failed, this function returns a pointer to a more detailed error description. Do not free this string. It remains valid until the next call of an export function.