LibVLC downloader

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_task_new (libvlc_downloader_t *downloader, const libvlc_downloader_request_t *req, const struct libvlc_downloader_cbs *cbs, void *cbs_opaque)
	Create a media download task.
int	libvlc_downloader_submit (libvlc_downloader_t *downloader, libvlc_downloader_task *task)
	Start a task created by libvlc_downloader_task_new().
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 created by libvlc_downloader_task_new() and started with libvlc_downloader_submit(). 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_task_new() 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_task_new(), or NULL to cancel all submitted 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), or if it was never submitted, 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_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_task_new()
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.

Pausing a pending task (including one not submitted yet) does not pause parsing. The on_subitems and on_slaves callbacks are still invoked, if available. If the download starts, the paused state is reported before any data is read (without a prior running state), and nothing is downloaded until the task is resumed.

Version

LibVLC 4.0.0 or later

References LIBVLC_API.

libvlc_downloader_submit()

int libvlc_downloader_submit	(	libvlc_downloader_t *	downloader,
		libvlc_downloader_task *	task )

Start a task created by libvlc_downloader_task_new().

• 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.

On success the task is scheduled and the callbacks are guaranteed to be called and the task will eventually report a terminal state (finished/cancelled/error). That callback may run even before this function returns.

Note

On failure no callback is invoked. The caller keeps its reference and may submit the task again.

A task may be submitted at most once, and may only be re-submitted if the previous attempt failed. Submitting does not transfer the caller's reference. It keeps owning the handle and must release it.

Parameters

downloader	the downloader the task was created from
task	a task that has not yet been successfully submitted

Returns

0 on success, -1 on error

Version

LibVLC 4.0.0 or later

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_task_new()

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_new()

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

Create a media download task.

This prepares a task handle for downloading a media. Nothing runs and no callback can fire until the handle is passed to libvlc_downloader_submit().

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 task handle owned by the caller. It must be released with libvlc_downloader_task_release(), whether or not it is submitted.

Version

LibVLC 4.0.0 or later

References LIBVLC_API.

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 libvlc_downloader_task_new() call transfers the ownership of the task handle to the caller. It must be released whether or not it was submitted.
• 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.

• It is safe to call this API at any time, including after libvlc_downloader_destroy() has been called on the downloader that created it. 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.