LGPL
[vlc.git] / include / vlc / libvlc_media_discoverer.h
1 /*****************************************************************************
2  * libvlc.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 /**
27  * \file
28  * This file defines libvlc_media_discoverer external API
29  */
30
31 #ifndef VLC_LIBVLC_MEDIA_DISCOVERER_H
32 #define VLC_LIBVLC_MEDIA_DISCOVERER_H 1
33
34 # ifdef __cplusplus
35 extern "C" {
36 # endif
37
38 /** \defgroup libvlc_media_discoverer LibVLC media discovery
39  * \ingroup libvlc
40  * LibVLC media discovery finds available media via various means.
41  * This corresponds to the service discovery functionality in VLC media player.
42  * Different plugins find potential medias locally (e.g. user media directory),
43  * from peripherals (e.g. video capture device), on the local network
44  * (e.g. SAP) or on the Internet (e.g. Internet radios).
45  * @{
46  */
47
48 typedef struct libvlc_media_discoverer_t libvlc_media_discoverer_t;
49
50 /**
51  * Discover media service by name.
52  *
53  * \param p_inst libvlc instance
54  * \param psz_name service name
55  * \return media discover object or NULL in case of error
56  */
57 LIBVLC_API libvlc_media_discoverer_t *
58 libvlc_media_discoverer_new_from_name( libvlc_instance_t * p_inst,
59                                        const char * psz_name );
60
61 /**
62  * Release media discover object. If the reference count reaches 0, then
63  * the object will be released.
64  *
65  * \param p_mdis media service discover object
66  */
67 LIBVLC_API void   libvlc_media_discoverer_release( libvlc_media_discoverer_t * p_mdis );
68
69 /**
70  * Get media service discover object its localized name.
71  *
72  * \param p_mdis media discover object
73  * \return localized name
74  */
75 LIBVLC_API char * libvlc_media_discoverer_localized_name( libvlc_media_discoverer_t * p_mdis );
76
77 /**
78  * Get media service discover media list.
79  *
80  * \param p_mdis media service discover object
81  * \return list of media items
82  */
83 LIBVLC_API libvlc_media_list_t * libvlc_media_discoverer_media_list( libvlc_media_discoverer_t * p_mdis );
84
85 /**
86  * Get event manager from media service discover object.
87  *
88  * \param p_mdis media service discover object
89  * \return event manager object.
90  */
91 LIBVLC_API libvlc_event_manager_t *
92         libvlc_media_discoverer_event_manager( libvlc_media_discoverer_t * p_mdis );
93
94 /**
95  * Query if media service discover object is running.
96  *
97  * \param p_mdis media service discover object
98  * \return true if running, false if not
99  *
100  * \libvlc_return_bool
101  */
102 LIBVLC_API int
103         libvlc_media_discoverer_is_running( libvlc_media_discoverer_t * p_mdis );
104
105 /**@} */
106
107 # ifdef __cplusplus
108 }
109 # endif
110
111 #endif /* <vlc/libvlc.h> */