include/vlc_media_source.h

   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 {
  65     input_item_node_t root;
  66 } vlc_media_tree_t;
  67
  68 /**
  69  * Callbacks to receive media tree events.
  70  */
  71 struct vlc_media_tree_callbacks
  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
  81     (*on_children_reset)(vlc_media_tree_t *tree, input_item_node_t *node,
  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
  97     (*on_children_added)(vlc_media_tree_t *tree, input_item_node_t *node,
  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
 111     (*on_children_removed)(vlc_media_tree_t *tree, input_item_node_t *node,
 112                            input_item_node_t *const children[], size_t count,
 113                            void *userdata);
 114 };
 115
 116 /**
 117  * Listener for media tree events.
 118  */
 119 typedef struct vlc_media_tree_listener_id vlc_media_tree_listener_id;
 120
 121 /**
 122  * Add a listener. The lock must NOT be held.
 123  *
 124  * \param tree                 the media tree, unlocked
 125  * \param cbs                  the callbacks (must be valid until the listener
 126  *                             is removed)
 127  * \param userdata             userdata provided as a parameter in callbacks
 128  * \param notify_current_state true to notify the current state immediately via
 129  *                             callbacks
 130  */
 131 VLC_API vlc_media_tree_listener_id *
 132 vlc_media_tree_AddListener(vlc_media_tree_t *tree,
 133                            const struct vlc_media_tree_callbacks *cbs,
 134                            void *userdata, bool notify_current_state);
 135
 136 /**
 137  * Remove a listener. The lock must NOT be held.
 138  *
 139  * \param tree     the media tree, unlocked
 140  * \param listener the listener identifier returned by
 141  *                 vlc_media_tree_AddListener()
 142  */
 143 VLC_API void
 144 vlc_media_tree_RemoveListener(vlc_media_tree_t *tree,
 145                               vlc_media_tree_listener_id *listener);
 146
 147 /**
 148  * Lock the media tree (non-recursive).
 149  */
 150 VLC_API void
 151 vlc_media_tree_Lock(vlc_media_tree_t *);
 152
 153 /**
 154  * Unlock the media tree.
 155  */
 156 VLC_API void
 157 vlc_media_tree_Unlock(vlc_media_tree_t *);
 158
 159 /**
 160  * Find the node containing the requested input item (and its parent).
 161  *
 162  * \param tree the media tree, locked
 163  * \param result point to the matching node if the function returns true [OUT]
 164  * \param result_parent if not NULL, point to the matching node parent
 165  *                      if the function returns true [OUT]
 166  *
 167  * \retval true if item was found
 168  * \retval false if item was not found
 169  */
 170 VLC_API bool
 171 vlc_media_tree_Find(vlc_media_tree_t *tree, const input_item_t *media,
 172                     input_item_node_t **result,
 173                     input_item_node_t **result_parent);
 174
 175 /**
 176  * Preparse a media, and expand it in the media tree on subitems added.
 177  *
 178  * \param tree   the media tree (not necessarily locked)
 179  * \param libvlc the libvlc instance
 180  * \param media  the media to preparse
 181  */
 182 VLC_API void
 183 vlc_media_tree_Preparse(vlc_media_tree_t *tree, libvlc_int_t *libvlc,
 184                         input_item_t *media);
 185
 186 /**
 187  * Media source.
 188  *
 189  * A media source is associated to a "service discovery". It stores the
 190  * detected media in a media tree.
 191  */
 192 typedef struct vlc_media_source_t
 193 {
 194     vlc_media_tree_t *tree;
 195     const char *description;
 196 } vlc_media_source_t;
 197
 198 /**
 199  * Increase the media source reference count.
 200  */
 201 VLC_API void
 202 vlc_media_source_Hold(vlc_media_source_t *);
 203
 204 /**
 205  * Decrease the media source reference count.
 206  *
 207  * Destroy the media source and close the associated "service discovery" if it
 208  * reaches 0.
 209  */
 210 VLC_API void
 211 vlc_media_source_Release(vlc_media_source_t *);
 212
 213 /**
 214  * Media source provider (opaque pointer), used to get media sources.
 215  */
 216 typedef struct vlc_media_source_provider_t vlc_media_source_provider_t;
 217
 218 /**
 219  * Return the media source provider associated to the libvlc instance.
 220  */
 221 VLC_API vlc_media_source_provider_t *
 222 vlc_media_source_provider_Get(libvlc_int_t *);
 223
 224 /**
 225  * Return the media source identified by psz_name.
 226  *
 227  * The resulting media source must be released by vlc_media_source_Release().
 228  */
 229 VLC_API vlc_media_source_t *
 230 vlc_media_source_provider_GetMediaSource(vlc_media_source_provider_t *,
 231                                          const char *name);
 232
 233 /**
 234  * Structure containing the description of a media source.
 235  */
 236 struct vlc_media_source_meta
 237 {
 238     char *name;
 239     char *longname;
 240     enum services_discovery_category_e category;
 241 };
 242
 243 /** List of media source metadata (opaque). */
 244 typedef struct vlc_media_source_meta_list vlc_media_source_meta_list_t;
 245
 246 /**
 247  * Return the list of metadata of available media sources.
 248  *
 249  * If category is not 0, then only media sources for the requested category are
 250  * listed.
 251  *
 252  * The result must be deleted by vlc_media_source_meta_list_Delete() (if not
 253  * null).
 254  *
 255  * Return NULL either on error or on empty list (this is due to the behavior
 256  * of the underlying vlc_sd_GetNames()).
 257  *
 258  * \param provider the media source provider
 259  * \param category the category to list (0 for all)
 260  */
 261 VLC_API vlc_media_source_meta_list_t *
 262 vlc_media_source_provider_List(vlc_media_source_provider_t *,
 263                                enum services_discovery_category_e category);
 264
 265 /**
 266  * Return the number of items in the list.
 267  */
 268 VLC_API size_t
 269 vlc_media_source_meta_list_Count(vlc_media_source_meta_list_t *);
 270
 271 /**
 272  * Return the item at index.
 273  */
 274 VLC_API struct vlc_media_source_meta *
 275 vlc_media_source_meta_list_Get(vlc_media_source_meta_list_t *, size_t index);
 276
 277 /**
 278  * Delete the list.
 279  *
 280  * Any struct vlc_media_source_meta retrieved from this list become invalid
 281  * after this call.
 282  */
 283 VLC_API void
 284 vlc_media_source_meta_list_Delete(vlc_media_source_meta_list_t *);
 285
 286 /** @} */
 287
 288 #ifdef __cplusplus
 289 }
 290 #endif
 291
 292 #endif
 293