Media source

Collaboration diagram for Media source:

Data Structures
struct	vlc_media_tree
	Media source API aims to manage "services discovery" easily from UI clients. More...
struct	vlc_media_tree_callbacks
	Callbacks to receive media tree events. More...
struct	vlc_media_source_t
	Media source. More...
struct	vlc_media_source_meta
	Structure containing the description of a media source. More...

Typedefs
typedef struct vlc_media_tree	vlc_media_tree_t
	Media source API aims to manage "services discovery" easily from UI clients.
typedef struct vlc_media_tree_listener_id	vlc_media_tree_listener_id
	Listener for media tree events.
typedef struct vlc_media_source_t	vlc_media_source_t
	Media source.
typedef struct vlc_media_source_provider_t	vlc_media_source_provider_t
	Media source provider (opaque pointer), used to get media sources.
typedef struct vlc_media_source_meta_list	vlc_media_source_meta_list_t
	List of media source metadata (opaque).

Functions
vlc_media_tree_t *	vlc_media_tree_New (void)
	Create an empty media tree.
vlc_media_tree_listener_id *	vlc_media_tree_AddListener (vlc_media_tree_t *tree, const struct vlc_media_tree_callbacks *cbs, void *userdata, bool notify_current_state)
	Add a listener.
void	vlc_media_tree_RemoveListener (vlc_media_tree_t *tree, vlc_media_tree_listener_id *listener)
	Remove a listener.
void	vlc_media_tree_Hold (vlc_media_tree_t *tree)
	Increase the media tree reference count.
void	vlc_media_tree_Release (vlc_media_tree_t *tree)
	Decrease the media tree reference count.
void	vlc_media_tree_Lock (vlc_media_tree_t *)
	Lock the media tree (non-recursive).
void	vlc_media_tree_Unlock (vlc_media_tree_t *)
	Unlock the media tree.
input_item_node_t *	vlc_media_tree_Add (vlc_media_tree_t *tree, input_item_node_t *parent, input_item_t *media)
	Add an item to the media tree.
bool	vlc_media_tree_Remove (vlc_media_tree_t *tree, input_item_t *media)
	Remove an item from the media tree.
bool	vlc_media_tree_Find (vlc_media_tree_t *tree, const input_item_t *media, input_item_node_t **result, input_item_node_t **result_parent)
	Find the node containing the requested input item (and its parent).
void	vlc_media_tree_Preparse (vlc_media_tree_t *tree, libvlc_int_t *libvlc, input_item_t *media, void *id)
	Preparse a media, and expand it in the media tree on subitems added.
void	vlc_media_tree_PreparseCancel (libvlc_int_t *libvlc, void *id)
	Cancel a media tree preparse request.
void	vlc_media_source_Hold (vlc_media_source_t *)
	Increase the media source reference count.
void	vlc_media_source_Release (vlc_media_source_t *)
	Decrease the media source reference count.
vlc_media_source_provider_t *	vlc_media_source_provider_Get (libvlc_int_t *)
	Return the media source provider associated to the libvlc instance.
vlc_media_source_t *	vlc_media_source_provider_GetMediaSource (vlc_media_source_provider_t *, const char *name)
	Return the media source identified by psz_name.
vlc_media_source_meta_list_t *	vlc_media_source_provider_List (vlc_media_source_provider_t *, enum services_discovery_category_e category)
	Return the list of metadata of available media sources.
size_t	vlc_media_source_meta_list_Count (vlc_media_source_meta_list_t *)
	Return the number of items in the list.
struct vlc_media_source_meta *	vlc_media_source_meta_list_Get (vlc_media_source_meta_list_t *, size_t index)
	Return the item at index.
void	vlc_media_source_meta_list_Delete (vlc_media_source_meta_list_t *)
	Delete the list.

Detailed Description

Typedef Documentation

vlc_media_source_meta_list_t

typedef struct vlc_media_source_meta_list vlc_media_source_meta_list_t

List of media source metadata (opaque).

vlc_media_source_provider_t

typedef struct vlc_media_source_provider_t vlc_media_source_provider_t

Media source provider (opaque pointer), used to get media sources.

vlc_media_source_t

typedef struct vlc_media_source_t vlc_media_source_t

Media source.

A media source is associated to a "service discovery". It stores the detected media in a media tree.

vlc_media_tree_listener_id

typedef struct vlc_media_tree_listener_id vlc_media_tree_listener_id

Listener for media tree events.

vlc_media_tree_t

typedef struct vlc_media_tree vlc_media_tree_t

Media source API aims to manage "services discovery" easily from UI clients.

A "media source provider", associated to the libvlc instance, allows to retrieve media sources (each associated to a services discovery module).

Requesting a services discovery that is not open will automatically open it. If several "clients" request the same media source (i.e. by requesting the same name), they will receive the same (refcounted) media source instance. As soon as a media source is released by all its clients, the associated services discovery is closed.

Each media source holds a media tree, used to store both the media detected by the services discovery and the media detected by preparsing. Clients may listen to the tree to be notified of changes.

To preparse a media belonging to a media tree, use vlc_media_tree_Preparse(). If subitems are detected during the preparsing, the media tree is updated accordingly. Media tree.

Nodes must be traversed with locked held (vlc_media_tree_Lock()).

Function Documentation

vlc_media_source_Hold()

void vlc_media_source_Hold

(

vlc_media_source_t *

ms

)

Increase the media source reference count.

References ms_priv, media_source_private_t::rc, and vlc_atomic_rc_inc().

Referenced by vlc_media_source_provider_GetMediaSource().

vlc_media_source_meta_list_Count()

size_t vlc_media_source_meta_list_Count

(

vlc_media_source_meta_list_t *

list

)

Return the number of items in the list.

References list.

vlc_media_source_meta_list_Delete()

void vlc_media_source_meta_list_Delete

(

vlc_media_source_meta_list_t *

list

)

Delete the list.

Any struct vlc_media_source_meta retrieved from this list become invalid after this call.

References list, and vlc_vector_destroy.

vlc_media_source_meta_list_Get()

struct vlc_media_source_meta * vlc_media_source_meta_list_Get	(	vlc_media_source_meta_list_t *	list,
		size_t	index
	)

Return the item at index.

References list.

vlc_media_source_provider_Get()

vlc_media_source_provider_t * vlc_media_source_provider_Get

(

libvlc_int_t *

libvlc

)

Return the media source provider associated to the libvlc instance.

References libvlc_priv(), and libvlc_priv_t::media_source_provider.

vlc_media_source_provider_GetMediaSource()

vlc_media_source_t * vlc_media_source_provider_GetMediaSource	(	vlc_media_source_provider_t *	provider,
		const char *	name
	)

Return the media source identified by psz_name.

The resulting media source must be released by vlc_media_source_Release().

References vlc_media_source_provider_t::lock, name, vlc_media_source_Hold(), vlc_media_source_provider_Add(), vlc_media_source_provider_Find(), vlc_mutex_lock(), and vlc_mutex_unlock().

vlc_media_source_provider_List()

vlc_media_source_meta_list_t * vlc_media_source_provider_List	(	vlc_media_source_provider_t *	provider,
		enum services_discovery_category_e	category
	)

Return the list of metadata of available media sources.

If category is not 0, then only media sources for the requested category are listed.

The result must be deleted by vlc_media_source_meta_list_Delete() (if not null).

Return NULL either on error or on empty list (this is due to the behavior of the underlying vlc_sd_GetNames()).

Parameters

provider	the media source provider
category	the category to list (0 for all)

References list, vlc_media_source_meta::name, p, unlikely, vlc_sd_GetNames, vlc_vector_destroy, vlc_vector_init, and vlc_vector_push.

vlc_media_source_Release()

void vlc_media_source_Release

(

vlc_media_source_t *

ms

)

Decrease the media source reference count.

Destroy the media source and close the associated "service discovery" if it reaches 0.

References ms_priv, media_source_private_t::rc, vlc_atomic_rc_dec(), and vlc_media_source_Delete().

vlc_media_tree_Add()

input_item_node_t * vlc_media_tree_Add	(	vlc_media_tree_t *	tree,
		input_item_node_t *	parent,
		input_item_t *	media
	)

Add an item to the media tree.

Parameters

tree	the media tree, locked
parent	the parent node, belonging to the media tree
media	the media to add as a child of parent

References on_children_added(), unlikely, vlc_media_tree_AddChild(), vlc_media_tree_AssertLocked(), and vlc_media_tree_Notify.

Referenced by services_discovery_item_added(), test_media_tree(), test_media_tree_callbacks(), and test_media_tree_callbacks_on_add_listener().

vlc_media_tree_AddListener()

vlc_media_tree_listener_id * vlc_media_tree_AddListener	(	vlc_media_tree_t *	tree,
		const struct vlc_media_tree_callbacks *	cbs,
		void *	userdata,
		bool	notify_current_state
	)

Add a listener.

The lock must NOT be held.

Parameters

tree	the media tree, unlocked
cbs	the callbacks (must be valid until the listener is removed)
userdata	userdata provided as a parameter in callbacks
notify_current_state	true to notify the current state immediately via callbacks

References vlc_media_tree_listener_id::cbs, media_tree_private_t::listeners, mt_priv, vlc_media_tree_listener_id::node, unlikely, vlc_media_tree_listener_id::userdata, vlc_list_append(), vlc_media_tree_Lock(), vlc_media_tree_NotifyCurrentState(), and vlc_media_tree_Unlock().

Referenced by test_media_tree_callbacks(), and test_media_tree_callbacks_on_add_listener().

vlc_media_tree_Find()

bool vlc_media_tree_Find	(	vlc_media_tree_t *	tree,
		const input_item_t *	media,
		input_item_node_t **	result,
		input_item_node_t **	result_parent
	)

Find the node containing the requested input item (and its parent).

Parameters

tree	the media tree, locked
media	the media to look for in the tree
result	point to the matching node if the function returns true [OUT]
result_parent	if not NULL, point to the matching node parent if the function returns true [OUT]

Return values

true	if item was found
false	if item was not found

References vlc_media_tree::root, vlc_media_tree_AssertLocked(), and vlc_media_tree_FindNodeByMedia().

Referenced by services_discovery_item_added().

vlc_media_tree_Hold()

void vlc_media_tree_Hold

(

vlc_media_tree_t *

tree

)

Increase the media tree reference count.

Parameters

tree	the media tree, unlocked

References mt_priv, media_tree_private_t::rc, and vlc_atomic_rc_inc().

vlc_media_tree_Lock()

void vlc_media_tree_Lock

(

vlc_media_tree_t *

tree

)

Lock the media tree (non-recursive).

References media_tree_private_t::lock, mt_priv, and vlc_mutex_lock().

Referenced by media_subtree_changed(), media_subtree_preparse_ended(), services_discovery_item_added(), services_discovery_item_removed(), test_media_tree(), test_media_tree_callbacks(), test_media_tree_callbacks_on_add_listener(), vlc_media_tree_AddListener(), and vlc_media_tree_RemoveListener().

vlc_media_tree_New()

vlc_media_tree_t * vlc_media_tree_New

(

void

)

Create an empty media tree.

References input_item_node_t::i_children, media_tree_private_t::listeners, media_tree_private_t::lock, input_item_node_t::p_item, input_item_node_t::pp_children, media_tree_private_t::public_data, media_tree_private_t::rc, vlc_media_tree::root, TAB_INIT, unlikely, vlc_atomic_rc_init(), vlc_list_init(), and vlc_mutex_init().

Referenced by test_media_tree(), test_media_tree_callbacks(), test_media_tree_callbacks_on_add_listener(), and vlc_media_source_New().

vlc_media_tree_Preparse()

void vlc_media_tree_Preparse	(	vlc_media_tree_t *	tree,
		libvlc_int_t *	libvlc,
		input_item_t *	media,
		void *	id
	)

Preparse a media, and expand it in the media tree on subitems added.

Parameters

tree	the media tree (not necessarily locked)
libvlc	the libvlc instance
media	the media to preparse
id	a task identifier

References input_item_t::i_preparse_depth, META_REQUEST_OPTION_DO_INTERACT, META_REQUEST_OPTION_SCOPE_ANY, preparser_callbacks, vlc_MetadataRequest(), and VLC_UNUSED.

vlc_media_tree_PreparseCancel()

void vlc_media_tree_PreparseCancel	(	libvlc_int_t *	libvlc,
		void *	id
	)

Cancel a media tree preparse request.

Parameters

libvlc	the libvlc instance
id	the preparse task id

References libvlc_MetadataCancel(), and VLC_UNUSED.

vlc_media_tree_Release()

void vlc_media_tree_Release

(

vlc_media_tree_t *

tree

)

Decrease the media tree reference count.

Destroy the media tree if it reaches 0.

Parameters

tree	the media tree, unlocked

References mt_priv, media_tree_private_t::rc, vlc_atomic_rc_dec(), and vlc_media_tree_Delete().

Referenced by test_media_tree(), test_media_tree_callbacks(), test_media_tree_callbacks_on_add_listener(), vlc_media_source_Delete(), and vlc_media_source_New().

vlc_media_tree_Remove()

bool vlc_media_tree_Remove	(	vlc_media_tree_t *	tree,
		input_item_t *	media
	)

Remove an item from the media tree.

Parameters

tree	the media tree, locked
media	the media to remove

References input_item_node_Delete(), input_item_node_RemoveNode(), on_children_removed(), vlc_media_tree::root, vlc_media_tree_AssertLocked(), vlc_media_tree_FindNodeByMedia(), and vlc_media_tree_Notify.

Referenced by services_discovery_item_removed(), test_media_tree(), and test_media_tree_callbacks().

vlc_media_tree_RemoveListener()

void vlc_media_tree_RemoveListener	(	vlc_media_tree_t *	tree,
		vlc_media_tree_listener_id *	listener
	)

Remove a listener.

The lock must NOT be held.

Parameters

tree	the media tree, unlocked
listener	the listener identifier returned by vlc_media_tree_AddListener()

References vlc_media_tree_listener_id::node, vlc_list_remove(), vlc_media_tree_Lock(), and vlc_media_tree_Unlock().

Referenced by test_media_tree_callbacks(), and test_media_tree_callbacks_on_add_listener().

vlc_media_tree_Unlock()

void vlc_media_tree_Unlock

(

vlc_media_tree_t *

tree

)

Unlock the media tree.

References media_tree_private_t::lock, mt_priv, and vlc_mutex_unlock().

Referenced by media_subtree_changed(), media_subtree_preparse_ended(), services_discovery_item_added(), services_discovery_item_removed(), test_media_tree(), test_media_tree_callbacks(), test_media_tree_callbacks_on_add_listener(), vlc_media_tree_AddListener(), and vlc_media_tree_RemoveListener().