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      * 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,
 125                        enum input_item_preparse_status status,
 126                        void *userdata);
 127 };
 128
 129 /**
 130  * Listener for media tree events.
 131  */
 132 typedef struct vlc_media_tree_listener_id vlc_media_tree_listener_id;
 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  */
 144 VLC_API vlc_media_tree_listener_id *
 145 vlc_media_tree_AddListener(vlc_media_tree_t *tree,
 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
 157 vlc_media_tree_RemoveListener(vlc_media_tree_t *tree,
 158                               vlc_media_tree_listener_id *listener);
 159
 160 /**
 161  * Lock the media tree (non-recursive).
 162  */
 163 VLC_API void
 164 vlc_media_tree_Lock(vlc_media_tree_t *);
 165
 166 /**
 167  * Unlock the media tree.
 168  */
 169 VLC_API void
 170 vlc_media_tree_Unlock(vlc_media_tree_t *);
 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
 184 vlc_media_tree_Find(vlc_media_tree_t *tree, const input_item_t *media,
 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
 197 vlc_media_tree_Preparse(vlc_media_tree_t *tree, libvlc_int_t *libvlc,
 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
 208 vlc_media_tree_PreparseCancel(libvlc_int_t *libvlc, void* id);
 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 {
 218     vlc_media_tree_t *tree;
 219     const char *description;
 220 } vlc_media_source_t;
 221
 222 /**
 223  * Increase the media source reference count.
 224  */
 225 VLC_API void
 226 vlc_media_source_Hold(vlc_media_source_t *);
 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
 235 vlc_media_source_Release(vlc_media_source_t *);
 236
 237 /**
 238  * Media source provider (opaque pointer), used to get media sources.
 239  */
 240 typedef struct vlc_media_source_provider_t vlc_media_source_provider_t;
 241
 242 /**
 243  * Return the media source provider associated to the libvlc instance.
 244  */
 245 VLC_API vlc_media_source_provider_t *
 246 vlc_media_source_provider_Get(libvlc_int_t *);
 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  */
 253 VLC_API vlc_media_source_t *
 254 vlc_media_source_provider_GetMediaSource(vlc_media_source_provider_t *,
 255                                          const char *name);
 256
 257 /**
 258  * Structure containing the description of a media source.
 259  */
 260 struct vlc_media_source_meta
 261 {
 262     char *name;
 263     char *longname;
 264     enum services_discovery_category_e category;
 265 };
 266
 267 /** List of media source metadata (opaque). */
 268 typedef struct vlc_media_source_meta_list vlc_media_source_meta_list_t;
 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  */
 285 VLC_API vlc_media_source_meta_list_t *
 286 vlc_media_source_provider_List(vlc_media_source_provider_t *,
 287                                enum services_discovery_category_e category);
 288
 289 /**
 290  * Return the number of items in the list.
 291  */
 292 VLC_API size_t
 293 vlc_media_source_meta_list_Count(vlc_media_source_meta_list_t *);
 294
 295 /**
 296  * Return the item at index.
 297  */
 298 VLC_API struct vlc_media_source_meta *
 299 vlc_media_source_meta_list_Get(vlc_media_source_meta_list_t *, size_t index);
 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
 308 vlc_media_source_meta_list_Delete(vlc_media_source_meta_list_t *);
 309
 310 /** @} */
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif
 317