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