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 , VLC_THUMBNAILER_FORMAT_RGBA , VLC_THUMBNAILER_FORMAT_ARGB }
	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.
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_req_NewParse (vlc_preparser_t preparser, input_item_t item, int type_option, const struct vlc_preparser_cbs cbs, void cbs_userdata)
	Create a parse/fetch request.
vlc_preparser_req *	vlc_preparser_req_NewThumbnail (vlc_preparser_t preparser, input_item_t item, const struct vlc_thumbnailer_arg arg, const struct vlc_thumbnailer_cbs cbs, void *cbs_userdata)
	Create a thumbnail generation request.
vlc_preparser_req *	vlc_preparser_req_NewThumbnailToFiles (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)
	Create a request generating a thumbnail to one or several files.
int	vlc_preparser_Submit (vlc_preparser_t preparser, vlc_preparser_req req)
	Submit a request created by one of the vlc_preparser_req_New*() functions.
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.

Detailed Description

Macro Definition Documentation

◆ VLC_PREPARSER_OPTION_INTERACT

#define VLC_PREPARSER_OPTION_INTERACT 0x1000

Referenced by Parse(), and vlc_media_tree_Preparse().

◆ VLC_PREPARSER_OPTION_SUBITEMS

#define VLC_PREPARSER_OPTION_SUBITEMS 0x2000

Referenced by Parse(), vlc_media_tree_Preparse(), and vlc_playlist_AutoPreparse().

◆ VLC_PREPARSER_TYPE_FETCHMETA_ALL

#define VLC_PREPARSER_TYPE_FETCHMETA_ALL (VLC_PREPARSER_TYPE_FETCHMETA_LOCAL|VLC_PREPARSER_TYPE_FETCHMETA_NET)

Referenced by Fetch(), input_fetcher_New(), input_fetcher_Push(), preparser_Cancel(), preparser_req_NewParse(), and vlc_preparser_internal_New().

◆ VLC_PREPARSER_TYPE_FETCHMETA_LOCAL

#define VLC_PREPARSER_TYPE_FETCHMETA_LOCAL 0x02

Referenced by input_fetcher_New(), input_fetcher_Push(), vlc_playlist_AutoPreparse(), and vlc_playlist_New().

◆ VLC_PREPARSER_TYPE_FETCHMETA_NET

#define VLC_PREPARSER_TYPE_FETCHMETA_NET 0x04

Referenced by input_fetcher_New(), input_fetcher_Push(), and RunSearchLocal().

◆ VLC_PREPARSER_TYPE_PARSE

#define VLC_PREPARSER_TYPE_PARSE 0x01

Referenced by ParserRun(), preparser_Cancel(), preparser_req_NewParse(), vlc_media_tree_Preparse(), vlc_playlist_AutoPreparse(), vlc_playlist_New(), vlc_preparser_external_New(), and vlc_preparser_internal_New().

◆ VLC_PREPARSER_TYPE_THUMBNAIL

#define VLC_PREPARSER_TYPE_THUMBNAIL 0x08

Referenced by preparser_Cancel(), preparser_req_NewParse(), preparser_req_NewThumbnail(), preparser_Submit(), ThumbnailerRun(), vlc_preparser_external_New(), and vlc_preparser_internal_New().

◆ VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES

#define VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES 0x10

Referenced by preparser_Cancel(), preparser_req_NewParse(), preparser_req_NewThumbnailToFiles(), preparser_Submit(), PreparserRequestNew(), ThumbnailerRun(), vlc_preparser_external_New(), and vlc_preparser_internal_New().

Typedef Documentation

◆ vlc_preparser_req

typedef struct vlc_preparser_req vlc_preparser_req

Preparser request opaque handle.

Identifies a request created by vlc_preparser_req_NewParse(), vlc_preparser_req_NewThumbnail() or vlc_preparser_req_NewThumbnailToFiles() and started with vlc_preparser_Submit(). It can be passed to vlc_preparser_Cancel() to cancel that request.

Note

Ownership of the handle is transferred to the caller by the vlc_preparser_req_New*() functions. The caller must release it with vlc_preparser_req_Release() once it is no longer needed, whether or not it was submitted.
The caller must ensure that the callbacks and their context remain valid until the request terminates.

◆ 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
VLC_THUMBNAILER_FORMAT_RGBA
VLC_THUMBNAILER_FORMAT_ARGB

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 a vlc_preparser_req_New*() function. 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.
That callback may run synchronously, on the thread calling this function, if the request had not started yet. The caller must be careful not to hold any lock that the callback needs, or it will deadlock against itself.
If the request is already in a terminated state (finished, cancelled or error), or if it was never submitted, the call is a no-op and no callback will be invoked.

References vlc_preparser_operations::cancel, vlc_preparser_t::ops, and vlc_preparser_t::sys.

Referenced by vlc_playlist_Clear(), vlc_playlist_Remove(), and vlc_playlist_Replace().

◆ 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_operations::delete, vlc_preparser_t::ops, and vlc_preparser_t::sys.

Referenced by vlc_playlist_Delete(), and vlc_playlist_New().

◆ 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_cfg::external_process, msg_Err, vlc_preparser_t::sys, vlc_preparser_external_New(), and vlc_preparser_internal_New().

Referenced by vlc_playlist_New().

◆ 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 a vlc_preparser_req_New*() function.

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_operations::get_item, and vlc_preparser_req::ops.

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

◆ vlc_preparser_req_NewParse()

vlc_preparser_req * vlc_preparser_req_NewParse	(	vlc_preparser_t *	preparser,
		input_item_t *	item,
		int	type_option,
		const struct vlc_preparser_cbs *	cbs,
		void *	cbs_userdata )

Create a parse/fetch request.

The request is created idle, nothing runs and no callback can fire until it is handed to vlc_preparser_Submit(). The caller owns the returned handle from the moment this function returns.

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: a request handle owned by the caller, or NULL in case of error. It must be released with vlc_preparser_req_Release(), whether or not it is submitted.

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

References vlc_preparser_t::ops, vlc_preparser_operations::req_new_parse, and vlc_preparser_t::sys.

Referenced by vlc_media_tree_Preparse(), and vlc_playlist_AutoPreparse().

◆ vlc_preparser_req_NewThumbnail()

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

Create a thumbnail generation request.

The request is created idle, nothing runs and no callback can fire until it is handed to vlc_preparser_Submit(). The caller owns the returned handle from the moment this function returns.

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: a request handle owned by the caller, or NULL in case of error. It must be released with vlc_preparser_req_Release(), whether or not it is submitted.

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

References vlc_preparser_t::ops, vlc_preparser_operations::req_new_thumbnail, and vlc_preparser_t::sys.

◆ vlc_preparser_req_NewThumbnailToFiles()

vlc_preparser_req * vlc_preparser_req_NewThumbnailToFiles	(	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 )

Create a request generating a thumbnail to one or several files.

The request is created idle, nothing runs and no callback can fire until it is handed to vlc_preparser_Submit(). The caller owns the returned handle from the moment this function returns.

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 > 0
cbs	callback to listen to events (can't be NULL)
cbs_userdata	opaque pointer used by the callbacks

Returns: a request handle owned by the caller, or NULL in case of error. It must be released with vlc_preparser_req_Release(), whether or not it is submitted.

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

References vlc_preparser_t::ops, vlc_preparser_operations::req_new_thumbnail_to_files, and vlc_preparser_t::sys.

◆ 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

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 vlc_preparser_req::ops, and vlc_preparser_req_operations::release.

Referenced by OnArtFetchEnded(), ParserRun(), preparser_Cancel(), preparser_Submit(), ThumbnailerRun(), ThumbnailerToFilesRun(), vlc_media_tree_Preparse(), vlc_playlist_AutoPreparse(), and vlc_playlist_item_Release().

◆ vlc_preparser_Submit()

int vlc_preparser_Submit	(	vlc_preparser_t *	preparser,
		vlc_preparser_req *	req )

Submit a request created by one of the vlc_preparser_req_New*() functions.

Parameters

preparser	the preparser object the request was created from
req	a request handle that has never been submitted successfully

Returns: VLC_SUCCESS if the request was queued, VLC_EGENERIC otherwise

Note

On success the on_ended callback is guaranteed to be invoked exactly once. It may be invoked even before this function returns.
On failure the request was not queued and no callback will be invoked. The caller keeps its reference and may submit the request again.
A request may be submitted at most once, and may only be re-submitted if the previous attempt failed. Submitting a request that was already queued successfully is undefined behaviour.
Submitting the same request concurrently from several threads is undefined behaviour.

References vlc_preparser_t::ops, vlc_preparser_operations::submit, vlc_preparser_req::submitted, vlc_preparser_t::sys, and VLC_SUCCESS.

Referenced by vlc_media_tree_Preparse(), and vlc_playlist_AutoPreparse().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ VLC_PREPARSER_OPTION_INTERACT

◆ VLC_PREPARSER_OPTION_SUBITEMS

◆ VLC_PREPARSER_TYPE_FETCHMETA_ALL

◆ VLC_PREPARSER_TYPE_FETCHMETA_LOCAL

◆ VLC_PREPARSER_TYPE_FETCHMETA_NET

◆ VLC_PREPARSER_TYPE_PARSE

◆ VLC_PREPARSER_TYPE_THUMBNAIL

◆ VLC_PREPARSER_TYPE_THUMBNAIL_TO_FILES

Typedef Documentation

◆ vlc_preparser_req

◆ vlc_preparser_t

Enumeration Type Documentation

◆ vlc_thumbnailer_format

Function Documentation

◆ vlc_preparser_Cancel()

◆ vlc_preparser_CheckThumbnailerFormat()

◆ vlc_preparser_Delete()

◆ vlc_preparser_GetBestThumbnailerFormat()

◆ vlc_preparser_New()

◆ vlc_preparser_req_GetItem()

◆ vlc_preparser_req_NewParse()

◆ vlc_preparser_req_NewThumbnail()

◆ vlc_preparser_req_NewThumbnailToFiles()

◆ vlc_preparser_req_Release()

◆ vlc_preparser_Submit()