libvlc_media_discoverer.h 5.92 KB
Newer Older
1
/*****************************************************************************
Pere Orga's avatar
Pere Orga committed
2
 * libvlc_media_discoverer.h:  libvlc external API
3
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
4
 * Copyright (C) 1998-2009 VLC authors and VideoLAN
5 6 7 8 9 10
 * $Id$
 *
 * Authors: Clément Stenac <zorglub@videolan.org>
 *          Jean-Paul Saman <jpsaman@videolan.org>
 *          Pierre d'Herbemont <pdherbemont@videolan.org>
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
11 12 13
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
14 15 16 17
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
18 19
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
20
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
21 22 23
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 25 26 27 28
 *****************************************************************************/

#ifndef VLC_LIBVLC_MEDIA_DISCOVERER_H
#define VLC_LIBVLC_MEDIA_DISCOVERER_H 1

29 30 31 32
# ifdef __cplusplus
extern "C" {
# endif

33
/**
34 35
 * Category of a media discoverer
 * \see libvlc_media_discoverer_list_get()
36
 */
37
typedef enum libvlc_media_discoverer_category_t {
38 39 40 41 42 43 44 45
    /** devices, like portable music player */
    libvlc_media_discoverer_devices,
    /** LAN/WAN services, like Upnp, SMB, or SAP */
    libvlc_media_discoverer_lan,
    /** Podcasts */
    libvlc_media_discoverer_podcasts,
    /** Local directories, like Video, Music or Pictures directories */
    libvlc_media_discoverer_localdirs,
46
} libvlc_media_discoverer_category_t;
47 48

/**
49 50
 * Media discoverer description
 * \see libvlc_media_discoverer_list_get()
51
 */
52
typedef struct libvlc_media_discoverer_description_t {
53 54
    char *psz_name;
    char *psz_longname;
55 56
    libvlc_media_discoverer_category_t i_cat;
} libvlc_media_discoverer_description_t;
57

58
/** \defgroup libvlc_media_discoverer LibVLC media discovery
59
 * \ingroup libvlc
60 61 62 63 64
 * LibVLC media discovery finds available media via various means.
 * This corresponds to the service discovery functionality in VLC media player.
 * Different plugins find potential medias locally (e.g. user media directory),
 * from peripherals (e.g. video capture device), on the local network
 * (e.g. SAP) or on the Internet (e.g. Internet radios).
65
 * @{
66 67
 * \file
 * LibVLC media discovery external API
68 69 70 71
 */

typedef struct libvlc_media_discoverer_t libvlc_media_discoverer_t;

72 73 74
/**
 * Create a media discoverer object by name.
 *
75 76
 * After this object is created, you should attach to media_list events in
 * order to be notified of new items discovered.
77 78 79 80 81 82 83
 *
 * You need to call libvlc_media_discoverer_start() in order to start the
 * discovery.
 *
 * \see libvlc_media_discoverer_media_list
 * \see libvlc_media_discoverer_event_manager
 * \see libvlc_media_discoverer_start
84 85
 *
 * \param p_inst libvlc instance
86 87
 * \param psz_name service name; use libvlc_media_discoverer_list_get() to get
 * 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 93 94 95 96 97 98
libvlc_media_discoverer_new( libvlc_instance_t * p_inst,
                             const char * psz_name );

/**
 * Start media discovery.
 *
 * To stop it, call libvlc_media_discoverer_stop() or
99
 * libvlc_media_discoverer_list_release() directly.
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
 *
 * \see libvlc_media_discoverer_stop
 *
 * \param p_mdis media discover object
 * \return -1 in case of error, 0 otherwise
 * \version LibVLC 3.0.0 or later
 */
LIBVLC_API int
libvlc_media_discoverer_start( libvlc_media_discoverer_t * p_mdis );

/**
 * Stop media discovery.
 *
 * \see libvlc_media_discoverer_start
 *
 * \param p_mdis media discover object
 * \version LibVLC 3.0.0 or later
 */
LIBVLC_API void
libvlc_media_discoverer_stop( libvlc_media_discoverer_t * p_mdis );
120 121 122 123 124 125 126

/**
 * Release media discover object. If the reference count reaches 0, then
 * the object will be released.
 *
 * \param p_mdis media service discover object
 */
Thomas Guillem's avatar
Thomas Guillem committed
127 128
LIBVLC_API void
libvlc_media_discoverer_release( libvlc_media_discoverer_t * p_mdis );
129 130 131 132 133 134 135

/**
 * Get media service discover media list.
 *
 * \param p_mdis media service discover object
 * \return list of media items
 */
Thomas Guillem's avatar
Thomas Guillem committed
136 137
LIBVLC_API libvlc_media_list_t *
libvlc_media_discoverer_media_list( libvlc_media_discoverer_t * p_mdis );
138 139 140 141 142 143

/**
 * Query if media service discover object is running.
 *
 * \param p_mdis media service discover object
 * \return true if running, false if not
144 145
 *
 * \libvlc_return_bool
146
 */
147
LIBVLC_API int
Thomas Guillem's avatar
Thomas Guillem committed
148
libvlc_media_discoverer_is_running( libvlc_media_discoverer_t * p_mdis );
149

150 151 152 153 154 155 156 157
/**
 * Get media discoverer services by category
 *
 * \version LibVLC 3.0.0 and later.
 *
 * \param p_inst libvlc instance
 * \param i_cat category of services to fetch
 * \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 160
 * the caller) [OUT]
 *
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 166
                                  libvlc_media_discoverer_category_t i_cat,
                                  libvlc_media_discoverer_description_t ***ppp_services );
167 168 169 170 171 172

/**
 * Release an array of media discoverer services
 *
 * \version LibVLC 3.0.0 and later.
 *
173
 * \see libvlc_media_discoverer_list_get()
174 175 176 177 178
 *
 * \param pp_services array to release
 * \param i_count number of elements in the array
 */
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 185 186 187
# ifdef __cplusplus
}
# endif

188
#endif /* <vlc/libvlc.h> */