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
124  (*on_preparse_end)(vlc_media_tree_t *tree, input_item_node_t * node,
126  void *userdata);
127 };
128 
129 /**
130  * Listener for media tree events.
131  */
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  */
195 VLC_API void
197  input_item_t *media);
198 
199 /**
200  * Media source.
201  *
202  * A media source is associated to a "service discovery". It stores the
203  * detected media in a media tree.
204  */
205 typedef struct vlc_media_source_t
206 {
207  vlc_media_tree_t *tree;
208  const char *description;
210 
211 /**
212  * Increase the media source reference count.
213  */
214 VLC_API void
216 
217 /**
218  * Decrease the media source reference count.
219  *
220  * Destroy the media source and close the associated "service discovery" if it
221  * reaches 0.
222  */
223 VLC_API void
225 
226 /**
227  * Media source provider (opaque pointer), used to get media sources.
228  */
231 /**
232  * Return the media source provider associated to the libvlc instance.
233  */
236 
237 /**
238  * Return the media source identified by psz_name.
239  *
240  * The resulting media source must be released by vlc_media_source_Release().
241  */
244  const char *name);
245 
246 /**
247  * Structure containing the description of a media source.
248  */
250 {
251  char *name;
252  char *longname;
254 };
255 
256 /** List of media source metadata (opaque). */
259 /**
260  * Return the list of metadata of available media sources.
261  *
262  * If category is not 0, then only media sources for the requested category are
263  * listed.
264  *
265  * The result must be deleted by vlc_media_source_meta_list_Delete() (if not
266  * null).
267  *
268  * Return NULL either on error or on empty list (this is due to the behavior
269  * of the underlying vlc_sd_GetNames()).
270  *
271  * \param provider the media source provider
272  * \param category the category to list (0 for all)
273  */
276  enum services_discovery_category_e category);
277 
278 /**
279  * Return the number of items in the list.
280  */
281 VLC_API size_t
283 
284 /**
285  * Return the item at index.
286  */
289 
290 /**
291  * Delete the list.
292  *
293  * Any struct vlc_media_source_meta retrieved from this list become invalid
294  * after this call.
295  */
296 VLC_API void
298 
299 /** @} */
300 
301 #ifdef __cplusplus
302 }
303 #endif
304 
305 #endif
306 
void vlc_media_source_meta_list_Delete(vlc_media_source_meta_list_t *)
Delete the list.
Definition: media_source.c:349
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:310
input_item_preparse_status
Definition: vlc_input_item.h:473
Media source API aims to manage "services discovery" easily from UI clients.
Definition: vlc_media_source.h:65
void vlc_media_tree_Lock(vlc_media_tree_t *)
Lock the media tree (non-recursive).
Definition: media_tree.c:227
services_discovery_category_e
Service discovery categories.
Definition: vlc_services_discovery.h:83
input_item_node_t root
Definition: vlc_media_source.h:66
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:77
void vlc_media_tree_RemoveListener(vlc_media_tree_t *tree, vlc_media_tree_listener_id *listener)
Remove a listener.
Definition: media_tree.c:284
Definition: vlc_input_item.h:191
This file is a collection of common definitions and types.
Definition: vlc_objects.h:113
Callbacks to receive media tree events.
Definition: vlc_media_source.h:72
void * userdata
Definition: media_tree.c:38
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:285
static 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)
Definition: test.c:175
This file lists functions and structures for service discovery (SD) in vlc.
static void on_children_reset(vlc_media_tree_t *tree, input_item_node_t *node, void *userdata)
Definition: test.c:144
vlc_chroma_description_t description
Definition: fourcc.c:724
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:337
void vlc_media_source_Release(vlc_media_source_t *)
Decrease the media source reference count.
Definition: media_source.c:182
struct vlc_media_tree vlc_media_tree_t
Media source API aims to manage "services discovery" easily from UI clients.
struct vlc_media_source_t vlc_media_source_t
Media source.
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:265
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:261
void vlc_media_tree_Preparse(vlc_media_tree_t *tree, libvlc_int_t *libvlc, input_item_t *media)
Preparse a media, and expand it in the media tree on subitems added.
Definition: media_tree.c:344
size_t count
Definition: core.c:402
void vlc_media_source_Hold(vlc_media_source_t *)
Increase the media source reference count.
Definition: media_source.c:175
const char name[16]
Definition: httpd.c:1236
const struct vlc_media_tree_callbacks * cbs
Definition: media_tree.c:37
Definition: media_tree.c:35
#define VLC_API
Definition: fourcc_gen.c:31
Definition: media_source.c:279
This file defines functions, structures and enums for input items in vlc.
void vlc_media_tree_Unlock(vlc_media_tree_t *)
Unlock the media tree.
Definition: media_tree.c:234
Definition: media_source.c:52
static 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)
Definition: test.c:158
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
Media source.
Definition: vlc_media_source.h:206
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:343
Structure containing the description of a media source.
Definition: vlc_media_source.h:250