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
30extern "C" {
31# endif
32
33/**
34 * Category of a media discoverer
35 * \see libvlc_media_discoverer_list_get()
36 */
37typedef 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 */
52typedef 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
70typedef 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 */
91LIBVLC_API libvlc_media_discoverer_t *
92libvlc_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 */
107LIBVLC_API int
108libvlc_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 */
118LIBVLC_API void
119libvlc_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 */
127LIBVLC_API void
128libvlc_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 */
136LIBVLC_API libvlc_media_list_t *
137libvlc_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 */
147LIBVLC_API int
148libvlc_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 */
163LIBVLC_API size_t
164libvlc_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 */
178LIBVLC_API void
179libvlc_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

source code of include/vlc/libvlc_media_discoverer.h