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
25extern "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
38typedef struct libvlc_renderer_discoverer_t libvlc_renderer_discoverer_t;
39
40/**
41 * Renderer discoverer description
42 *
43 * \see libvlc_renderer_discoverer_list_get()
44 */
45typedef 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 */
67typedef 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 */
81LIBVLC_API libvlc_renderer_item_t *
82libvlc_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 */
89LIBVLC_API void
90libvlc_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 */
99LIBVLC_API const char *
100libvlc_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 */
110LIBVLC_API const char *
111libvlc_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 */
120LIBVLC_API const char *
121libvlc_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 */
133LIBVLC_API int
134libvlc_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 */
155LIBVLC_API libvlc_renderer_discoverer_t *
156libvlc_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 */
166LIBVLC_API void
167libvlc_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 */
182LIBVLC_API int
183libvlc_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 */
194LIBVLC_API void
195libvlc_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 */
214LIBVLC_API libvlc_event_manager_t *
215libvlc_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 */
231LIBVLC_API size_t
232libvlc_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 */
245LIBVLC_API void
246libvlc_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
256

source code of include/vlc/libvlc_renderer_discoverer.h