1 /***************************************************************************** 2 * libvlc_media_discoverer.h: libvlc external API 3 ***************************************************************************** 4 * Copyright (C) 1998-2009 VLC authors and VideoLAN 5 * $Id: 96c0515ffec98f439867814d68525288b2702b0f $ 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> */ 189