Preparser

Collaboration diagram for Preparser:

Files
file	vlc_preparser.h
	VLC Preparser API.

Data Structures
struct	vlc_preparser_cbs
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_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 struct vlc_preparser_req	vlc_preparser_req
	Preparser request opaque handle.

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 *	vlc_preparser_Push (vlc_preparser_t *preparser, input_item_t *item, int type_option, const struct vlc_preparser_cbs *cbs, void *cbs_userdata)
	This function enqueues the provided item to be preparsed or fetched.
vlc_preparser_req *	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 *	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 *req)
	This function cancels ongoing or queued preparsing/thumbnail generation for a given request handle.
input_item_t *	vlc_preparser_req_GetItem (vlc_preparser_req *req)
	Fetch the input item associated with the request.
void	vlc_preparser_req_Release (vlc_preparser_req *req)
	Release a preparser request handle.
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_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

typedef struct vlc_preparser_req vlc_preparser_req

Preparser request opaque handle.

Identifies a request submitted via vlc_preparser_Push(), vlc_preparser_GenerateThumbnail(), or vlc_preparser_GenerateThumbnailToFiles(). It can be passed to vlc_preparser_Cancel() to cancel that request.

Note

• Validity starts when a submit function returns a non-NULL handle and ends with vlc_preparser_req_Release().
• The user must ensure that callbacks and their context remain valid until request termination.

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 *	req
	)

This function cancels ongoing or queued preparsing/thumbnail generation for a given request handle.

Parameters

preparser	the preparser object
req	request handle returned by vlc_preparser_Push(), vlc_preparser_GenerateThumbnail(), or vlc_preparser_GenerateThumbnailToFiles(). Pass NULL to cancel all pending and running tasks.

Returns

number of tasks cancelled

Note

• When a request is cancelled, the on_ended callback will be triggered with -EINTR status.
• If the request is already in a terminated state (finished, cancelled, or error), the call is a no-op and no callback will be invoked.

References vlc_preparser_req::cbs, count, Interrupt(), vlc_preparser_t::lock, vlc_preparser_req::node, vlc_thumbnailer_to_files_cbs::on_ended, vlc_thumbnailer_cbs::on_ended, vlc_preparser_cbs::on_ended, vlc_preparser_req::options, vlc_preparser_cbs_internal::parser, vlc_preparser_t::parser, vlc_preparser_req::preparse_status, vlc_preparser_req::preparser, vlc_preparser_req::runnable, vlc_preparser_t::submitted_tasks, vlc_preparser_cbs_internal::thumbnailer, vlc_preparser_t::thumbnailer, vlc_preparser_cbs_internal::thumbnailer_to_files, vlc_preparser_t::thumbnailer_to_files, vlc_preparser_req::userdata, vlc_executor_Cancel(), vlc_list_foreach, vlc_list_remove(), vlc_mutex_lock(), vlc_mutex_unlock(), vlc_preparser_req_Release(), VLC_PREPARSER_TYPE_FETCHMETA_ALL, VLC_PREPARSER_TYPE_PARSE, VLC_PREPARSER_TYPE_THUMBNAIL, and VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES.

Referenced by vlc_playlist_Clear(), vlc_playlist_Remove(), vlc_playlist_Replace(), and 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, vlc_preparser_req::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 * 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

NULL in case of error, or a valid request handle 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 vlc_preparser_req::cbs, vlc_preparser_req::item, vlc_preparser_req::preparser, PreparserAddTask(), PreparserRequestNew(), PreparserRequestRetain(), vlc_preparser_req::runnable, vlc_preparser_req::thumb_arg, vlc_preparser_cbs_internal::thumbnailer, vlc_preparser_t::thumbnailer, ThumbnailerRun(), vlc_executor_Submit(), and VLC_PREPARSER_TYPE_THUMBNAIL.

vlc_preparser_GenerateThumbnailToFiles()

vlc_preparser_req * 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

NULL in case of error, or a valid request handle 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, vlc_preparser_req::item, msg_Err, vlc_thumbnailer_to_files_cbs::on_ended, vlc_preparser_req::output_count, vlc_preparser_req::outputs, vlc_preparser_t::owner, vlc_preparser_req::preparser, PreparserAddTask(), PreparserRequestDelete(), PreparserRequestNew(), PreparserRequestRetain(), vlc_preparser_req::runnable, strdup(), vlc_preparser_req::thumb_arg, vlc_preparser_t::thumbnailer, vlc_preparser_cbs_internal::thumbnailer_to_files, ThumbnailerRun(), unlikely, vlc_alloc(), VLC_CODEC_UNKNOWN, vlc_executor_Submit(), 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::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_req::preparser, 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 * vlc_preparser_Push	(	vlc_preparser_t *	preparser,
		input_item_t *	item,
		int	type_option,
		const struct vlc_preparser_cbs *	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

Returns

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

References vlc_preparser_req::cbs, Fetch(), vlc_preparser_t::fetcher, vlc_preparser_req::item, vlc_preparser_cbs_internal::parser, vlc_preparser_t::parser, ParserRun(), vlc_preparser_req::preparser, PreparserAddTask(), PreparserRequestNew(), PreparserRequestRetain(), vlc_preparser_req::runnable, vlc_executor_Submit(), 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_req_GetItem()

input_item_t * vlc_preparser_req_GetItem

(

vlc_preparser_req *

req

)

Fetch the input item associated with the request.

Parameters

req	request handle returned by vlc_preparser_Push(), vlc_preparser_GenerateThumbnail(), or vlc_preparser_GenerateThumbnailToFiles().

Returns

input_item_t associated with the request

Note

The returned input item is held by the request, it must not be released by the caller.

References vlc_preparser_req::item.

Referenced by media_subtree_changed(), media_subtree_preparse_ended(), and on_preparse_ended().

vlc_preparser_req_Release()

void vlc_preparser_req_Release

(

vlc_preparser_req *

req

)

Release a preparser request handle.

Parameters

req	the preparser request handle

Note

• The request handle is retained when returned by a submit function.
• Mandatory to call to avoid memory leaks.
• It is safe to call this API from within the on_ended callback.
• The request handle should not be used after calling this function.
• If called on an active request, it doesn't cancel the preparsing request, use vlc_preparser_Cancel() for that.

References PreparserRequestDelete(), vlc_preparser_req::rc, and vlc_atomic_rc_dec().

Referenced by media_subtree_preparse_ended(), on_preparse_ended(), OnArtFetchEnded(), ParserRun(), ThumbnailerRun(), ThumbnailerToFilesRun(), and vlc_preparser_Cancel().

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 vlc_preparser_req::preparser, and vlc_preparser_t::timeout.