LibVLC parser

libvlc_parser_t is an abstract representation of a parser More...

Collaboration diagram for LibVLC parser:

Files
file	libvlc_parser.h
	LibVLC parser API.

Data Structures
union	libvlc_thumbnailer_seek_value_t
	Thumbnailer seek value. More...
struct	libvlc_parser_cbs
	struct defining callbacks for libvlc_parser_queue More...
struct	libvlc_parser_request_t
	struct defining a parse request More...
struct	libvlc_thumbnailer_cbs
	struct defining callbacks for libvlc_parser_queue_thumbnailing More...
struct	libvlc_thumbnailer_request_t
	struct defining a thumbnailer request More...
struct	libvlc_parser_cfg
	struct defining parser configuration More...

Typedefs
typedef struct libvlc_parser_t	libvlc_parser_t
typedef struct libvlc_media_t	libvlc_media_t
typedef struct libvlc_picture_list_t	libvlc_picture_list_t
typedef struct libvlc_picture_t	libvlc_picture_t
typedef enum libvlc_picture_type_t	libvlc_picture_type_t
typedef struct libvlc_parser_request_t	libvlc_parser_request_t
	A parser request object.
typedef struct libvlc_thumbnailer_request_t	libvlc_thumbnailer_request_t
	A thumbnailer request object.
typedef struct libvlc_parser_task	libvlc_parser_task
	Opaque handle of a parsing/thumbnailing task.
typedef enum libvlc_media_parse_flag_t	libvlc_media_parse_flag_t
	Parse flags used by libvlc_parser_request_t.
typedef enum libvlc_parser_status_t	libvlc_parser_status_t
	Outcome of a finished parse request, reported by libvlc_parser_cbs::on_parsed.
typedef enum libvlc_thumbnailer_seek_type_t	libvlc_thumbnailer_seek_type_t
	Thumbnailer seek type.
typedef enum libvlc_thumbnailer_seek_speed_t	libvlc_thumbnailer_seek_speed_t
	Thumbnailer seek speed.
typedef union libvlc_thumbnailer_seek_value_t	libvlc_thumbnailer_seek_value_t
	Thumbnailer seek value.

Enumerations
enum	libvlc_media_parse_flag_t { libvlc_media_parse = 0x01 , libvlc_media_fetch_local = 0x02 , libvlc_media_fetch_network = 0x04 , libvlc_media_do_interact = 0x08 }
	Parse flags used by libvlc_parser_request_t. More...
enum	libvlc_parser_status_t { libvlc_parser_status_failed , libvlc_parser_status_timeout , libvlc_parser_status_cancelled , libvlc_parser_status_done }
	Outcome of a finished parse request, reported by libvlc_parser_cbs::on_parsed. More...
enum	libvlc_thumbnailer_seek_type_t { libvlc_thumbnailer_seek_none , libvlc_thumbnailer_seek_time , libvlc_thumbnailer_seek_pos }
	Thumbnailer seek type. More...
enum	libvlc_thumbnailer_seek_speed_t { libvlc_media_thumbnail_seek_precise , libvlc_media_thumbnail_seek_fast }
	Thumbnailer seek speed. More...

Functions
libvlc_parser_t *	libvlc_parser_new (libvlc_instance_t *inst, const struct libvlc_parser_cfg *cfg)
	Create a parser.
void	libvlc_parser_destroy (libvlc_parser_t *parser)
	Destroy a parser and free resources.
libvlc_parser_task *	libvlc_parser_queue (libvlc_parser_t *parser, const libvlc_parser_request_t *req, const struct libvlc_parser_cbs *cbs, void *cbs_opaque)
	Parse a media asynchronously.
libvlc_parser_task *	libvlc_parser_queue_thumbnailing (libvlc_parser_t *parser, const libvlc_thumbnailer_request_t *req, const struct libvlc_thumbnailer_cbs *cbs, void *cbs_opaque)
	Generate a thumbnail asynchronously.
size_t	libvlc_parser_cancel_request (libvlc_parser_t *parser, libvlc_parser_task *task)
	Cancel a parser request.
libvlc_media_t *	libvlc_parser_task_get_media (libvlc_parser_task *task)
	Fetch the media associated with the task handle.
void	libvlc_parser_task_release (libvlc_parser_task *task)
	Release a parser task handle.

Detailed Description

libvlc_parser_t is an abstract representation of a parser

Typedef Documentation

libvlc_media_parse_flag_t

typedef enum libvlc_media_parse_flag_t libvlc_media_parse_flag_t

Parse flags used by libvlc_parser_request_t.

libvlc_media_t

typedef struct libvlc_media_t libvlc_media_t

libvlc_parser_request_t

typedef struct libvlc_parser_request_t libvlc_parser_request_t

A parser request object.

libvlc_parser_status_t

typedef enum libvlc_parser_status_t libvlc_parser_status_t

Outcome of a finished parse request, reported by libvlc_parser_cbs::on_parsed.

libvlc_parser_t

typedef struct libvlc_parser_t libvlc_parser_t

libvlc_parser_task

typedef struct libvlc_parser_task libvlc_parser_task

Opaque handle of a parsing/thumbnailing task.

Identifies a task request submitted via libvlc_parser_queue() or libvlc_parser_queue_thumbnailing(). It can be passed to libvlc_parser_cancel_request() to cancel that request.

Note

Validity starts when a submit function returns a non-NULL handle and ends with libvlc_parser_task_release().

libvlc_picture_list_t

typedef struct libvlc_picture_list_t libvlc_picture_list_t

libvlc_picture_t

typedef struct libvlc_picture_t libvlc_picture_t

libvlc_picture_type_t

typedef enum libvlc_picture_type_t libvlc_picture_type_t

libvlc_thumbnailer_request_t

typedef struct libvlc_thumbnailer_request_t libvlc_thumbnailer_request_t

A thumbnailer request object.

libvlc_thumbnailer_seek_speed_t

typedef enum libvlc_thumbnailer_seek_speed_t libvlc_thumbnailer_seek_speed_t

Thumbnailer seek speed.

libvlc_thumbnailer_seek_type_t

typedef enum libvlc_thumbnailer_seek_type_t libvlc_thumbnailer_seek_type_t

Thumbnailer seek type.

libvlc_thumbnailer_seek_value_t

typedef union libvlc_thumbnailer_seek_value_t libvlc_thumbnailer_seek_value_t

Thumbnailer seek value.

The active member is selected based on the associated libvlc_thumbnailer_seek_type_t.

Enumeration Type Documentation

libvlc_media_parse_flag_t

enum libvlc_media_parse_flag_t

Parse flags used by libvlc_parser_request_t.

Enumerator
libvlc_media_parse	Parse media.
libvlc_media_fetch_local	Fetch meta and cover art using local resources.
libvlc_media_fetch_network	Fetch meta and cover art using network resources.
libvlc_media_do_interact	Interact with the user (via libvlc_dialog_cbs) when preparsing this item (and not its sub items). Set this flag in order to receive a callback when the input is asking for credentials.

libvlc_parser_status_t

enum libvlc_parser_status_t

Outcome of a finished parse request, reported by libvlc_parser_cbs::on_parsed.

Enumerator
libvlc_parser_status_failed	The parsing failed.
libvlc_parser_status_timeout	The parsing timed out.
libvlc_parser_status_cancelled	The parsing was cancelled.
libvlc_parser_status_done	The parsing completed successfully.

libvlc_thumbnailer_seek_speed_t

enum libvlc_thumbnailer_seek_speed_t

Thumbnailer seek speed.

Enumerator
libvlc_media_thumbnail_seek_precise	Precise, but potentially slow.
libvlc_media_thumbnail_seek_fast	Fast, but potentially imprecise.

libvlc_thumbnailer_seek_type_t

enum libvlc_thumbnailer_seek_type_t

Thumbnailer seek type.

Enumerator
libvlc_thumbnailer_seek_none	Don't seek (default).
libvlc_thumbnailer_seek_time	Seek by time.
libvlc_thumbnailer_seek_pos	Seek by position.

Function Documentation

libvlc_parser_cancel_request()

size_t libvlc_parser_cancel_request	(	libvlc_parser_t *	parser,
		libvlc_parser_task *	task )

Cancel a parser request.

Parameters

parser	the parser
task	A parser task returned by libvlc_parser_queue(), libvlc_parser_queue_thumbnailing() or NULL to cancel all requests.

Returns

the number of requests cancelled

Note

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

Version

libvlc 4.0.0 or later

References LIBVLC_API.

libvlc_parser_destroy()

void libvlc_parser_destroy

(

libvlc_parser_t *

parser

)

Destroy a parser and free resources.

All pending and running tasks are cancelled, and reported as cancelled via callback. This API waits for all worker threads to join.

Note

It is safe to call this API while tasks are still running or pending.

Parameters

parser

the parser

Version

libvlc 4.0.0 or later

References LIBVLC_API.

libvlc_parser_new()

libvlc_parser_t * libvlc_parser_new	(	libvlc_instance_t *	inst,
		const struct libvlc_parser_cfg *	cfg )

Create a parser.

Parameters

inst	LibVLC instance to create parser with
cfg	a pointer to a valid configuration struct

Returns

a new parser object, or NULL on error. It must be released by libvlc_parser_destroy().

Version

libvlc 4.0.0 or later

libvlc_parser_queue()

libvlc_parser_task * libvlc_parser_queue	(	libvlc_parser_t *	parser,
		const libvlc_parser_request_t *	req,
		const struct libvlc_parser_cbs *	cbs,
		void *	cbs_opaque )

Parse a media asynchronously.

This fetches (local or network) art, meta data and/or tracks information.

Note

It is possible to cancel the request with libvlc_parser_cancel_request()

If the request is successfully queued, the libvlc_parser_cbs::on_parsed callback is guaranteed to be called

Note

A media can be parsed multiple times, for instance to refresh network metadata; a previous successful, failed, timed out or cancelled parse does not prevent re-queueing.

Parameters

parser	the parser
req	a pointer to a valid request struct
cbs	a pointer to a valid callbacks struct. The pointed struct must be kept alive (and not modified) by the caller until libvlc_parser_cbs.on_parsed is called for the returned task handle.
cbs_opaque	an opaque pointer to be passed to the callbacks

Returns

NULL in case of error, or a valid handle if the item was scheduled for parsing. If this returns NULL, the libvlc_parser_cbs::on_parsed callback will not be called.

Version

LibVLC 4.0.0 or later

References LIBVLC_API.

libvlc_parser_queue_thumbnailing()

libvlc_parser_task * libvlc_parser_queue_thumbnailing	(	libvlc_parser_t *	parser,
		const libvlc_thumbnailer_request_t *	req,
		const struct libvlc_thumbnailer_cbs *	cbs,
		void *	cbs_opaque )

Generate a thumbnail asynchronously.

Note

It is possible to cancel the request with libvlc_parser_cancel_request()

If the request is successfully queued, the libvlc_thumbnailer_cbs::on_ended callback is guaranteed to be called

Parameters

parser	the parser
req	a pointer to a valid request struct
cbs	a pointer to a valid callbacks struct. The pointed struct must be kept alive (and not modified) by the caller until libvlc_thumbnailer_cbs.on_ended is called for the returned task handle.
cbs_opaque	an opaque pointer to be passed to the callbacks

Returns

NULL in case of error, or a valid handle if the item was scheduled for thumbnailing. If this returns an error, the libvlc_thumbnailer_cbs::on_ended callback will not be called.

Version

LibVLC 4.0.0 or later

libvlc_parser_task_get_media()

libvlc_media_t * libvlc_parser_task_get_media

(

libvlc_parser_task *

task

)

Fetch the media associated with the task handle.

Parameters

task	A parser task returned by libvlc_parser_queue() or libvlc_parser_queue_thumbnailing()

Returns

libvlc_media_t associated with the task

Note

The returned media is held by the task, it must not be released by the caller.

libvlc_parser_task_release()

void libvlc_parser_task_release

(

libvlc_parser_task *

task

)

Release a parser task handle.

Parameters

task	the parser task handle

Note

• The task 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_parsed/on_ended callback.
• The task handle should not be used after calling this function.
• If called on an active request, it doesn't cancel the task, use libvlc_parser_cancel_request() for that.

References LIBVLC_API.