ZVBI Library
0.2.33
|
Modules | |
Internal export module interface | |
Teletext and Closed Caption page render functions | |
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... | |
Typedefs | |
typedef struct vbi_export | vbi_export |
Export module instance, an opaque object. More... | |
typedef struct vbi_export_info | vbi_export_info |
Information about an export module. More... | |
Enumerations | |
enum | vbi_option_type { VBI_OPTION_BOOL = 1, VBI_OPTION_INT, VBI_OPTION_REAL, VBI_OPTION_STRING, VBI_OPTION_MENU } |
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 struct vbi_export vbi_export |
Export module instance, an opaque object.
Allocate with vbi_export_new().
typedef struct vbi_export_info vbi_export_info |
Information about an export module.
Although export modules can be accessed by a static keyword (see vbi_export_new()) they are by definition opaque. The client can list export modules for the user and manipulate them without knowing about their availability or purpose. To do so, information about the module is necessary, given in this structure.
You can obtain this information with vbi_export_info_enum().
enum vbi_option_type |
Enumerator | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
VBI_OPTION_BOOL |
A boolean value, either
| ||||||||||||||||
VBI_OPTION_INT |
A signed integer value.
When only a few discrete values rather than a range of values are permitted
| ||||||||||||||||
VBI_OPTION_REAL |
A real value.
As with
| ||||||||||||||||
VBI_OPTION_STRING |
A null terminated string.
As with
| ||||||||||||||||
VBI_OPTION_MENU |
Choice between a number of named options. The value of this kind of option is the menu index. The menu strings can be localized with a dgettext("zvbi", menu.str[n]) call. For details see gettext info file.
|
vbi_export_info* vbi_export_info_enum | ( | int | index | ) |
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.
NULL
if the index is out of bounds. vbi_export_info* vbi_export_info_keyword | ( | const char * | keyword | ) |
keyword | Export module identifier as in vbi_export_info and vbi_export_new(). |
Similar to vbi_export_info_enum(), but this function attempts to find an export module by keyword.
NULL
if the named export module has not been found. References vbi_export_info::keyword.
vbi_export_info* vbi_export_info_export | ( | vbi_export * | export | ) |
export | Pointer to a vbi_export object previously allocated with vbi_export_new(). |
Returns the export module info for the given export object.
NULL
if export is NULL
. References vbi_export::_class.
vbi_export* vbi_export_new | ( | const char * | keyword, |
char ** | errstr | ||
) |
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
keyword | like this: |
NULL
is returned and the errstr may be set (else NULL) if some problem occurred. References vbi_export::_class, vbi_export::errstr, vbi_export_info::keyword, vbi_export_info::label, vbi_export::name, vbi_export_delete(), and vbi_export_errstr().
void vbi_export_delete | ( | vbi_export * | export | ) |
export | Pointer to a vbi_export object previously allocated with vbi_export_new(). Can be NULL . |
This function frees all resources associated with the vbi_export object.
References vbi_export::_class, vbi_export::creator, vbi_export::errstr, and vbi_export::network.
Referenced by vbi_export_new().
vbi_option_info* vbi_export_option_info_enum | ( | vbi_export * | export, |
int | index | ||
) |
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.
NULL
if index is out of bounds. References vbi_export::_class.
vbi_option_info* vbi_export_option_info_keyword | ( | vbi_export * | export, |
const char * | keyword | ||
) |
export | Pointer to a initialized vbi_export object. |
keyword | Keyword of the option as in vbi_option_info. |
Similar to vbi_export_option_info_enum(), but tries to find the option info based on the given keyword.
NULL
if the keyword wasn't found. References vbi_export::_class, vbi_option_info::keyword, and vbi_export_unknown_option().
Referenced by vbi_export_invalid_option(), vbi_export_option_menu_get(), and vbi_export_option_menu_set().
vbi_bool vbi_export_option_set | ( | vbi_export * | export, |
const char * | keyword, | ||
... | |||
) |
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.
TRUE
on success, otherwise the option is not changed. References vbi_export::_class, vbi_export::creator, vbi_export::network, vbi_export::reveal, and vbi_export_strdup().
Referenced by vbi_export_option_menu_set().
vbi_bool vbi_export_option_get | ( | vbi_export * | export, |
const char * | keyword, | ||
vbi_option_value * | value | ||
) |
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.
TRUE
on success, otherwise value unchanged. References vbi_export::_class, vbi_export::creator, vbi_export::network, vbi_export::reveal, vbi_export_strdup(), and vbi_export_unknown_option().
Referenced by vbi_export_option_menu_get().
vbi_bool vbi_export_option_menu_set | ( | vbi_export * | export, |
const char * | keyword, | ||
int | entry | ||
) |
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.
TRUE
on success, otherwise the option is not changed. References vbi_option_info::max, vbi_option_info::menu, vbi_option_info::type, vbi_export_option_info_keyword(), vbi_export_option_set(), VBI_OPTION_BOOL, VBI_OPTION_INT, VBI_OPTION_MENU, and VBI_OPTION_REAL.
vbi_bool vbi_export_option_menu_get | ( | vbi_export * | export, |
const char * | keyword, | ||
int * | entry | ||
) |
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.
TRUE
on success, otherwise value remained unchanged. References vbi_option_info::menu, vbi_option_info::min, vbi_option_info::type, vbi_export_option_get(), vbi_export_option_info_keyword(), VBI_OPTION_BOOL, VBI_OPTION_INT, VBI_OPTION_MENU, and VBI_OPTION_REAL.
ssize_t vbi_export_mem | ( | vbi_export * | e, |
void * | buffer, | ||
size_t | buffer_size, | ||
const vbi_page * | pg | ||
) |
e | Initialized vbi_export object. |
buffer | Output buffer. |
buffer_size | Size of the output buffer in bytes. |
pg | Page to be exported. |
This function writes the pg contents, converted to the format selected with vbi_export_new(), into the buffer.
You can call this function repeatedly, it does not change the state of the vbi_export or vbi_page structure.
References vbi_export::_class, vbi_export::_write, vbi_export::capacity, vbi_export::data, vbi_export::offset, vbi_export::target, and vbi_export::write_error.
void* vbi_export_alloc | ( | vbi_export * | e, |
void ** | buffer, | ||
size_t * | buffer_size, | ||
const vbi_page * | pg | ||
) |
e | Initialized vbi_export object. |
buffer | The address of the output buffer will be stored here. buffer can be NULL . |
buffer_size | The amount of data stored in the output buffer, in bytes, will be stored here. buffer_size can be NULL . |
pg | Page to be exported. |
This function writes the pg contents, converted to the format selected with vbi_export_new(), into a newly allocated buffer. You must free() this buffer when it is no longer needed.
You can call this function repeatedly, it does not change the state of the vbi_export or vbi_page structure.
NULL
, and buffer and buffer_size remain unmodified.References vbi_export::_class, vbi_export::_write, vbi_export::capacity, vbi_export::data, vbi_export::offset, vbi_export::target, and vbi_export::write_error.
vbi_bool vbi_export_stdio | ( | vbi_export * | e, |
FILE * | fp, | ||
vbi_page * | pg | ||
) |
e | 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 format selected with the vbi_export_new() function, into 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 repeatedly, it does not change the state of the vbi_export or vbi_page structure.
FALSE
on failure, TRUE
on success. References vbi_export::_class, vbi_export::_write, vbi_export::data, vbi_export::target, and vbi_export::write_error.
vbi_bool vbi_export_file | ( | vbi_export * | e, |
const char * | name, | ||
vbi_page * | pg | ||
) |
e | Initialized vbi_export object. |
name | File to be created. |
pg | Page to be exported. |
Writes the pg contents, converted to the format selected with vbi_export_new(), into a new file with the given name. When an error occurs after the file was opened, the function deletes the file.
You can call this function repeatedly, it does not change the state of the vbi_export or vbi_page structure.
FALSE
on failure, TRUE
on success. References vbi_export::_class, vbi_export::_write, vbi_export::data, vbi_export::name, vbi_export::target, vbi_export_error_printf(), vbi_export_write_error(), and vbi_export::write_error.
char* vbi_export_errstr | ( | vbi_export * | export | ) |
export | Pointer to a initialized vbi_export object. |
References vbi_export::errstr.
Referenced by vbi_export_new().