Preparser

Collaboration diagram for Preparser:

Files
file	vlc_preparser.h
	VLC Preparser API.

Data Structures
struct	vlc_thumbnailer_cbs
	Preparser thumbnailer callbacks. More...
struct	vlc_thumbnailer_to_files_cbs
	Preparser thumbnailer to file callbacks. More...
struct	vlc_thumbnailer_arg
	Thumbnailer argument. More...
struct	vlc_thumbnailer_output
	Thumbnailer output argument. More...
struct	vlc_preparser_cfg
	Preparser creation configuration. More...

Macros
#define	VLC_PREPARSER_REQ_ID_INVALID   0
#define	VLC_PREPARSER_TYPE_PARSE   0x01
#define	VLC_PREPARSER_TYPE_FETCHMETA_LOCAL   0x02
#define	VLC_PREPARSER_TYPE_FETCHMETA_NET   0x04
#define	VLC_PREPARSER_TYPE_THUMBNAIL   0x08
#define	VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES   0x10
#define	VLC_PREPARSER_TYPE_FETCHMETA_ALL    (VLC_PREPARSER_TYPE_FETCHMETA_LOCAL|VLC_PREPARSER_TYPE_FETCHMETA_NET)
#define	VLC_PREPARSER_OPTION_INTERACT   0x1000
#define	VLC_PREPARSER_OPTION_SUBITEMS   0x2000

Typedefs
typedef struct vlc_preparser_t	vlc_preparser_t
	Preparser opaque structure.
typedef size_t	vlc_preparser_req_id

Enumerations
enum	vlc_thumbnailer_format { VLC_THUMBNAILER_FORMAT_PNG , VLC_THUMBNAILER_FORMAT_WEBP , VLC_THUMBNAILER_FORMAT_JPEG }
	Thumbnailer output format. More...

Functions
vlc_preparser_t *	vlc_preparser_New (vlc_object_t *obj, const struct vlc_preparser_cfg *cfg)
	This function creates the preparser object and thread.
vlc_preparser_req_id	vlc_preparser_Push (vlc_preparser_t *preparser, input_item_t *item, int type_option, const input_item_parser_cbs_t *cbs, void *cbs_userdata)
	This function enqueues the provided item to be preparsed or fetched.
vlc_preparser_req_id	vlc_preparser_GenerateThumbnail (vlc_preparser_t *preparser, input_item_t *item, const struct vlc_thumbnailer_arg *arg, const struct vlc_thumbnailer_cbs *cbs, void *cbs_userdata)
	This function enqueues the provided item for generating a thumbnail.
int	vlc_preparser_GetBestThumbnailerFormat (enum vlc_thumbnailer_format *format, const char **out_ext)
	Get the best possible format.
int	vlc_preparser_CheckThumbnailerFormat (enum vlc_thumbnailer_format format)
	Check if the format is handled by VLC.
vlc_preparser_req_id	vlc_preparser_GenerateThumbnailToFiles (vlc_preparser_t *preparser, input_item_t *item, const struct vlc_thumbnailer_arg *arg, const struct vlc_thumbnailer_output *outputs, size_t output_count, const struct vlc_thumbnailer_to_files_cbs *cbs, void *cbs_userdata)
	This function generates a thumbnail to one or several files.
size_t	vlc_preparser_Cancel (vlc_preparser_t *preparser, vlc_preparser_req_id id)
	This function cancel all preparsing requests for a given id.
void	vlc_preparser_Delete (vlc_preparser_t *preparser)
	This function destroys the preparser object and thread.
void	vlc_preparser_SetTimeout (vlc_preparser_t *preparser, vlc_tick_t timeout)
	Do not use, libVLC only fonction, will be removed soon.

Detailed Description

Macro Definition Documentation

VLC_PREPARSER_OPTION_INTERACT

#define VLC_PREPARSER_OPTION_INTERACT   0x1000

VLC_PREPARSER_OPTION_SUBITEMS

#define VLC_PREPARSER_OPTION_SUBITEMS   0x2000

VLC_PREPARSER_REQ_ID_INVALID

#define VLC_PREPARSER_REQ_ID_INVALID   0

VLC_PREPARSER_TYPE_FETCHMETA_ALL

#define VLC_PREPARSER_TYPE_FETCHMETA_ALL    (VLC_PREPARSER_TYPE_FETCHMETA_LOCAL|VLC_PREPARSER_TYPE_FETCHMETA_NET)

VLC_PREPARSER_TYPE_FETCHMETA_LOCAL

#define VLC_PREPARSER_TYPE_FETCHMETA_LOCAL   0x02

VLC_PREPARSER_TYPE_FETCHMETA_NET

#define VLC_PREPARSER_TYPE_FETCHMETA_NET   0x04

VLC_PREPARSER_TYPE_PARSE

#define VLC_PREPARSER_TYPE_PARSE   0x01

VLC_PREPARSER_TYPE_THUMBNAIL

#define VLC_PREPARSER_TYPE_THUMBNAIL   0x08

VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES

#define VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES   0x10

Typedef Documentation

vlc_preparser_req_id

typedef size_t vlc_preparser_req_id

vlc_preparser_t

typedef struct vlc_preparser_t vlc_preparser_t

Preparser opaque structure.

The preparser object will retrieve the meta data of any given input item in an asynchronous way. It will also issue art fetching requests.

Enumeration Type Documentation

vlc_thumbnailer_format

enum vlc_thumbnailer_format

Thumbnailer output format.

Enumerator
VLC_THUMBNAILER_FORMAT_PNG
VLC_THUMBNAILER_FORMAT_WEBP
VLC_THUMBNAILER_FORMAT_JPEG

Function Documentation

vlc_preparser_Cancel()

size_t vlc_preparser_Cancel	(	vlc_preparser_t *	preparser,
		vlc_preparser_req_id	id
	)

This function cancel all preparsing requests for a given id.

Parameters

preparser	the preparser object
id	unique id returned by vlc_preparser_Push(), VLC_PREPARSER_REQ_ID_INVALID to cancels all tasks

Returns

number of tasks cancelled

References task::cbs, count, task::id, Interrupt(), task::item, vlc_preparser_t::lock, task::node, task::options, vlc_preparser_t::parser, task::preparse_status, task::preparser, task::runnable, vlc_preparser_t::submitted_tasks, TaskDelete(), vlc_preparser_t::thumbnailer, vlc_preparser_t::thumbnailer_to_files, task::userdata, vlc_executor_Cancel(), vlc_list_foreach, vlc_list_remove(), vlc_mutex_lock(), vlc_mutex_unlock(), VLC_PREPARSER_REQ_ID_INVALID, VLC_PREPARSER_TYPE_FETCHMETA_ALL, VLC_PREPARSER_TYPE_PARSE, VLC_PREPARSER_TYPE_THUMBNAIL, and VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES.

Referenced by vlc_preparser_Delete().

vlc_preparser_CheckThumbnailerFormat()

int vlc_preparser_CheckThumbnailerFormat

(

enum vlc_thumbnailer_format

format

)

Check if the format is handled by VLC.

Parameters

format

format to check

Returns

0 if the format was found, VLC_ENOENT otherwise (in case there are no "image encoder" modules)

References CheckThumbnailerFormat().

vlc_preparser_Delete()

void vlc_preparser_Delete

(

vlc_preparser_t *

preparser

)

This function destroys the preparser object and thread.

Parameters

preparser

the preparser object All pending input items will be released.

References vlc_preparser_t::fetcher, input_fetcher_Delete(), vlc_preparser_t::parser, task::preparser, vlc_preparser_t::thumbnailer, vlc_preparser_t::thumbnailer_to_files, vlc_executor_Delete(), and vlc_preparser_Cancel().

Referenced by vlc_playlist_Delete(), and vlc_playlist_New().

vlc_preparser_GenerateThumbnail()

vlc_preparser_req_id vlc_preparser_GenerateThumbnail	(	vlc_preparser_t *	preparser,
		input_item_t *	item,
		const struct vlc_thumbnailer_arg *	arg,
		const struct vlc_thumbnailer_cbs *	cbs,
		void *	cbs_userdata
	)

This function enqueues the provided item for generating a thumbnail.

Parameters

preparser	the preparser object
item	a valid item to generate the thumbnail for
arg	pointer to the arg struct, NULL for default options
cbs	callback to listen to events (can't be NULL)
cbs_userdata	opaque pointer used by the callbacks

Returns

VLC_PREPARSER_REQ_ID_INVALID in case of error, or a valid id if the item was scheduled for thumbnailing. If this returns an error, the thumbnailer.on_ended callback will not be invoked

The provided input_item will be held by the thumbnailer and can safely be released safely after calling this function.

References task::cbs, task::id, task::item, task::preparser, PreparserAddTask(), task::runnable, TaskNew(), task::thumb_arg, vlc_preparser_cbs::thumbnailer, vlc_preparser_t::thumbnailer, ThumbnailerRun(), vlc_executor_Submit(), VLC_PREPARSER_REQ_ID_INVALID, and VLC_PREPARSER_TYPE_THUMBNAIL.

vlc_preparser_GenerateThumbnailToFiles()

vlc_preparser_req_id vlc_preparser_GenerateThumbnailToFiles	(	vlc_preparser_t *	preparser,
		input_item_t *	item,
		const struct vlc_thumbnailer_arg *	arg,
		const struct vlc_thumbnailer_output *	outputs,
		size_t	output_count,
		const struct vlc_thumbnailer_to_files_cbs *	cbs,
		void *	cbs_userdata
	)

This function generates a thumbnail to one or several files.

Parameters

preparser	the preparser object
item	a valid item to generate the thumbnail for
arg	pointer to the arg struct, NULL for default options
outputs	array of outputs, one file will be generated per output for a single thumbnail
output_count	outputs array size, must be > 1
cbs	callback to listen to events (can't be NULL)
cbs_userdata	opaque pointer used by the callbacks

Returns

VLC_PREPARSER_REQ_ID_INVALID in case of error, or a valid id if the item was scheduled for thumbnailing. If this returns an error, the thumbnailer.on_ended callback will not be invoked

The provided input_item will be held by the thumbnailer and can safely be released safely after calling this function.

References CheckThumbnailerFormat(), vlc_thumbnailer_output::creat_mode, task_thumbnail_output::creat_mode, vlc_thumbnailer_output::crop, task_thumbnail_output::crop, vlc_thumbnailer_output::file_path, task_thumbnail_output::file_path, vlc_thumbnailer_output::format, task_thumbnail_output::fourcc, vlc_thumbnailer_output::height, task_thumbnail_output::height, task::item, msg_Err, vlc_thumbnailer_to_files_cbs::on_ended, task::output_count, task::outputs, vlc_preparser_t::owner, task::preparser, PreparserAddTask(), task::runnable, strdup(), TaskDelete(), TaskNew(), task::thumb_arg, vlc_preparser_t::thumbnailer, vlc_preparser_cbs::thumbnailer_to_files, ThumbnailerRun(), unlikely, vlc_alloc(), VLC_CODEC_UNKNOWN, vlc_executor_Submit(), VLC_PREPARSER_REQ_ID_INVALID, VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES, vlc_thumbnailer_output::width, and task_thumbnail_output::width.

vlc_preparser_GetBestThumbnailerFormat()

int vlc_preparser_GetBestThumbnailerFormat	(	enum vlc_thumbnailer_format *	format,
		const char **	out_ext
	)

Get the best possible format.

Parameters

[out]	format	pointer to the best format
[out]	out_ext	pointer to the extension of the format

Returns

0 if a format was found, VLC_ENOENT otherwise (in case there are no "image encoder" modules)

References CheckThumbnailerFormat().

vlc_preparser_New()

vlc_preparser_t * vlc_preparser_New	(	vlc_object_t *	obj,
		const struct vlc_preparser_cfg *	cfg
	)

This function creates the preparser object and thread.

Parameters

obj	the parent object
cfg	a pointer to a valid confiuration struct

Returns

a valid preparser object or NULL in case of error

References vlc_preparser_t::current_id, vlc_preparser_t::fetcher, input_fetcher_Delete(), input_fetcher_New(), vlc_preparser_t::lock, vlc_preparser_cfg::max_parser_threads, vlc_preparser_cfg::max_thumbnailer_threads, vlc_preparser_t::owner, vlc_preparser_t::parser, vlc_preparser_t::submitted_tasks, vlc_preparser_t::thumbnailer, vlc_preparser_t::thumbnailer_to_files, vlc_preparser_cfg::timeout, vlc_preparser_t::timeout, vlc_preparser_cfg::types, unlikely, vlc_executor_Delete(), vlc_executor_New(), vlc_list_init(), vlc_mutex_init(), VLC_PREPARSER_TYPE_FETCHMETA_ALL, VLC_PREPARSER_TYPE_PARSE, VLC_PREPARSER_TYPE_THUMBNAIL, and VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES.

Referenced by vlc_playlist_New().

vlc_preparser_Push()

vlc_preparser_req_id vlc_preparser_Push	(	vlc_preparser_t *	preparser,
		input_item_t *	item,
		int	type_option,
		const input_item_parser_cbs_t *	cbs,
		void *	cbs_userdata
	)

This function enqueues the provided item to be preparsed or fetched.

The input item is retained until the preparsing is done or until the preparser object is deleted.

Parameters

preparser	the preparser object
item	a valid item to preparse
type_option	a combination of VLC_PREPARSER_TYPE_* and VLC_PREPARSER_OPTION_* flags. The type must be in the set specified in vlc_preparser_New() (it is possible to select less types).
cbs	callback to listen to events (can't be NULL)
cbs_userdata	opaque pointer used by the callbacks
id	unique id provided by the caller. This is can be used to cancel the request with vlc_preparser_Cancel()

Returns

VLC_PREPARSER_REQ_ID_INVALID in case of error, or a valid id if the item was scheduled for preparsing. If this returns an error, the on_preparse_ended will not be invoked

References vlc_input_thread_cfg::cbs, Fetch(), vlc_preparser_t::fetcher, task::id, task::item, vlc_preparser_t::lock, vlc_preparser_cbs::parser, vlc_preparser_t::parser, ParserRun(), task::preparser, PreparserAddTask(), PreparserGetNextTaskIdLocked(), task::runnable, TaskNew(), vlc_executor_Submit(), vlc_mutex_lock(), vlc_mutex_unlock(), VLC_PREPARSER_REQ_ID_INVALID, VLC_PREPARSER_TYPE_FETCHMETA_ALL, VLC_PREPARSER_TYPE_PARSE, VLC_PREPARSER_TYPE_THUMBNAIL, VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES, and VLC_SUCCESS.

Referenced by vlc_media_tree_Preparse(), and vlc_playlist_AutoPreparse().

vlc_preparser_SetTimeout()

void vlc_preparser_SetTimeout	(	vlc_preparser_t *	preparser,
		vlc_tick_t	timeout
	)

Do not use, libVLC only fonction, will be removed soon.

References task::preparser, and vlc_preparser_t::timeout.