Sync bindings/java with jvlc head (release is close ;).
[vlc.git] / include / vlc / libvlc.h
1 /*****************************************************************************
2  * libvlc.h:  libvlc_* new external API
3  *****************************************************************************
4  * Copyright (C) 1998-2005 the VideoLAN team
5  * $Id: vlc.h 13701 2005-12-12 17:58:56Z zorglub $
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23
24 /**
25  * \defgroup libvlc Libvlc
26  * This is libvlc, the base library of the VLC program.
27  *
28  * @{
29  */
30
31
32 #ifndef _LIBVLC_H
33 #define _LIBVLC_H 1
34
35 #include <vlc/vlc.h>
36
37 # ifdef __cplusplus
38 extern "C" {
39 # endif
40
41 /*****************************************************************************
42  * Exception handling
43  *****************************************************************************/
44 /** defgroup libvlc_exception Exceptions
45  * \ingroup libvlc
46  * LibVLC Exceptions handling
47  * @{
48  */
49
50 struct libvlc_exception_t
51 {
52     int b_raised;
53     char *psz_message;
54 };
55 typedef struct libvlc_exception_t libvlc_exception_t;
56
57 /**
58  * Initialize an exception structure. This can be called several times to reuse
59  * an exception structure.
60  * \param p_exception the exception to initialize
61  */
62 void libvlc_exception_init( libvlc_exception_t *p_exception );
63
64 /**
65  * Has an exception been raised ?
66  * \param p_exception the exception to query
67  * \return 0 if no exception raised, 1 else
68  */
69 int libvlc_exception_raised( libvlc_exception_t *p_exception );
70
71 /**
72  * Raise an exception
73  * \param p_exception the exception to raise
74  * \param psz_message the exception message
75  */
76 void libvlc_exception_raise( libvlc_exception_t *p_exception, char *psz_format, ... );
77
78 /**
79  * Clear an exception object so it can be reused.
80  * The exception object must be initialized
81  * \param p_exception the exception to clear
82  */
83 void libvlc_exception_clear( libvlc_exception_t * );
84
85 /**
86  * Get exception message
87  * \param p_exception the exception to query
88  * \return the exception message or NULL if not applicable (exception not raised
89  * for example)
90  */
91 char* libvlc_exception_get_message( libvlc_exception_t *p_exception );
92
93 /**@} */
94
95 /*****************************************************************************
96  * Core handling
97  *****************************************************************************/
98
99 /** defgroup libvlc_core Core
100  * \ingroup libvlc
101  * LibVLC Core
102  * @{
103  */
104
105 /** This structure is opaque. It represents a libvlc instance */
106 typedef struct libvlc_instance_t libvlc_instance_t;
107
108 /**
109  * Create an initialized libvlc instance
110  * \param argc the number of arguments
111  * \param argv command-line-type arguments
112  * \param exception an initialized exception pointer
113  */
114 libvlc_instance_t * libvlc_new( int , char **, libvlc_exception_t *);
115
116 /**
117  * Destroy a libvlc instance
118  * \param p_instance the instance to destroy
119  */
120 void libvlc_destroy( libvlc_instance_t *);
121
122 /** @}*/
123
124 /*****************************************************************************
125  * Playlist
126  *****************************************************************************/
127 /** defgroup libvlc_playlist Playlist
128  * \ingroup libvlc
129  * LibVLC Playlist handling
130  * @{
131  */
132
133 /**
134  * Start playing. You can give some additionnal playlist item options
135  * that will be added to the item before playing it.
136  * \param p_instance the instance
137  * \param i_id the item to play. If this is a negative number, the next
138  * item will be selected. Else, the item with the given ID will be played
139  * \param i_options the number of options to add to the item
140  * \param ppsz_options the options to add to the item
141  * \param p_exception an initialized exception
142  */
143 void libvlc_playlist_play( libvlc_instance_t*, int, int, char **,
144                            libvlc_exception_t * );
145
146 /**
147  * Pause a running playlist, resume if it was stopped
148  * \param p_instance the instance to pause
149  * \param p_exception an initialized exception
150  */
151 void libvlc_playlist_pause( libvlc_instance_t *, libvlc_exception_t * );
152
153 /**
154  * Checks if the playlist is running
155  * \param p_instance the instance
156  * \param p_exception an initialized exception
157  * \return 0 if the playlist is stopped or paused, 1 if it is running
158  */
159 int libvlc_playlist_isplaying( libvlc_instance_t *, libvlc_exception_t * );
160
161 /**
162  * Get the number of items in the playlist
163  * \param p_instance the instance
164  * \param p_exception an initialized exception
165  * \return the number of items
166  */
167 int libvlc_playlist_items_count( libvlc_instance_t *, libvlc_exception_t * );
168
169 /**
170  * Stop playing
171  * \param p_instance the instance to stop
172  * \param p_exception an initialized exception
173  */
174 void libvlc_playlist_stop( libvlc_instance_t *, libvlc_exception_t * );
175
176 /**
177  * Go to next playlist item (starts playback if it was stopped)
178  * \param p_instance the instance to use
179  * \param p_exception an initialized exception
180  */
181 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
182
183 /**
184  * Go to previous playlist item (starts playback if it was stopped)
185  * \param p_instance the instance to use
186  * \param p_exception an initialized exception
187  */
188 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
189
190 /**
191  * Remove all playlist items
192  * \param p_instance the instance
193  * \param p_exception an initialized exception
194  */
195 void libvlc_playlist_clear( libvlc_instance_t *, libvlc_exception_t * );
196
197 /**
198  * Go to next playlist item
199  * \param p_instance the instance
200  * \param p_exception an initialized exception
201  */
202 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
203
204 /**
205  * Go to Previous playlist item
206  * \param p_instance the instance
207  * \param p_exception an initialized exception
208  */
209 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
210
211 /**
212  * Add an item at the end of the playlist
213  * If you need more advanced options, \see libvlc_playlist_add_extended
214  * \param p_instance the instance
215  * \param psz_uri the URI to open, using VLC format
216  * \param psz_name a name that you might want to give or NULL
217  * \return the identifier of the new item
218  */
219 int libvlc_playlist_add( libvlc_instance_t *, const char *, const char *,
220                          libvlc_exception_t * );
221
222 /**
223  * Add an item at the end of the playlist, with additional input options
224  * \param p_instance the instance
225  * \param psz_uri the URI to open, using VLC format
226  * \param psz_name a name that you might want to give or NULL
227  * \param i_options the number of options to add
228  * \param ppsz_options strings representing the options to add
229  * \return the identifier of the new item
230  */
231 int libvlc_playlist_add_extended( libvlc_instance_t *, const char *,
232                                   const char *, int, const char **,
233                                   libvlc_exception_t * );
234
235
236 int libvlc_playlist_delete_item( libvlc_instance_t *, int,
237                                  libvlc_exception_t * );
238     
239 typedef struct libvlc_input_t libvlc_input_t;
240
241 /* Get the input that is currently being played by the playlist
242  * \param p_instance the instance to use
243  * \param p_exception an initialized excecption
244  * \return an input object
245  */
246 libvlc_input_t *libvlc_playlist_get_input( libvlc_instance_t *,
247                                            libvlc_exception_t * );
248
249
250
251 /** @}*/
252
253 /*****************************************************************************
254  * Input
255  *****************************************************************************/
256 /** defgroup libvlc_input Input
257  * \ingroup libvlc
258  * LibVLC Input handling
259  * @{
260  */
261
262 /** Free an input object
263  * \param p_input the input to free
264  */
265 void libvlc_input_free( libvlc_input_t * );
266
267 /// \bug This might go away ... to be replaced by a broader system
268 vlc_int64_t libvlc_input_get_length     ( libvlc_input_t *, libvlc_exception_t *);
269 vlc_int64_t libvlc_input_get_time       ( libvlc_input_t *, libvlc_exception_t *);
270 float       libvlc_input_get_position   ( libvlc_input_t *, libvlc_exception_t *);
271 vlc_bool_t  libvlc_input_will_play      ( libvlc_input_t *, libvlc_exception_t *);
272 vlc_bool_t  libvlc_input_has_vout       ( libvlc_input_t *, libvlc_exception_t *);
273 float       libvlc_input_get_fps        ( libvlc_input_t *, libvlc_exception_t *);
274         
275 /** @} */
276
277 /** defgroup libvlc_video Video
278  * \ingroup libvlc
279  * LibVLC Video handling
280  * @{
281  */
282
283 /**
284  * Toggle fullscreen status on video output
285  * \param p_input the input
286  * \param p_exception an initialized exception
287  */
288 void libvlc_toggle_fullscreen( libvlc_input_t *, libvlc_exception_t * );
289
290 /**
291  * Enable or disable fullscreen on a video output
292  * \param p_input the input
293  * \param b_fullscreen boolean for fullscreen status
294  * \param p_exception an initialized exception
295  */
296 void libvlc_set_fullscreen( libvlc_input_t *, int, libvlc_exception_t * );
297
298 /**
299  * Get current fullscreen status
300  * \param p_input the input
301  * \param p_exception an initialized exception
302  * \return the fullscreen status (boolean)
303  */
304 int libvlc_get_fullscreen( libvlc_input_t *, libvlc_exception_t * );
305     
306 /**
307  * Get current video height
308  * \param p_input the input
309  * \param p_exception an initialized exception
310  * \return the video height
311  */
312 int libvlc_video_get_height( libvlc_input_t *, libvlc_exception_t * );
313
314 /**
315  * Get current video width
316  * \param p_input the input
317  * \param p_exception an initialized exception
318  * \return the video width
319  */
320 int libvlc_video_get_width( libvlc_input_t *, libvlc_exception_t * );
321
322 /**
323  * Take a snapshot of the current video window
324  * \param p_input the input
325  * \param psz_filepath the path where to save the screenshot to
326  * \param p_exception an initialized exception
327  */
328 void libvlc_video_take_snapshot( libvlc_input_t *, char *, libvlc_exception_t * );
329     
330
331 /** @} */
332
333 /**
334  * defgroup libvlc_vlm VLM
335  * \ingroup libvlc
336  * LibVLC VLM handling
337  * @{
338  */
339
340 /** defgroup libvlc_audio Audio
341  * \ingroup libvlc
342  * LibVLC Audio handling
343  * @{
344  */
345
346 /**
347  * Get current mute status
348  * \param p_instance libvlc instance
349  * \param p_exception an initialized exception
350  * \return the mute status (boolean)
351  */
352 vlc_bool_t libvlc_audio_get_mute( libvlc_instance_t *, libvlc_exception_t * );
353
354 /**
355  * Set mute status
356  * \param p_instance libvlc instance
357  * \param status If status is VLC_TRUE then mute, otherwise unmute
358  * \param p_exception an initialized exception
359  * \return void
360  */
361 void libvlc_audio_set_mute( libvlc_instance_t *, vlc_bool_t , libvlc_exception_t * );
362
363
364 /**
365  * Get current audio level
366  * \param p_instance libvlc instance
367  * \param p_exception an initialized exception
368  * \return the audio level (int)
369  */
370 int libvlc_audio_get_volume( libvlc_instance_t *, libvlc_exception_t * );
371
372
373 /**
374  * Set current audio level
375  * \param p_instance libvlc instance
376  * \param i_volume the volume (int)
377  * \param p_exception an initialized exception
378  * \return void
379  */
380 void libvlc_audio_set_volume( libvlc_instance_t *, int , libvlc_exception_t *);
381
382 /** @} */
383
384
385 /**
386  * Add a broadcast, with one input
387  * \param p_instance the instance
388  * \param psz_name the name of the new broadcast
389  * \param psz_input the input MRL
390  * \param psz_output the output MRL (the parameter to the "sout" variable)
391  * \param i_options number of additional options
392  * \param ppsz_options additional options
393  * \param b_enabled boolean for enabling the new broadcast
394  * \param b_loop Should this broadcast be played in loop ?
395  * \param p_exception an initialized exception
396  */
397 void libvlc_vlm_add_broadcast( libvlc_instance_t *, char *, char *, char* ,
398                                int, char **, int, int, libvlc_exception_t * );
399
400 /**
401  * Delete a media (vod or broadcast)
402  * \param p_instance the instance
403  * \param psz_name the media to delete
404  * \param p_exception an initialized exception
405  */
406 void libvlc_vlm_del_media( libvlc_instance_t *, char *, libvlc_exception_t * );
407
408 /**
409  * Enable or disable a media (vod or broadcast)
410  * \param p_instance the instance
411  * \param psz_name the media to work on
412  * \param b_enabled the new status
413  * \param p_exception an initialized exception
414  */
415 void libvlc_vlm_set_enabled( libvlc_instance_t *, char *, int,
416                              libvlc_exception_t *);
417
418 /**
419  * Set the output for a media
420  * \param p_instance the instance
421  * \param psz_name the media to work on
422  * \param psz_output the output MRL (the parameter to the "sout" variable)
423  * \param p_exception an initialized exception
424  */
425 void libvlc_vlm_set_output( libvlc_instance_t *, char *, char*,
426                             libvlc_exception_t *);
427
428 /**
429  * Set a media's input MRL. This will delete all existing inputs and
430  * add the specified one.
431  * \param p_instance the instance
432  * \param psz_name the media to work on
433  * \param psz_input the input MRL
434  * \param p_exception an initialized exception
435  */
436 void libvlc_vlm_set_input( libvlc_instance_t *, char *, char*,
437                            libvlc_exception_t *);
438
439
440
441 /**
442  * Set output for a media
443  * \param p_instance the instance
444  * \param psz_name the media to work on
445  * \param b_loop the new status
446  * \param p_exception an initialized exception
447  */
448 void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int,
449                           libvlc_exception_t *);
450
451
452
453
454 /**
455  * Edit the parameters of a media. This will delete all existing inputs and
456  * add the specified one.
457  * \param p_instance the instance
458  * \param psz_name the name of the new broadcast
459  * \param psz_input the input MRL
460  * \param psz_output the output MRL (the parameter to the "sout" variable)
461  * \param i_options number of additional options
462  * \param ppsz_options additional options
463  * \param b_enabled boolean for enabling the new broadcast
464  * \param b_loop Should this broadcast be played in loop ?
465  * \param p_exception an initialized exception
466  */
467 void libvlc_vlm_change_media( libvlc_instance_t *, char *, char *, char* ,
468                               int, char **, int, int, libvlc_exception_t * );
469
470
471 /** @} */
472 /** @} */
473
474 # ifdef __cplusplus
475 }
476 # endif
477
478 #endif /* <vlc/libvlc.h> */