VLC  4.0.0-dev
vlc_media_source.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_media_source.h
3  *****************************************************************************
4  * Copyright (C) 2018 VLC authors and VideoLAN
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation; either version 2.1 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19  *****************************************************************************/
20 
21 #ifndef VLC_MEDIA_SOURCE_H
22 #define VLC_MEDIA_SOURCE_H
23 
24 #include <vlc_common.h>
25 #include <vlc_input_item.h>
26 #include <vlc_services_discovery.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33  * \defgroup media_source Media source
34  * \ingroup input
35  * @{
36  */
37 
38 /**
39  * Media source API aims to manage "services discovery" easily from UI clients.
40  *
41  * A "media source provider", associated to the libvlc instance, allows to
42  * retrieve media sources (each associated to a services discovery module).
43  *
44  * Requesting a services discovery that is not open will automatically open it.
45  * If several "clients" request the same media source (i.e. by requesting the
46  * same name), they will receive the same (refcounted) media source instance.
47  * As soon as a media source is released by all its clients, the associated
48  * services discovery is closed.
49  *
50  * Each media source holds a media tree, used to store both the media
51  * detected by the services discovery and the media detected by preparsing.
52  * Clients may listen to the tree to be notified of changes.
53  *
54  * To preparse a media belonging to a media tree, use vlc_media_tree_Preparse().
55  * If subitems are detected during the preparsing, the media tree is updated
56  * accordingly.
57  */
58 
59 /**
60  * Media tree.
61  *
62  * Nodes must be traversed with locked held (vlc_media_tree_Lock()).
63  */
64 typedef struct vlc_media_tree {
67 
68 /**
69  * Callbacks to receive media tree events.
70  */
72 {
73  /**
74  * Called when the whole content of a subtree has changed.
75  *
76  * \param playlist the playlist
77  * \param node the node having its children reset (may be root)
78  * \param userdata userdata provided to AddListener()
79  */
80  void
82  void *userdata);
83 
84  /**
85  * Called when children has been added to a node.
86  *
87  * The children may themselves contain children, which will not be notified
88  * separately.
89  *
90  * \param playlist the playlist
91  * \param node the node having children added
92  * \param children the children added
93  * \param count the number of children added
94  * \param userdata userdata provided to AddListener()
95  */
96  void
98  input_item_node_t *const children[], size_t count,
99  void *userdata);
100 
101  /**
102  * Called when children has been removed from a node.
103  *
104  * \param playlist the playlist
105  * \param node the node having children removed
106  * \param children the children removed
107  * \param count the number of children removed
108  * \param userdata userdata provided to AddListener()
109  */
110  void
112  input_item_node_t *const children[], size_t count,
113  void *userdata);
114 
115  /**
116  * Called when the preparsing of a node is complete
117  *
118  * \param tree the media tree
119  * \param node the node being parsed
120  * \param status the reason for the preparsing termination
121  * \param userdata userdata provided to AddListener()
122  */
123  void
125  enum input_item_preparse_status status,
126  void *userdata);
127 };
128 
129 /**
130  * Listener for media tree events.
131  */
133 
134 /**
135  * Add a listener. The lock must NOT be held.
136  *
137  * \param tree the media tree, unlocked
138  * \param cbs the callbacks (must be valid until the listener
139  * is removed)
140  * \param userdata userdata provided as a parameter in callbacks
141  * \param notify_current_state true to notify the current state immediately via
142  * callbacks
143  */
146  const struct vlc_media_tree_callbacks *cbs,
147  void *userdata, bool notify_current_state);
148 
149 /**
150  * Remove a listener. The lock must NOT be held.
151  *
152  * \param tree the media tree, unlocked
153  * \param listener the listener identifier returned by
154  * vlc_media_tree_AddListener()
155  */
156 VLC_API void
158  vlc_media_tree_listener_id *listener);
159 
160 /**
161  * Lock the media tree (non-recursive).
162  */
163 VLC_API void
165 
166 /**
167  * Unlock the media tree.
168  */
169 VLC_API void
171 
172 /**
173  * Find the node containing the requested input item (and its parent).
174  *
175  * \param tree the media tree, locked
176  * \param result point to the matching node if the function returns true [OUT]
177  * \param result_parent if not NULL, point to the matching node parent
178  * if the function returns true [OUT]
179  *
180  * \retval true if item was found
181  * \retval false if item was not found
182  */
183 VLC_API bool
185  input_item_node_t **result,
186  input_item_node_t **result_parent);
187 
188 /**
189  * Preparse a media, and expand it in the media tree on subitems added.
190  *
191  * \param tree the media tree (not necessarily locked)
192  * \param libvlc the libvlc instance
193  * \param media the media to preparse
194  * \param id a task identifier
195  */
196 VLC_API void
198  input_item_t *media, void *id);
199 
200 
201 /**
202  * Cancel a media tree preparse request
203  *
204  * \param libvlc the libvlc instance
205  * \param id the preparse task id
206  */
207 VLC_API void
209 
210 /**
211  * Media source.
212  *
213  * A media source is associated to a "service discovery". It stores the
214  * detected media in a media tree.
215  */
216 typedef struct vlc_media_source_t
217 {
219  const char *description;
221 
222 /**
223  * Increase the media source reference count.
224  */
225 VLC_API void
227 
228 /**
229  * Decrease the media source reference count.
230  *
231  * Destroy the media source and close the associated "service discovery" if it
232  * reaches 0.
233  */
234 VLC_API void
236 
237 /**
238  * Media source provider (opaque pointer), used to get media sources.
239  */
241 
242 /**
243  * Return the media source provider associated to the libvlc instance.
244  */
247 
248 /**
249  * Return the media source identified by psz_name.
250  *
251  * The resulting media source must be released by vlc_media_source_Release().
252  */
255  const char *name);
256 
257 /**
258  * Structure containing the description of a media source.
259  */
261 {
262  char *name;
263  char *longname;
265 };
266 
267 /** List of media source metadata (opaque). */
269 
270 /**
271  * Return the list of metadata of available media sources.
272  *
273  * If category is not 0, then only media sources for the requested category are
274  * listed.
275  *
276  * The result must be deleted by vlc_media_source_meta_list_Delete() (if not
277  * null).
278  *
279  * Return NULL either on error or on empty list (this is due to the behavior
280  * of the underlying vlc_sd_GetNames()).
281  *
282  * \param provider the media source provider
283  * \param category the category to list (0 for all)
284  */
287  enum services_discovery_category_e category);
288 
289 /**
290  * Return the number of items in the list.
291  */
292 VLC_API size_t
294 
295 /**
296  * Return the item at index.
297  */
300 
301 /**
302  * Delete the list.
303  *
304  * Any struct vlc_media_source_meta retrieved from this list become invalid
305  * after this call.
306  */
307 VLC_API void
309 
310 /** @} */
311 
312 #ifdef __cplusplus
313 }
314 #endif
315 
316 #endif
317 
size_t count
Definition: core.c:392
#define VLC_API
Definition: fourcc_gen.c:31
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.
Definition: media_source.c:264
struct vlc_media_tree vlc_media_tree_t
Media source API aims to manage "services discovery" easily from UI clients.
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.
Definition: media_source.c:284
size_t vlc_media_source_meta_list_Count(vlc_media_source_meta_list_t *)
Return the number of items in the list.
Definition: media_source.c:336
void vlc_media_source_Release(vlc_media_source_t *)
Decrease the media source reference count.
Definition: media_source.c:182
void vlc_media_tree_PreparseCancel(libvlc_int_t *libvlc, void *id)
Cancel a media tree preparse request.
Definition: media_tree.c:362
void vlc_media_tree_RemoveListener(vlc_media_tree_t *tree, vlc_media_tree_listener_id *listener)
Remove a listener.
Definition: media_tree.c:283
void vlc_media_tree_Unlock(vlc_media_tree_t *)
Unlock the media tree.
Definition: media_tree.c:233
struct vlc_media_source_t vlc_media_source_t
Media source.
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.
Definition: media_source.c:342
void vlc_media_tree_Lock(vlc_media_tree_t *)
Lock the media tree (non-recursive).
Definition: media_tree.c:226
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.
Definition: media_tree.c:260
vlc_media_source_provider_t * vlc_media_source_provider_Get(libvlc_int_t *)
Return the media source provider associated to the libvlc instance.
Definition: media_source.c:202
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.
Definition: media_tree.c:343
void vlc_media_source_meta_list_Delete(vlc_media_source_meta_list_t *)
Delete the list.
Definition: media_source.c:348
void vlc_media_source_Hold(vlc_media_source_t *)
Increase the media source reference count.
Definition: media_source.c:175
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).
Definition: media_tree.c:309
const char name[16]
Definition: httpd.c:1267
Definition: vlc_input_item.h:205
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:89
Definition: vlc_objects.h:91
Definition: media_source.c:279
Structure containing the description of a media source.
Definition: vlc_media_source.h:262
char * longname
Definition: vlc_media_source.h:264
enum services_discovery_category_e category
Definition: vlc_media_source.h:265
char * name
Definition: vlc_media_source.h:263
Definition: media_source.c:53
Media source.
Definition: vlc_media_source.h:218
const char * description
Definition: vlc_media_source.h:220
vlc_media_tree_t * tree
Definition: vlc_media_source.h:219
Callbacks to receive media tree events.
Definition: vlc_media_source.h:73
void(* on_children_added)(vlc_media_tree_t *tree, input_item_node_t *node, input_item_node_t *const children[], size_t count, void *userdata)
Called when children has been added to a node.
Definition: vlc_media_source.h:98
void(* on_children_reset)(vlc_media_tree_t *tree, input_item_node_t *node, void *userdata)
Called when the whole content of a subtree has changed.
Definition: vlc_media_source.h:82
void(* on_children_removed)(vlc_media_tree_t *tree, input_item_node_t *node, input_item_node_t *const children[], size_t count, void *userdata)
Called when children has been removed from a node.
Definition: vlc_media_source.h:112
void(* on_preparse_end)(vlc_media_tree_t *tree, input_item_node_t *node, enum input_item_preparse_status status, void *userdata)
Called when the preparsing of a node is complete.
Definition: vlc_media_source.h:125
Definition: media_tree.c:36
void * userdata
Definition: media_tree.c:38
const struct vlc_media_tree_callbacks * cbs
Definition: media_tree.c:37
Media source API aims to manage "services discovery" easily from UI clients.
Definition: vlc_media_source.h:65
input_item_node_t root
Definition: vlc_media_source.h:66
This file is a collection of common definitions and types.
This file defines functions, structures and enums for input items in vlc.
input_item_preparse_status
Definition: vlc_input_item.h:490
This file lists functions and structures for service discovery (SD) in vlc.
services_discovery_category_e
Service discovery categories.
Definition: vlc_services_discovery.h:84