LGPL
[vlc.git] / include / vlc / libvlc_vlm.h
1 /*****************************************************************************
2  * libvlc_vlm.h:  libvlc_* new external API
3  *****************************************************************************
4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
5  * $Id$
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
9  *
10  * This program is free software; you can redistribute it and/or modify it
11  * under the terms of the GNU Lesser General Public License as published by
12  * the Free Software Foundation; either version 2.1 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public License
21  * along with this program; if not, write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23  *****************************************************************************/
24
25 #ifndef LIBVLC_VLM_H
26 #define LIBVLC_VLM_H 1
27
28 /**
29  * \file
30  * This file defines libvlc_vlm_* external API
31  */
32
33 # ifdef __cplusplus
34 extern "C" {
35 # endif
36
37 /*****************************************************************************
38  * VLM
39  *****************************************************************************/
40 /** \defgroup libvlc_vlm LibVLC VLM
41  * \ingroup libvlc
42  * @{
43  */
44
45
46 /**
47  * Release the vlm instance related to the given libvlc_instance_t
48  *
49  * \param p_instance the instance
50  */
51 LIBVLC_API void libvlc_vlm_release( libvlc_instance_t *p_instance );
52
53 /**
54  * Add a broadcast, with one input.
55  *
56  * \param p_instance the instance
57  * \param psz_name the name of the new broadcast
58  * \param psz_input the input MRL
59  * \param psz_output the output MRL (the parameter to the "sout" variable)
60  * \param i_options number of additional options
61  * \param ppsz_options additional options
62  * \param b_enabled boolean for enabling the new broadcast
63  * \param b_loop Should this broadcast be played in loop ?
64  * \return 0 on success, -1 on error
65  */
66 LIBVLC_API int libvlc_vlm_add_broadcast( libvlc_instance_t *p_instance,
67                                              const char *psz_name, const char *psz_input,
68                                              const char *psz_output, int i_options,
69                                              const char * const* ppsz_options,
70                                              int b_enabled, int b_loop );
71
72 /**
73  * Add a vod, with one input.
74  *
75  * \param p_instance the instance
76  * \param psz_name the name of the new vod media
77  * \param psz_input the input MRL
78  * \param i_options number of additional options
79  * \param ppsz_options additional options
80  * \param b_enabled boolean for enabling the new vod
81  * \param psz_mux the muxer of the vod media
82  * \return 0 on success, -1 on error
83  */
84 LIBVLC_API int libvlc_vlm_add_vod( libvlc_instance_t * p_instance,
85                                        const char *psz_name, const char *psz_input,
86                                        int i_options, const char * const* ppsz_options,
87                                        int b_enabled, const char *psz_mux );
88
89 /**
90  * Delete a media (VOD or broadcast).
91  *
92  * \param p_instance the instance
93  * \param psz_name the media to delete
94  * \return 0 on success, -1 on error
95  */
96 LIBVLC_API int libvlc_vlm_del_media( libvlc_instance_t * p_instance,
97                                          const char *psz_name );
98
99 /**
100  * Enable or disable a media (VOD or broadcast).
101  *
102  * \param p_instance the instance
103  * \param psz_name the media to work on
104  * \param b_enabled the new status
105  * \return 0 on success, -1 on error
106  */
107 LIBVLC_API int libvlc_vlm_set_enabled( libvlc_instance_t *p_instance,
108                                            const char *psz_name, int b_enabled );
109
110 /**
111  * Set the output for a media.
112  *
113  * \param p_instance the instance
114  * \param psz_name the media to work on
115  * \param psz_output the output MRL (the parameter to the "sout" variable)
116  * \return 0 on success, -1 on error
117  */
118 LIBVLC_API int libvlc_vlm_set_output( libvlc_instance_t *p_instance,
119                                           const char *psz_name,
120                                           const char *psz_output );
121
122 /**
123  * Set a media's input MRL. This will delete all existing inputs and
124  * add the specified one.
125  *
126  * \param p_instance the instance
127  * \param psz_name the media to work on
128  * \param psz_input the input MRL
129  * \return 0 on success, -1 on error
130  */
131 LIBVLC_API int libvlc_vlm_set_input( libvlc_instance_t *p_instance,
132                                          const char *psz_name,
133                                          const char *psz_input );
134
135 /**
136  * Add a media's input MRL. This will add the specified one.
137  *
138  * \param p_instance the instance
139  * \param psz_name the media to work on
140  * \param psz_input the input MRL
141  * \return 0 on success, -1 on error
142  */
143 LIBVLC_API int libvlc_vlm_add_input( libvlc_instance_t *p_instance,
144                                          const char *psz_name,
145                                          const char *psz_input );
146
147 /**
148  * Set a media's loop status.
149  *
150  * \param p_instance the instance
151  * \param psz_name the media to work on
152  * \param b_loop the new status
153  * \return 0 on success, -1 on error
154  */
155 LIBVLC_API int libvlc_vlm_set_loop( libvlc_instance_t *p_instance,
156                                         const char *psz_name,
157                                         int b_loop );
158
159 /**
160  * Set a media's vod muxer.
161  *
162  * \param p_instance the instance
163  * \param psz_name the media to work on
164  * \param psz_mux the new muxer
165  * \return 0 on success, -1 on error
166  */
167 LIBVLC_API int libvlc_vlm_set_mux( libvlc_instance_t *p_instance,
168                                        const char *psz_name,
169                                        const char *psz_mux );
170
171 /**
172  * Edit the parameters of a media. This will delete all existing inputs and
173  * add the specified one.
174  *
175  * \param p_instance the instance
176  * \param psz_name the name of the new broadcast
177  * \param psz_input the input MRL
178  * \param psz_output the output MRL (the parameter to the "sout" variable)
179  * \param i_options number of additional options
180  * \param ppsz_options additional options
181  * \param b_enabled boolean for enabling the new broadcast
182  * \param b_loop Should this broadcast be played in loop ?
183  * \return 0 on success, -1 on error
184  */
185 LIBVLC_API int libvlc_vlm_change_media( libvlc_instance_t *p_instance,
186                                             const char *psz_name, const char *psz_input,
187                                             const char *psz_output, int i_options,
188                                             const char * const *ppsz_options,
189                                             int b_enabled, int b_loop );
190
191 /**
192  * Play the named broadcast.
193  *
194  * \param p_instance the instance
195  * \param psz_name the name of the broadcast
196  * \return 0 on success, -1 on error
197  */
198 LIBVLC_API int libvlc_vlm_play_media ( libvlc_instance_t *p_instance,
199                                            const char *psz_name );
200
201 /**
202  * Stop the named broadcast.
203  *
204  * \param p_instance the instance
205  * \param psz_name the name of the broadcast
206  * \return 0 on success, -1 on error
207  */
208 LIBVLC_API int libvlc_vlm_stop_media ( libvlc_instance_t *p_instance,
209                                            const char *psz_name );
210
211 /**
212  * Pause the named broadcast.
213  *
214  * \param p_instance the instance
215  * \param psz_name the name of the broadcast
216  * \return 0 on success, -1 on error
217  */
218 LIBVLC_API int libvlc_vlm_pause_media( libvlc_instance_t *p_instance,
219                                            const char *psz_name );
220
221 /**
222  * Seek in the named broadcast.
223  *
224  * \param p_instance the instance
225  * \param psz_name the name of the broadcast
226  * \param f_percentage the percentage to seek to
227  * \return 0 on success, -1 on error
228  */
229 LIBVLC_API int libvlc_vlm_seek_media( libvlc_instance_t *p_instance,
230                                           const char *psz_name,
231                                           float f_percentage );
232
233 /**
234  * Return information about the named media as a JSON
235  * string representation.
236  *
237  * This function is mainly intended for debugging use,
238  * if you want programmatic access to the state of
239  * a vlm_media_instance_t, please use the corresponding
240  * libvlc_vlm_get_media_instance_xxx -functions.
241  * Currently there are no such functions available for
242  * vlm_media_t though.
243  *
244  * \param p_instance the instance
245  * \param psz_name the name of the media,
246  *      if the name is an empty string, all media is described
247  * \return string with information about named media, or NULL on error
248  */
249 LIBVLC_API const char* libvlc_vlm_show_media( libvlc_instance_t *p_instance,
250                                                   const char *psz_name );
251
252 /**
253  * Get vlm_media instance position by name or instance id
254  *
255  * \param p_instance a libvlc instance
256  * \param psz_name name of vlm media instance
257  * \param i_instance instance id
258  * \return position as float or -1. on error
259  */
260 LIBVLC_API float libvlc_vlm_get_media_instance_position( libvlc_instance_t *p_instance,
261                                                              const char *psz_name,
262                                                              int i_instance );
263
264 /**
265  * Get vlm_media instance time by name or instance id
266  *
267  * \param p_instance a libvlc instance
268  * \param psz_name name of vlm media instance
269  * \param i_instance instance id
270  * \return time as integer or -1 on error
271  */
272 LIBVLC_API int libvlc_vlm_get_media_instance_time( libvlc_instance_t *p_instance,
273                                                        const char *psz_name,
274                                                        int i_instance );
275
276 /**
277  * Get vlm_media instance length by name or instance id
278  *
279  * \param p_instance a libvlc instance
280  * \param psz_name name of vlm media instance
281  * \param i_instance instance id
282  * \return length of media item or -1 on error
283  */
284 LIBVLC_API int libvlc_vlm_get_media_instance_length( libvlc_instance_t *p_instance,
285                                                          const char *psz_name,
286                                                          int i_instance );
287
288 /**
289  * Get vlm_media instance playback rate by name or instance id
290  *
291  * \param p_instance a libvlc instance
292  * \param psz_name name of vlm media instance
293  * \param i_instance instance id
294  * \return playback rate or -1 on error
295  */
296 LIBVLC_API int libvlc_vlm_get_media_instance_rate( libvlc_instance_t *p_instance,
297                                                        const char *psz_name,
298                                                        int i_instance );
299 #if 0
300 /**
301  * Get vlm_media instance title number by name or instance id
302  * \bug will always return 0
303  * \param p_instance a libvlc instance
304  * \param psz_name name of vlm media instance
305  * \param i_instance instance id
306  * \return title as number or -1 on error
307  */
308 LIBVLC_API int libvlc_vlm_get_media_instance_title( libvlc_instance_t *,
309                                                         const char *, int );
310
311 /**
312  * Get vlm_media instance chapter number by name or instance id
313  * \bug will always return 0
314  * \param p_instance a libvlc instance
315  * \param psz_name name of vlm media instance
316  * \param i_instance instance id
317  * \return chapter as number or -1 on error
318  */
319 LIBVLC_API int libvlc_vlm_get_media_instance_chapter( libvlc_instance_t *,
320                                                           const char *, int );
321
322 /**
323  * Is libvlc instance seekable ?
324  * \bug will always return 0
325  * \param p_instance a libvlc instance
326  * \param psz_name name of vlm media instance
327  * \param i_instance instance id
328  * \return 1 if seekable, 0 if not, -1 if media does not exist
329  */
330 LIBVLC_API int libvlc_vlm_get_media_instance_seekable( libvlc_instance_t *,
331                                                            const char *, int );
332 #endif
333 /**
334  * Get libvlc_event_manager from a vlm media.
335  * The p_event_manager is immutable, so you don't have to hold the lock
336  *
337  * \param p_instance a libvlc instance
338  * \return libvlc_event_manager
339  */
340 LIBVLC_API libvlc_event_manager_t *
341     libvlc_vlm_get_event_manager( libvlc_instance_t *p_instance );
342
343 /** @} */
344
345 # ifdef __cplusplus
346 }
347 # endif
348
349 #endif /* <vlc/libvlc_vlm.h> */