include/vlc/libvlc_media_discoverer.h

   1 /*****************************************************************************
   2  * libvlc_media_discoverer.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2009 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Clément Stenac <zorglub@videolan.org>
   8  *          Jean-Paul Saman <jpsaman@videolan.org>
   9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU Lesser General Public License as published by
  13  * the Free Software Foundation; either version 2.1 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24  *****************************************************************************/
  25
  26 #ifndef VLC_LIBVLC_MEDIA_DISCOVERER_H
  27 #define VLC_LIBVLC_MEDIA_DISCOVERER_H 1
  28
  29 # ifdef __cplusplus
  30 extern "C" {
  31 # endif
  32
  33 /**
  34  * Category of a media discoverer
  35  * \see libvlc_media_discoverer_list_get()
  36  */
  37 typedef enum libvlc_media_discoverer_category_t {
  38     /** devices, like portable music player */
  39     libvlc_media_discoverer_devices,
  40     /** LAN/WAN services, like Upnp, SMB, or SAP */
  41     libvlc_media_discoverer_lan,
  42     /** Podcasts */
  43     libvlc_media_discoverer_podcasts,
  44     /** Local directories, like Video, Music or Pictures directories */
  45     libvlc_media_discoverer_localdirs,
  46 } libvlc_media_discoverer_category_t;
  47
  48 /**
  49  * Media discoverer description
  50  * \see libvlc_media_discoverer_list_get()
  51  */
  52 typedef struct libvlc_media_discoverer_description_t {
  53     char *psz_name;
  54     char *psz_longname;
  55     libvlc_media_discoverer_category_t i_cat;
  56 } libvlc_media_discoverer_description_t;
  57
  58 /** \defgroup libvlc_media_discoverer LibVLC media discovery
  59  * \ingroup libvlc
  60  * LibVLC media discovery finds available media via various means.
  61  * This corresponds to the service discovery functionality in VLC media player.
  62  * Different plugins find potential medias locally (e.g. user media directory),
  63  * from peripherals (e.g. video capture device), on the local network
  64  * (e.g. SAP) or on the Internet (e.g. Internet radios).
  65  * @{
  66  * \file
  67  * LibVLC media discovery external API
  68  */
  69
  70 typedef struct libvlc_media_discoverer_t libvlc_media_discoverer_t;
  71
  72 /**
  73  * Create a media discoverer object by name.
  74  *
  75  * After this object is created, you should attach to media_list events in
  76  * order to be notified of new items discovered.
  77  *
  78  * You need to call libvlc_media_discoverer_start() in order to start the
  79  * discovery.
  80  *
  81  * \see libvlc_media_discoverer_media_list
  82  * \see libvlc_media_discoverer_event_manager
  83  * \see libvlc_media_discoverer_start
  84  *
  85  * \param p_inst libvlc instance
  86  * \param psz_name service name; use libvlc_media_discoverer_list_get() to get
  87  * a list of the discoverer names available in this libVLC instance
  88  * \return media discover object or NULL in case of error
  89  * \version LibVLC 3.0.0 or later
  90  */
  91 LIBVLC_API libvlc_media_discoverer_t *
  92 libvlc_media_discoverer_new( libvlc_instance_t * p_inst,
  93                              const char * psz_name );
  94
  95 /**
  96  * Start media discovery.
  97  *
  98  * To stop it, call libvlc_media_discoverer_stop() or
  99  * libvlc_media_discoverer_list_release() directly.
 100  *
 101  * \see libvlc_media_discoverer_stop
 102  *
 103  * \param p_mdis media discover object
 104  * \return -1 in case of error, 0 otherwise
 105  * \version LibVLC 3.0.0 or later
 106  */
 107 LIBVLC_API int
 108 libvlc_media_discoverer_start( libvlc_media_discoverer_t * p_mdis );
 109
 110 /**
 111  * Stop media discovery.
 112  *
 113  * \see libvlc_media_discoverer_start
 114  *
 115  * \param p_mdis media discover object
 116  * \version LibVLC 3.0.0 or later
 117  */
 118 LIBVLC_API void
 119 libvlc_media_discoverer_stop( libvlc_media_discoverer_t * p_mdis );
 120
 121 /**
 122  * Release media discover object. If the reference count reaches 0, then
 123  * the object will be released.
 124  *
 125  * \param p_mdis media service discover object
 126  */
 127 LIBVLC_API void
 128 libvlc_media_discoverer_release( libvlc_media_discoverer_t * p_mdis );
 129
 130 /**
 131  * Get media service discover media list.
 132  *
 133  * \param p_mdis media service discover object
 134  * \return list of media items
 135  */
 136 LIBVLC_API libvlc_media_list_t *
 137 libvlc_media_discoverer_media_list( libvlc_media_discoverer_t * p_mdis );
 138
 139 /**
 140  * Query if media service discover object is running.
 141  *
 142  * \param p_mdis media service discover object
 143  * \return true if running, false if not
 144  *
 145  * \libvlc_return_bool
 146  */
 147 LIBVLC_API int
 148 libvlc_media_discoverer_is_running( libvlc_media_discoverer_t * p_mdis );
 149
 150 /**
 151  * Get media discoverer services by category
 152  *
 153  * \version LibVLC 3.0.0 and later.
 154  *
 155  * \param p_inst libvlc instance
 156  * \param i_cat category of services to fetch
 157  * \param ppp_services address to store an allocated array of media discoverer
 158  * services (must be freed with libvlc_media_discoverer_list_release() by
 159  * the caller) [OUT]
 160  *
 161  * \return the number of media discoverer services (0 on error)
 162  */
 163 LIBVLC_API size_t
 164 libvlc_media_discoverer_list_get( libvlc_instance_t *p_inst,
 165                                   libvlc_media_discoverer_category_t i_cat,
 166                                   libvlc_media_discoverer_description_t ***ppp_services );
 167
 168 /**
 169  * Release an array of media discoverer services
 170  *
 171  * \version LibVLC 3.0.0 and later.
 172  *
 173  * \see libvlc_media_discoverer_list_get()
 174  *
 175  * \param pp_services array to release
 176  * \param i_count number of elements in the array
 177  */
 178 LIBVLC_API void
 179 libvlc_media_discoverer_list_release( libvlc_media_discoverer_description_t **pp_services,
 180                                       size_t i_count );
 181
 182 /**@} */
 183
 184 # ifdef __cplusplus
 185 }
 186 # endif
 187
 188 #endif /* <vlc/libvlc.h> */