include/vlc/libvlc_renderer_discoverer.h

   1 /*****************************************************************************
   2  * libvlc_renderer_discoverer.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright © 2016 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_LIBVLC_RENDERER_DISCOVERER_H
  22 #define VLC_LIBVLC_RENDERER_DISCOVERER_H 1
  23
  24 # ifdef __cplusplus
  25 extern "C" {
  26 # endif
  27
  28 /**
  29  * @defgroup libvlc_renderer_discoverer LibVLC renderer discoverer
  30  * @ingroup libvlc
  31  * LibVLC renderer discoverer finds available renderers available on the local
  32  * network
  33  * @{
  34  * @file
  35  * LibVLC renderer discoverer external API
  36  */
  37
  38 typedef struct libvlc_renderer_discoverer_t libvlc_renderer_discoverer_t;
  39
  40 /**
  41  * Renderer discoverer description
  42  *
  43  * \see libvlc_renderer_discoverer_list_get()
  44  */
  45 typedef struct libvlc_rd_description_t
  46 {
  47     char *psz_name;
  48     char *psz_longname;
  49 } libvlc_rd_description_t;
  50
  51 /** The renderer can render audio */
  52 #define LIBVLC_RENDERER_CAN_AUDIO 0x0001
  53 /** The renderer can render video */
  54 #define LIBVLC_RENDERER_CAN_VIDEO 0x0002
  55
  56 /**
  57  * Renderer item
  58  *
  59  * This struct is passed by a @ref libvlc_event_t when a new renderer is added
  60  * or deleted.
  61  *
  62  * An item is valid until the @ref libvlc_RendererDiscovererItemDeleted event
  63  * is called with the same pointer.
  64  *
  65  * \see libvlc_renderer_discoverer_event_manager()
  66  */
  67 typedef struct libvlc_renderer_item_t libvlc_renderer_item_t;
  68
  69
  70 /**
  71  * Hold a renderer item, i.e. creates a new reference
  72  *
  73  * This functions need to called from the libvlc_RendererDiscovererItemAdded
  74  * callback if the libvlc user wants to use this item after. (for display or
  75  * for passing it to the mediaplayer for example).
  76  *
  77  * \version LibVLC 3.0.0 or later
  78  *
  79  * \return the current item
  80  */
  81 LIBVLC_API libvlc_renderer_item_t *
  82 libvlc_renderer_item_hold(libvlc_renderer_item_t *p_item);
  83
  84 /**
  85  * Releases a renderer item, i.e. decrements its reference counter
  86  *
  87  * \version LibVLC 3.0.0 or later
  88  */
  89 LIBVLC_API void
  90 libvlc_renderer_item_release(libvlc_renderer_item_t *p_item);
  91
  92 /**
  93  * Get the human readable name of a renderer item
  94  *
  95  * \version LibVLC 3.0.0 or later
  96  *
  97  * \return the name of the item (can't be NULL, must *not* be freed)
  98  */
  99 LIBVLC_API const char *
 100 libvlc_renderer_item_name(const libvlc_renderer_item_t *p_item);
 101
 102 /**
 103  * Get the type (not translated) of a renderer item. For now, the type can only
 104  * be "chromecast" ("upnp", "airplay" may come later).
 105  *
 106  * \version LibVLC 3.0.0 or later
 107  *
 108  * \return the type of the item (can't be NULL, must *not* be freed)
 109  */
 110 LIBVLC_API const char *
 111 libvlc_renderer_item_type(const libvlc_renderer_item_t *p_item);
 112
 113 /**
 114  * Get the icon uri of a renderer item
 115  *
 116  * \version LibVLC 3.0.0 or later
 117  *
 118  * \return the uri of the item's icon (can be NULL, must *not* be freed)
 119  */
 120 LIBVLC_API const char *
 121 libvlc_renderer_item_icon_uri(const libvlc_renderer_item_t *p_item);
 122
 123 /**
 124  * Get the flags of a renderer item
 125  *
 126  * \see LIBVLC_RENDERER_CAN_AUDIO
 127  * \see LIBVLC_RENDERER_CAN_VIDEO
 128  *
 129  * \version LibVLC 3.0.0 or later
 130  *
 131  * \return bitwise flag: capabilities of the renderer, see
 132  */
 133 LIBVLC_API int
 134 libvlc_renderer_item_flags(const libvlc_renderer_item_t *p_item);
 135
 136 /**
 137  * Create a renderer discoverer object by name
 138  *
 139  * After this object is created, you should attach to events in order to be
 140  * notified of the discoverer events.
 141  *
 142  * You need to call libvlc_renderer_discoverer_start() in order to start the
 143  * discovery.
 144  *
 145  * \see libvlc_renderer_discoverer_event_manager()
 146  * \see libvlc_renderer_discoverer_start()
 147  *
 148  * \version LibVLC 3.0.0 or later
 149  *
 150  * \param p_inst libvlc instance
 151  * \param psz_name service name; use libvlc_renderer_discoverer_list_get() to
 152  * get a list of the discoverer names available in this libVLC instance
 153  * \return media discover object or NULL in case of error
 154  */
 155 LIBVLC_API libvlc_renderer_discoverer_t *
 156 libvlc_renderer_discoverer_new( libvlc_instance_t *p_inst,
 157                                 const char *psz_name );
 158
 159 /**
 160  * Release a renderer discoverer object
 161  *
 162  * \version LibVLC 3.0.0 or later
 163  *
 164  * \param p_rd renderer discoverer object
 165  */
 166 LIBVLC_API void
 167 libvlc_renderer_discoverer_release( libvlc_renderer_discoverer_t *p_rd );
 168
 169 /**
 170  * Start renderer discovery
 171  *
 172  * To stop it, call libvlc_renderer_discoverer_stop() or
 173  * libvlc_renderer_discoverer_release() directly.
 174  *
 175  * \see libvlc_renderer_discoverer_stop()
 176  *
 177  * \version LibVLC 3.0.0 or later
 178  *
 179  * \param p_rd renderer discoverer object
 180  * \return -1 in case of error, 0 otherwise
 181  */
 182 LIBVLC_API int
 183 libvlc_renderer_discoverer_start( libvlc_renderer_discoverer_t *p_rd );
 184
 185 /**
 186  * Stop renderer discovery.
 187  *
 188  * \see libvlc_renderer_discoverer_start()
 189  *
 190  * \version LibVLC 3.0.0 or later
 191  *
 192  * \param p_rd renderer discoverer object
 193  */
 194 LIBVLC_API void
 195 libvlc_renderer_discoverer_stop( libvlc_renderer_discoverer_t *p_rd );
 196
 197 /**
 198  * Get the event manager of the renderer discoverer
 199  *
 200  * The possible events to attach are @ref libvlc_RendererDiscovererItemAdded
 201  * and @ref libvlc_RendererDiscovererItemDeleted.
 202  *
 203  * The @ref libvlc_renderer_item_t struct passed to event callbacks is owned by
 204  * VLC, users should take care of holding/releasing this struct for their
 205  * internal usage.
 206  *
 207  * \see libvlc_event_t.u.renderer_discoverer_item_added.item
 208  * \see libvlc_event_t.u.renderer_discoverer_item_removed.item
 209  *
 210  * \version LibVLC 3.0.0 or later
 211  *
 212  * \return a valid event manager (can't fail)
 213  */
 214 LIBVLC_API libvlc_event_manager_t *
 215 libvlc_renderer_discoverer_event_manager( libvlc_renderer_discoverer_t *p_rd );
 216
 217 /**
 218  * Get media discoverer services
 219  *
 220  * \see libvlc_renderer_list_release()
 221  *
 222  * \version LibVLC 3.0.0 and later
 223  *
 224  * \param p_inst libvlc instance
 225  * \param ppp_services address to store an allocated array of renderer
 226  * discoverer services (must be freed with libvlc_renderer_list_release() by
 227  * the caller) [OUT]
 228  *
 229  * \return the number of media discoverer services (0 on error)
 230  */
 231 LIBVLC_API size_t
 232 libvlc_renderer_discoverer_list_get( libvlc_instance_t *p_inst,
 233                                      libvlc_rd_description_t ***ppp_services );
 234
 235 /**
 236  * Release an array of media discoverer services
 237  *
 238  * \see libvlc_renderer_discoverer_list_get()
 239  *
 240  * \version LibVLC 3.0.0 and later
 241  *
 242  * \param pp_services array to release
 243  * \param i_count number of elements in the array
 244  */
 245 LIBVLC_API void
 246 libvlc_renderer_discoverer_list_release( libvlc_rd_description_t **pp_services,
 247                                          size_t i_count );
 248
 249 /** @} */
 250
 251 # ifdef __cplusplus
 252 }
 253 # endif
 254
 255 #endif