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