libvlc: clean up deprecated functions
[vlc.git] / 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 {
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;
47
48 /**
49  * Media discoverer description
50  * \see libvlc_media_discoverer_list_get()
51  */
52 typedef struct libvlc_media_discoverer_description {
53     char *psz_name;
54     char *psz_longname;
55     libvlc_media_discoverer_category i_cat;
56 } libvlc_media_discoverer_description;
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 events in order to be
76  * notified of the discoverer state.
77  * You should also attach to media_list events in order to be notified of new
78  * items discovered.
79  *
80  * You need to call libvlc_media_discoverer_start() in order to start the
81  * discovery.
82  *
83  * \see libvlc_media_discoverer_media_list
84  * \see libvlc_media_discoverer_event_manager
85  * \see libvlc_media_discoverer_start
86  *
87  * \param p_inst libvlc instance
88  * \param psz_name service name; use libvlc_media_discoverer_list_get() to get
89  * a list of the discoverer names available in this libVLC instance
90  * \return media discover object or NULL in case of error
91  * \version LibVLC 3.0.0 or later
92  */
93 LIBVLC_API libvlc_media_discoverer_t *
94 libvlc_media_discoverer_new( libvlc_instance_t * p_inst,
95                              const char * psz_name );
96
97 /**
98  * Start media discovery.
99  *
100  * To stop it, call libvlc_media_discoverer_stop() or
101  * libvlc_media_discoverer_list_release() directly.
102  *
103  * \see libvlc_media_discoverer_stop
104  *
105  * \param p_mdis media discover object
106  * \return -1 in case of error, 0 otherwise
107  * \version LibVLC 3.0.0 or later
108  */
109 LIBVLC_API int
110 libvlc_media_discoverer_start( libvlc_media_discoverer_t * p_mdis );
111
112 /**
113  * Stop media discovery.
114  *
115  * \see libvlc_media_discoverer_start
116  *
117  * \param p_mdis media discover object
118  * \version LibVLC 3.0.0 or later
119  */
120 LIBVLC_API void
121 libvlc_media_discoverer_stop( libvlc_media_discoverer_t * p_mdis );
122
123 /**
124  * Release media discover object. If the reference count reaches 0, then
125  * the object will be released.
126  *
127  * \param p_mdis media service discover object
128  */
129 LIBVLC_API void
130 libvlc_media_discoverer_release( libvlc_media_discoverer_t * p_mdis );
131
132 /**
133  * Get media service discover object its localized name.
134  *
135  * \param p_mdis media discover object
136  * \return localized name
137  */
138 LIBVLC_API char *
139 libvlc_media_discoverer_localized_name( libvlc_media_discoverer_t * p_mdis );
140
141 /**
142  * Get media service discover media list.
143  *
144  * \param p_mdis media service discover object
145  * \return list of media items
146  */
147 LIBVLC_API libvlc_media_list_t *
148 libvlc_media_discoverer_media_list( libvlc_media_discoverer_t * p_mdis );
149
150 /**
151  * Get event manager from media service discover object.
152  *
153  * \param p_mdis media service discover object
154  * \return event manager object.
155  */
156 LIBVLC_API libvlc_event_manager_t *
157 libvlc_media_discoverer_event_manager( libvlc_media_discoverer_t * p_mdis );
158
159 /**
160  * Query if media service discover object is running.
161  *
162  * \param p_mdis media service discover object
163  * \return true if running, false if not
164  *
165  * \libvlc_return_bool
166  */
167 LIBVLC_API int
168 libvlc_media_discoverer_is_running( libvlc_media_discoverer_t * p_mdis );
169
170 /**
171  * Get media discoverer services by category
172  *
173  * \version LibVLC 3.0.0 and later.
174  *
175  * \param p_inst libvlc instance
176  * \param i_cat category of services to fetch
177  * \param ppp_services address to store an allocated array of media discoverer
178  * services (must be freed with libvlc_media_discoverer_list_release() by
179  * the caller) [OUT]
180  *
181  * \return the number of media discoverer services (zero on error)
182  */
183 LIBVLC_API unsigned int
184 libvlc_media_discoverer_list_get( libvlc_instance_t *p_inst,
185                                   libvlc_media_discoverer_category i_cat,
186                                   libvlc_media_discoverer_description ***ppp_services );
187
188 /**
189  * Release an array of media discoverer services
190  *
191  * \version LibVLC 3.0.0 and later.
192  *
193  * \see libvlc_media_discoverer_list_get()
194  *
195  * \param pp_services array to release
196  * \param i_count number of elements in the array
197  */
198 LIBVLC_API void
199 libvlc_media_discoverer_list_release( libvlc_media_discoverer_description **pp_services,
200                                       unsigned int i_count );
201
202 /**@} */
203
204 # ifdef __cplusplus
205 }
206 # endif
207
208 #endif /* <vlc/libvlc.h> */