libvlc_downloader_t is an abstract representation of a downloader More...

Collaboration diagram for LibVLC downloader:

Files
file	libvlc_downloader.h
	LibVLC downloader API.

Data Structures
struct	libvlc_downloader_cbs
	Downloader callbacks. More...
struct	libvlc_downloader_request_t
	struct defining a downloader request More...
struct	libvlc_downloader_cfg
	struct defining downloader configuration More...

Macros
#define	LIBVLC_DOWNLOADER_CB_ERROR ((ptrdiff_t)-1)
	Sentinel return value to signal an error in the download (to be returned by on_buffer callback).
#define	LIBVLC_DOWNLOADER_CB_CANCEL ((ptrdiff_t)-2)
	Sentinel return value to cancel the download (to be returned by on_buffer callback).

Typedefs
typedef struct libvlc_downloader_t	libvlc_downloader_t
typedef struct libvlc_downloader_request_t	libvlc_downloader_request_t
	A downloader request object.
typedef struct libvlc_downloader_task	libvlc_downloader_task
	Opaque handle of a downloader task.
typedef enum libvlc_downloader_status_t	libvlc_downloader_status_t
	Downloader status.

Enumerations
enum	libvlc_downloader_status_t { libvlc_downloader_status_pending , libvlc_downloader_status_running , libvlc_downloader_status_paused , libvlc_downloader_status_finished , libvlc_downloader_status_cancelled , libvlc_downloader_status_error }
	Downloader status. More...

Functions
libvlc_downloader_t *	libvlc_downloader_new (libvlc_instance_t inst, const struct libvlc_downloader_cfg cfg)
	Create a downloader instance.
libvlc_downloader_task *	libvlc_downloader_queue (libvlc_downloader_t downloader, const libvlc_downloader_request_t req, const struct libvlc_downloader_cbs cbs, void cbs_opaque)
	Download a media asynchronously.
size_t	libvlc_downloader_cancel (libvlc_downloader_t downloader, libvlc_downloader_task task)
	Cancel an ongoing download.
void	libvlc_downloader_set_pause (libvlc_downloader_t downloader, libvlc_downloader_task task, bool paused)
	Toggle pause/resume for the download.
void	libvlc_downloader_destroy (libvlc_downloader_t *downloader)
	Destroy a downloader and free resources.
libvlc_media_t *	libvlc_downloader_task_get_media (libvlc_downloader_task *task)
	Get the media associated with the downloader request handle.
void	libvlc_downloader_task_release (libvlc_downloader_task *task)
	Release a downloader task handle.

Detailed Description

libvlc_downloader_t is an abstract representation of a downloader

Macro Definition Documentation

◆ LIBVLC_DOWNLOADER_CB_CANCEL

#define LIBVLC_DOWNLOADER_CB_CANCEL ((ptrdiff_t)-2)

Sentinel return value to cancel the download (to be returned by on_buffer callback).

◆ LIBVLC_DOWNLOADER_CB_ERROR

#define LIBVLC_DOWNLOADER_CB_ERROR ((ptrdiff_t)-1)

Sentinel return value to signal an error in the download (to be returned by on_buffer callback).

Typedef Documentation

◆ libvlc_downloader_request_t

typedef struct libvlc_downloader_request_t libvlc_downloader_request_t

A downloader request object.

◆ libvlc_downloader_status_t

typedef enum libvlc_downloader_status_t libvlc_downloader_status_t

Downloader status.

◆ libvlc_downloader_t

typedef struct libvlc_downloader_t libvlc_downloader_t

◆ libvlc_downloader_task

typedef struct libvlc_downloader_task libvlc_downloader_task

Opaque handle of a downloader task.

Identifies a task request submitted via libvlc_downloader_queue(). It can be passed to libvlc_downloader_cancel() to cancel that request, or to libvlc_downloader_set_pause() to pause/resume that request.

Note: Validity starts when libvlc_downloader_queue() returns a non-NULL handle and ends with libvlc_downloader_task_release().

Enumeration Type Documentation

◆ libvlc_downloader_status_t

enum libvlc_downloader_status_t

Downloader status.

Enumerator
libvlc_downloader_status_pending	download pending
libvlc_downloader_status_running	active download in progress (not paused)
libvlc_downloader_status_paused	download paused
libvlc_downloader_status_finished	download finished
libvlc_downloader_status_cancelled	download cancelled
libvlc_downloader_status_error	download error occurred

Function Documentation

◆ libvlc_downloader_cancel()

size_t libvlc_downloader_cancel	(	libvlc_downloader_t *	downloader,
		libvlc_downloader_task *	task )

Cancel an ongoing download.

Parameters

downloader	downloader instance
task	a downloader task returned by libvlc_downloader_queue(), or NULL to cancel all requests.

Returns: the number of requests cancelled

Note

This function is valid only if the request is in one of the following states: pending, running, or paused.
When a request is cancelled, the on_state_update callback will be triggered with the cancelled state.
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.

Version: LibVLC 4.0.0 or later

References LIBVLC_API.

◆ libvlc_downloader_destroy()

void libvlc_downloader_destroy ( libvlc_downloader_t * downloader )

Destroy a downloader and free resources.

All pending, running and paused downloads are cancelled. Waits for all download threads to join.

Parameters

downloader downloader instance

Version: LibVLC 4.0.0 or later

References LIBVLC_API.

◆ libvlc_downloader_new()

libvlc_downloader_t * libvlc_downloader_new	(	libvlc_instance_t *	inst,
		const struct libvlc_downloader_cfg *	cfg )

Create a downloader instance.

Supports downloading files over a limited set of protocols: http(s), ftp, file, nfs, smb, sftp

The downloader must be released by calling libvlc_downloader_destroy() when it is no longer needed.

Parameters

inst	LibVLC instance
cfg	a pointer to a valid downloader configuration struct

Returns: downloader instance or NULL on error

Version: LibVLC 4.0.0 or later

References LIBVLC_API.

◆ libvlc_downloader_queue()

libvlc_downloader_task * libvlc_downloader_queue	(	libvlc_downloader_t *	downloader,
		const libvlc_downloader_request_t *	req,
		const struct libvlc_downloader_cbs *	cbs,
		void *	cbs_opaque )

Download a media asynchronously.

The downloader first parses the media.
If the media has subitems, the user will be notified via the on_subitems callback.
If the media has slaves, the user will be notified via the on_slaves callback.
If the media is not a file type, the download will not proceed.
See also
libvlc_media_type_t, and the user will be notified via the on_state_update callback.
If the media is a file type with finite size, the download starts in a separate thread.

Parameters

downloader	downloader instance
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_downloader_cbs.on_state_update() is called for the returned task handle with a terminal state (finished/cancelled/error).
cbs_opaque	opaque pointer for callbacks

Returns: NULL in case of error, or a valid handle if the request was scheduled for downloading.

Note: No callbacks will be invoked if the return value is NULL.

Version: LibVLC 4.0.0 or later

◆ libvlc_downloader_set_pause()

void libvlc_downloader_set_pause	(	libvlc_downloader_t *	downloader,
		libvlc_downloader_task *	task,
		bool	paused )

Toggle pause/resume for the download.

Parameters

downloader	downloader instance
task	a valid downloader task returned by libvlc_downloader_queue()
paused	true to pause, false to resume

Note: This API is valid only when the download is in pending/running/paused state. And the on_state_update callback with paused/running state will be called only during these state changes. Else, for finished/cancelled/error states, it's a no-op and no callback will be called.

Version: LibVLC 4.0.0 or later

References LIBVLC_API.

◆ libvlc_downloader_task_get_media()

libvlc_media_t * libvlc_downloader_task_get_media ( libvlc_downloader_task * task )

Get the media associated with the downloader request handle.

Parameters

task	opaque handle returned by libvlc_downloader_queue()

Returns: the media associated with the request handle.

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

Version: LibVLC 4.0.0 or later

◆ libvlc_downloader_task_release()

void libvlc_downloader_task_release ( libvlc_downloader_task * task )

Release a downloader task handle.

Parameters

task	the downloader task handle

Note

The task handle is retained when returned by libvlc_downloader_queue().
Mandatory to call to avoid memory leaks.
It is safe to call this API from within the on_state_update callback, when it reports a terminal state (finished, cancelled, error)

See also: libvlc_downloader_status_t.

The task handle should not be used after calling this function.
If called on an active task, it doesn't cancel the task, use libvlc_downloader_cancel() for that.

Version: LibVLC 4.0.0 or later

References LIBVLC_API.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LIBVLC_DOWNLOADER_CB_CANCEL

◆ LIBVLC_DOWNLOADER_CB_ERROR

Typedef Documentation

◆ libvlc_downloader_request_t

◆ libvlc_downloader_status_t

◆ libvlc_downloader_t

◆ libvlc_downloader_task

Enumeration Type Documentation

◆ libvlc_downloader_status_t

Function Documentation

◆ libvlc_downloader_cancel()

◆ libvlc_downloader_destroy()

◆ libvlc_downloader_new()

◆ libvlc_downloader_queue()

◆ libvlc_downloader_set_pause()

◆ libvlc_downloader_task_get_media()

◆ libvlc_downloader_task_release()