Exporting formatted Teletext and Closed Caption pages
[High Level Decoding]


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.
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)
ssize_t	vbi_export_mem (vbi_export e, void buffer, size_t buffer_size, const vbi_page *pg) _vbi_nonnull((1))
void *	vbi_export_alloc (vbi_export e, void buffer, size_t buffer_size, const vbi_page *pg) _vbi_nonnull((1))
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:

 static void
 export_my_page (vbi_page *pg)
 {
         vbi_export *ex;
         char *errstr;

         if (!(ex = vbi_export_new ("html", &errstr))) {
                 fprintf (stderr, "Cannot export as HTML: %s\n", errstr);
                 free (errstr);
                 return;
         }

         if (!vbi_export_file (ex, "my_page.html", pg))
                 puts (vbi_export_errstr (ex));

         vbi_export_delete (ex);
 }

Typedef Documentation

typedef struct vbi_export vbi_export

Export module instance, an opaque object.

Allocate with vbi_export_new().

Enumeration Type Documentation

enum vbi_option_type

Enumerator:

VBI_OPTION_BOOL

A boolean value, either TRUE (1) or FALSE (0).

Type:	int
Default:	vbi_option_info.def.num
Bounds:	vbi_option_info.min.num (0) ... max.num (1), step.num (1)
Menu:	NULL

VBI_OPTION_INT

A signed integer value.

Type:	int
Default:	vbi_option_info.def.num
Bounds:	vbi_option_info.min.num ... max.num, step.num
Menu:	NULL

When only a few discrete values rather than a range of values are permitted vbi_option_info.menu points to a vector of integers. However you must still set the option by value, not by menu index. If the value is invalid vbi_export_option_set() may fail or pick the closest possible value instead.

Type:	int
Default:	vbi_option_info.menu.num[vbi_option_info.def.num]
Bounds:	See vbi_option_info.menu.num[] for valid values
Menu:	vbi_option_info.menu.num[min.num (0) ... max.num], step.num (1)

VBI_OPTION_REAL

A real value.

Type:	double
Default:	vbi_option_info.def.dbl
Bounds:	vbi_option_info.min.dbl ... max.dbl, step.dbl
Menu:	NULL

As with VBI_OPTION_INT vbi_option_info.menu may point to a set of valid values:

Type:	double
Default:	vbi_option_info.menu.dbl[vbi_option.info.def.num]
Bounds:	See vbi_option_info.menu.dbl[] for valid values
Menu:	vbi_option_info.menu.dbl[min.num (0) ... max.num], step.num (1)

VBI_OPTION_STRING

A null terminated string.

Type:	char *
Default:	vbi_option_info.def.str
Bounds:	Not applicable
Menu:	NULL

As with VBI_OPTION_INT vbi_option_info.menu may point to a set of valid strings. Note that vbi_export_option_set() always expects a string for this kind of option, and it may accept strings which are not in the menu. Contrast this with VBI_OPTION_MENU, where a menu index is expected.

Type:	char *
Default:	vbi_option_info.menu.str[vbi_option_info.def.num]
Bounds:	Not applicable
Menu:	vbi_option_info.menu.str[min.num (0) ... max.num], step.num (1)

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.

Type:	int
Default:	vbi_option_info.def.num
Bounds:	vbi_option_info.min.num (0) ... max.num, step.num (1)
Menu:	vbi_option_info.menu.str[vbi_option_info.min.num ... max.num], step.num (1).

Function Documentation

vbi_export_info* vbi_export_info_enum ( int index )

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.

vbi_export_info* vbi_export_info_keyword ( const char * keyword )

Parameters:

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.

Returns:: Static pointer to a vbi_export_info structure, NULL if the named export module has not been found.

vbi_export_info* vbi_export_info_export ( vbi_export * export )

Parameters:

export

Pointer to a vbi_export object previously allocated with vbi_export_new().

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:

keyword

like this:

 vbi_export_new ("keyword; quality=75.5, comment=\"example text\"");

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.

void vbi_export_delete ( vbi_export * export )

Parameters:

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.

vbi_option_info* vbi_export_option_info_enum	(	vbi_export *	export,
		int	index
	)

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_option_info* vbi_export_option_info_keyword	(	vbi_export *	export,
		const char *	keyword
	)

Parameters:

	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.

Returns:: Static pointer to a vbi_option_info structure, NULL if the keyword wasn't found.

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

 vbi_export_option_set (export, "quality", 75.5);

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.

vbi_bool vbi_export_option_get	(	vbi_export *	export,
		const char *	keyword,
		vbi_option_value *	value
	)

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.

ssize_t vbi_export_mem	(	vbi_export *	e,
		void *	buffer,
		size_t	buffer_size,
		const vbi_page *	pg
	)

Parameters:

	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.

Returns:: On success the function returns the actual number of bytes stored in the buffer. If buffer_size is too small it returns the required size and the buffer contents are undefined. On other errors it returns -1 and the buffer contents are undefined.

Since:: 0.2.26

void* vbi_export_alloc	(	vbi_export *	e,
		void **	buffer,
		size_t *	buffer_size,
		const vbi_page *	pg
	)

Parameters:

	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.

Returns:: On success the function returns the address of the allocated buffer. On failure it returns NULL, and buffer and buffer_size remain unmodified.

Since:: 0.2.26

vbi_bool vbi_export_stdio	(	vbi_export *	e,
		FILE *	fp,
		vbi_page *	pg
	)

Parameters:

	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.

Returns:: FALSE on failure, TRUE on success.

vbi_bool vbi_export_file	(	vbi_export *	e,
		const char *	name,
		vbi_page *	pg
	)

Parameters:

	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.

Returns:: FALSE on failure, TRUE on success.

char* vbi_export_errstr ( vbi_export * export )

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.

Exporting formatted Teletext and Closed Caption pages [High Level Decoding]

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Exporting formatted Teletext and Closed Caption pages
[High Level Decoding]