Audio track and channel support for JavaScript API. The ActiveX vlc.audio.channel...
[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  *          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 /**
26  * \defgroup libvlc Libvlc
27  * This is libvlc, the base library of the VLC program.
28  *
29  * @{
30  */
31
32
33 #ifndef _LIBVLC_H
34 #define _LIBVLC_H 1
35
36 #include <vlc/vlc.h>
37
38 # ifdef __cplusplus
39 extern "C" {
40 # endif
41
42 /*****************************************************************************
43  * Exception handling
44  *****************************************************************************/
45 /** defgroup libvlc_exception Exceptions
46  * \ingroup libvlc
47  * LibVLC Exceptions handling
48  * @{
49  */
50
51 struct libvlc_exception_t
52 {
53     int b_raised;
54     int i_code;
55     char *psz_message;
56 };
57 typedef struct libvlc_exception_t libvlc_exception_t;
58
59 /**
60  * Initialize an exception structure. This can be called several times to reuse
61  * an exception structure.
62  * \param p_exception the exception to initialize
63  */
64 void libvlc_exception_init( libvlc_exception_t *p_exception );
65
66 /**
67  * Has an exception been raised ?
68  * \param p_exception the exception to query
69  * \return 0 if no exception raised, 1 else
70  */
71 int libvlc_exception_raised( libvlc_exception_t *p_exception );
72
73 /**
74  * Raise an exception
75  * \param p_exception the exception to raise
76  * \param psz_message the exception message
77  */
78 void libvlc_exception_raise( libvlc_exception_t *p_exception, const char *psz_format, ... );
79
80 /**
81  * Clear an exception object so it can be reused.
82  * The exception object must be initialized
83  * \param p_exception the exception to clear
84  */
85 void libvlc_exception_clear( libvlc_exception_t * );
86
87 /**
88  * Get exception message
89  * \param p_exception the exception to query
90  * \return the exception message or NULL if not applicable (exception not raised
91  * for example)
92  */
93 char* libvlc_exception_get_message( libvlc_exception_t *p_exception );
94
95 /**@} */
96
97 /*****************************************************************************
98  * Core handling
99  *****************************************************************************/
100
101 /** defgroup libvlc_core Core
102  * \ingroup libvlc
103  * LibVLC Core
104  * @{
105  */
106
107 /** This structure is opaque. It represents a libvlc instance */
108 typedef struct libvlc_instance_t libvlc_instance_t;
109
110 /**
111  * Create an initialized libvlc instance
112  * \param argc the number of arguments
113  * \param argv command-line-type arguments
114  * \param exception an initialized exception pointer
115  */
116 libvlc_instance_t * libvlc_new( int , char **, libvlc_exception_t *);
117
118 /**
119  * Returns a libvlc instance identifier for legacy APIs. Use of this
120  * function is discouraged, you should convert your program to use the
121  * new API.
122  * \param p_instance the instance
123  */
124 int libvlc_get_vlc_id( libvlc_instance_t *p_instance );
125
126 /**
127  * Destroy a libvlc instance.
128  * \param p_instance the instance to destroy
129  */
130 void libvlc_destroy( libvlc_instance_t *, libvlc_exception_t * );
131
132 /** @}*/
133
134 /*****************************************************************************
135  * Playlist
136  *****************************************************************************/
137 /** defgroup libvlc_playlist Playlist
138  * \ingroup libvlc
139  * LibVLC Playlist handling
140  * @{
141  */
142
143 /**
144  * Set loop variable
145  */
146 void libvlc_playlist_loop( libvlc_instance_t* , vlc_bool_t,
147                            libvlc_exception_t * );
148
149 /**
150  * Start playing. You can give some additionnal playlist item options
151  * that will be added to the item before playing it.
152  * \param p_instance the instance
153  * \param i_id the item to play. If this is a negative number, the next
154  * item will be selected. Else, the item with the given ID will be played
155  * \param i_options the number of options to add to the item
156  * \param ppsz_options the options to add to the item
157  * \param p_exception an initialized exception
158  */
159 void libvlc_playlist_play( libvlc_instance_t*, int, int, char **,
160                            libvlc_exception_t * );
161
162 /**
163  * Pause a running playlist, resume if it was stopped
164  * \param p_instance the instance to pause
165  * \param p_exception an initialized exception
166  */
167 void libvlc_playlist_pause( libvlc_instance_t *, libvlc_exception_t * );
168
169 /**
170  * Checks if the playlist is running
171  * \param p_instance the instance
172  * \param p_exception an initialized exception
173  * \return 0 if the playlist is stopped or paused, 1 if it is running
174  */
175 int libvlc_playlist_isplaying( libvlc_instance_t *, libvlc_exception_t * );
176
177 /**
178  * Get the number of items in the playlist
179  * \param p_instance the instance
180  * \param p_exception an initialized exception
181  * \return the number of items
182  */
183 int libvlc_playlist_items_count( libvlc_instance_t *, libvlc_exception_t * );
184
185 /**
186  * Stop playing
187  * \param p_instance the instance to stop
188  * \param p_exception an initialized exception
189  */
190 void libvlc_playlist_stop( libvlc_instance_t *, libvlc_exception_t * );
191
192 /**
193  * Go to next playlist item (starts playback if it was stopped)
194  * \param p_instance the instance to use
195  * \param p_exception an initialized exception
196  */
197 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
198
199 /**
200  * Go to previous playlist item (starts playback if it was stopped)
201  * \param p_instance the instance to use
202  * \param p_exception an initialized exception
203  */
204 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
205
206 /**
207  * Remove all playlist items
208  * \param p_instance the instance
209  * \param p_exception an initialized exception
210  */
211 void libvlc_playlist_clear( libvlc_instance_t *, libvlc_exception_t * );
212
213 /**
214  * Add an item at the end of the playlist
215  * If you need more advanced options, \see libvlc_playlist_add_extended
216  * \param p_instance the instance
217  * \param psz_uri the URI to open, using VLC format
218  * \param psz_name a name that you might want to give or NULL
219  * \return the identifier of the new item
220  */
221 int libvlc_playlist_add( libvlc_instance_t *, const char *, const char *,
222                          libvlc_exception_t * );
223
224 /**
225  * Add an item at the end of the playlist, with additional input options
226  * \param p_instance the instance
227  * \param psz_uri the URI to open, using VLC format
228  * \param psz_name a name that you might want to give or NULL
229  * \param i_options the number of options to add
230  * \param ppsz_options strings representing the options to add
231  * \param p_exception an initialized exception
232  * \return the identifier of the new item
233  */
234 int libvlc_playlist_add_extended( libvlc_instance_t *, const char *,
235                                   const char *, int, const char **,
236                                   libvlc_exception_t * );
237
238 /**
239  * Delete the playlist item with the given ID.
240  * \param p_instance the instance
241  * \param i_id the id to remove
242  * \param p_exception an initialized exception
243  * \return
244  */
245 int libvlc_playlist_delete_item( libvlc_instance_t *, int,
246                                  libvlc_exception_t * );
247
248 typedef struct libvlc_input_t libvlc_input_t;
249
250 /* Get the input that is currently being played by the playlist
251  * \param p_instance the instance to use
252  * \param p_exception an initialized excecption
253  * \return an input object
254  */
255 libvlc_input_t *libvlc_playlist_get_input( libvlc_instance_t *,
256                                            libvlc_exception_t * );
257
258 /** @}*/
259
260 /*****************************************************************************
261  * Input
262  *****************************************************************************/
263 /** defgroup libvlc_input Input
264  * \ingroup libvlc
265  * LibVLC Input handling
266  * @{
267  */
268
269 /** Free an input object
270  * \param p_input the input to free
271  */
272 void libvlc_input_free( libvlc_input_t * );
273
274 /// \bug This might go away ... to be replaced by a broader system
275 vlc_int64_t libvlc_input_get_length     ( libvlc_input_t *, libvlc_exception_t *);
276 vlc_int64_t libvlc_input_get_time       ( libvlc_input_t *, libvlc_exception_t *);
277 void        libvlc_input_set_time       ( libvlc_input_t *, vlc_int64_t, libvlc_exception_t *);
278 float       libvlc_input_get_position   ( libvlc_input_t *, libvlc_exception_t *);
279 void        libvlc_input_set_position   ( libvlc_input_t *, float, libvlc_exception_t *);
280 vlc_bool_t  libvlc_input_will_play      ( libvlc_input_t *, libvlc_exception_t *);
281 float       libvlc_input_get_rate       ( libvlc_input_t *, libvlc_exception_t *);
282 void        libvlc_input_set_rate       ( libvlc_input_t *, float, libvlc_exception_t *);
283 int         libvlc_input_get_state      ( libvlc_input_t *, libvlc_exception_t *);
284
285 /** @} */
286
287 /** defgroup libvlc_video Video
288  * \ingroup libvlc
289  * LibVLC Video handling
290  * @{
291  */
292
293 typedef int libvlc_drawable_t;
294
295 /**
296  * Does this input have a video output ?
297  * \param p_input the input
298  * \param p_exception an initialized exception
299  */
300 vlc_bool_t  libvlc_input_has_vout       ( libvlc_input_t *, libvlc_exception_t *);
301 float       libvlc_input_get_fps        ( libvlc_input_t *, libvlc_exception_t *);
302
303 /**
304  * Toggle fullscreen status on video output
305  * \param p_input the input
306  * \param p_exception an initialized exception
307  */
308 void libvlc_toggle_fullscreen( libvlc_input_t *, libvlc_exception_t * );
309
310 /**
311  * Enable or disable fullscreen on a video output
312  * \param p_input the input
313  * \param b_fullscreen boolean for fullscreen status
314  * \param p_exception an initialized exception
315  */
316 void libvlc_set_fullscreen( libvlc_input_t *, int, libvlc_exception_t * );
317
318 /**
319  * Get current fullscreen status
320  * \param p_input the input
321  * \param p_exception an initialized exception
322  * \return the fullscreen status (boolean)
323  */
324 int libvlc_get_fullscreen( libvlc_input_t *, libvlc_exception_t * );
325
326 /**
327  * Get current video height
328  * \param p_input the input
329  * \param p_exception an initialized exception
330  * \return the video height
331  */
332 int libvlc_video_get_height( libvlc_input_t *, libvlc_exception_t * );
333
334 /**
335  * Get current video width
336  * \param p_input the input
337  * \param p_exception an initialized exception
338  * \return the video width
339  */
340 int libvlc_video_get_width( libvlc_input_t *, libvlc_exception_t * );
341
342 /**
343  * Get current video aspect ratio
344  * \param p_input the input
345  * \param p_exception an initialized exception
346  * \return the video aspect ratio
347  */
348 char *libvlc_video_get_aspect_ratio( libvlc_input_t *, libvlc_exception_t * );
349
350 /**
351  * Set new video aspect ratio
352  * \param p_input the input
353  * \param psz_aspect new video aspect-ratio
354  * \param p_exception an initialized exception
355  */
356 void libvlc_video_set_aspect_ratio( libvlc_input_t *, char *, libvlc_exception_t * );
357
358 /**
359  * Take a snapshot of the current video window
360  * \param p_input the input
361  * \param psz_filepath the path where to save the screenshot to
362  * \param p_exception an initialized exception
363  */
364 void libvlc_video_take_snapshot( libvlc_input_t *, char *, libvlc_exception_t * );
365
366 int libvlc_video_destroy( libvlc_input_t *, libvlc_exception_t *);
367
368 /**
369  * Resize the current video output window
370  * \param p_instance libvlc instance
371  * \param width new width for video output window
372  * \param height new height for video output window
373  * \param p_exception an initialized exception
374  * \return the mute status (boolean)
375  */
376 void libvlc_video_resize( libvlc_input_t *, int, int, libvlc_exception_t *);
377
378 /**
379 * Downcast to this general type as placeholder for a platform specific one, such as:
380 *  Drawable on X11,
381 *  CGrafPort on MacOSX,
382 *  HWND on win32
383 */
384
385 /**
386  * change the parent for the current the video output
387  * \param p_instance libvlc instance
388  * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
389  * \param p_exception an initialized exception
390  * \return the mute status (boolean)
391  */
392 int libvlc_video_reparent( libvlc_input_t *, libvlc_drawable_t, libvlc_exception_t * );
393
394 /**
395  * Set the default video output parent
396  *  this settings will be used as default for all video outputs
397  * \param p_instance libvlc instance
398  * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
399  * \param p_exception an initialized exception
400  */
401 void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawable_t, libvlc_exception_t * );
402
403 /**
404  * Set the default video output size
405  *  this settings will be used as default for all video outputs
406  * \param p_instance libvlc instance
407  * \param width new width for video drawable
408  * \param height new height for video drawable
409  * \param p_exception an initialized exception
410  */
411 void libvlc_video_set_size( libvlc_instance_t *, int, int, libvlc_exception_t * );
412
413 /**
414 * Downcast to this general type as placeholder for a platform specific one, such as:
415 *  Drawable on X11,
416 *  CGrafPort on MacOSX,
417 *  HWND on win32
418 */
419 typedef struct
420 {
421     int top, left;
422     int bottom, right;
423 }
424 libvlc_rectangle_t;
425
426 /**
427  * Set the default video output viewport for a windowless video output (MacOS X only)
428  *  this settings will be used as default for all video outputs
429  * \param p_instance libvlc instance
430  * \param view coordinates within video drawable
431  * \param clip coordinates within video drawable
432  * \param p_exception an initialized exception
433  */
434 void libvlc_video_set_viewport( libvlc_instance_t *, const libvlc_rectangle_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
435
436
437 /** @} */
438
439 /**
440  * defgroup libvlc_vlm VLM
441  * \ingroup libvlc
442  * LibVLC VLM handling
443  * @{
444  */
445
446 /** defgroup libvlc_audio Audio
447  * \ingroup libvlc
448  * LibVLC Audio handling
449  * @{
450  */
451
452 /**
453  * Toggle mute status
454  * \param p_instance libvlc instance
455  * \param p_exception an initialized exception
456  * \return void
457  */
458 void libvlc_audio_toggle_mute( libvlc_instance_t *, libvlc_exception_t * );
459
460 /**
461  * Get current mute status
462  * \param p_instance libvlc instance
463  * \param p_exception an initialized exception
464  * \return the mute status (boolean)
465  */
466 vlc_bool_t libvlc_audio_get_mute( libvlc_instance_t *, libvlc_exception_t * );
467
468 /**
469  * Set mute status
470  * \param p_instance libvlc instance
471  * \param status If status is VLC_TRUE then mute, otherwise unmute
472  * \param p_exception an initialized exception
473  * \return void
474  */
475 void libvlc_audio_set_mute( libvlc_instance_t *, vlc_bool_t , libvlc_exception_t * );
476
477 /**
478  * Get current audio level
479  * \param p_instance libvlc instance
480  * \param p_exception an initialized exception
481  * \return the audio level (int)
482  */
483 int libvlc_audio_get_volume( libvlc_instance_t *, libvlc_exception_t * );
484
485 /**
486  * Set current audio level
487  * \param p_instance libvlc instance
488  * \param i_volume the volume (int)
489  * \param p_exception an initialized exception
490  * \return void
491  */
492 void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *);
493
494 /**
495 +  * Get current audio track
496 +  * \param p_input input instance
497 +  * \param p_exception an initialized exception
498 +  * \return the audio track (int)
499 +  */
500 int libvlc_audio_get_track( libvlc_input_t *, libvlc_exception_t * );
501
502 /**
503  * Set current audio track
504  * \param p_input input instance
505  * \param i_track the track (int)
506  * \param p_exception an initialized exception
507  * \return void
508  */
509 void libvlc_audio_set_track( libvlc_input_t *, int, libvlc_exception_t * );
510
511 /**
512  * Get current audio channel
513  * \param p_instance input instance
514  * \param p_exception an initialized exception
515  * \return the audio channel (char *)
516  */
517 char *libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * );
518
519 /**
520  * Set current audio channel
521  * \param p_instance input instance
522  * \param psz_channel the audio channel (char *)
523  * \param p_exception an initialized exception
524  * \return void
525  */
526 void libvlc_audio_set_channel( libvlc_instance_t *, char *, libvlc_exception_t * );
527
528 /** @} */
529
530
531 /**
532  * Add a broadcast, with one input
533  * \param p_instance the instance
534  * \param psz_name the name of the new broadcast
535  * \param psz_input the input MRL
536  * \param psz_output the output MRL (the parameter to the "sout" variable)
537  * \param i_options number of additional options
538  * \param ppsz_options additional options
539  * \param b_enabled boolean for enabling the new broadcast
540  * \param b_loop Should this broadcast be played in loop ?
541  * \param p_exception an initialized exception
542  */
543 void libvlc_vlm_add_broadcast( libvlc_instance_t *, char *, char *, char* ,
544                                int, char **, int, int, libvlc_exception_t * );
545
546 /**
547  * Delete a media (vod or broadcast)
548  * \param p_instance the instance
549  * \param psz_name the media to delete
550  * \param p_exception an initialized exception
551  */
552 void libvlc_vlm_del_media( libvlc_instance_t *, char *, libvlc_exception_t * );
553
554 /**
555  * Enable or disable a media (vod or broadcast)
556  * \param p_instance the instance
557  * \param psz_name the media to work on
558  * \param b_enabled the new status
559  * \param p_exception an initialized exception
560  */
561 void libvlc_vlm_set_enabled( libvlc_instance_t *, char *, int,
562                              libvlc_exception_t *);
563
564 /**
565  * Set the output for a media
566  * \param p_instance the instance
567  * \param psz_name the media to work on
568  * \param psz_output the output MRL (the parameter to the "sout" variable)
569  * \param p_exception an initialized exception
570  */
571 void libvlc_vlm_set_output( libvlc_instance_t *, char *, char*,
572                             libvlc_exception_t *);
573
574 /**
575  * Set a media's input MRL. This will delete all existing inputs and
576  * add the specified one.
577  * \param p_instance the instance
578  * \param psz_name the media to work on
579  * \param psz_input the input MRL
580  * \param p_exception an initialized exception
581  */
582 void libvlc_vlm_set_input( libvlc_instance_t *, char *, char*,
583                            libvlc_exception_t *);
584
585 /**
586  * Set output for a media
587  * \param p_instance the instance
588  * \param psz_name the media to work on
589  * \param b_loop the new status
590  * \param p_exception an initialized exception
591  */
592 void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int,
593                           libvlc_exception_t *);
594
595 /**
596  * Edit the parameters of a media. This will delete all existing inputs and
597  * add the specified one.
598  * \param p_instance the instance
599  * \param psz_name the name of the new broadcast
600  * \param psz_input the input MRL
601  * \param psz_output the output MRL (the parameter to the "sout" variable)
602  * \param i_options number of additional options
603  * \param ppsz_options additional options
604  * \param b_enabled boolean for enabling the new broadcast
605  * \param b_loop Should this broadcast be played in loop ?
606  * \param p_exception an initialized exception
607  */
608 void libvlc_vlm_change_media( libvlc_instance_t *, char *, char *, char* ,
609                               int, char **, int, int, libvlc_exception_t * );
610
611 /**
612  * Plays the named broadcast.
613  * \param p_instance the instance
614  * \param psz_name the name of the broadcast
615  * \param p_exception an initialized exception
616  */
617 void libvlc_vlm_play_media ( libvlc_instance_t *, char *, libvlc_exception_t * );
618
619 /**
620  * Stops the named broadcast.
621  * \param p_instance the instance
622  * \param psz_name the name of the broadcast
623  * \param p_exception an initialized exception
624  */ 
625 void libvlc_vlm_stop_media ( libvlc_instance_t *, char *, libvlc_exception_t * );
626
627 /**
628  * Pauses the named broadcast.
629  * \param p_instance the instance
630  * \param psz_name the name of the broadcast
631  * \param p_exception an initialized exception
632  */ 
633 void libvlc_vlm_pause_media( libvlc_instance_t *, char *, libvlc_exception_t * );
634     
635 /**
636  * Seeks in the named broadcast.
637  * \param p_instance the instance
638  * \param psz_name the name of the broadcast
639  * \param f_percentage the percentage to seek to
640  * \param p_exception an initialized exception
641  */ 
642 void libvlc_vlm_seek_media( libvlc_instance_t *, char *,
643                             float, libvlc_exception_t * );
644    
645 /**
646  * Return information of the named broadcast.
647  * \param p_instance the instance
648  * \param psz_name the name of the broadcast
649  * \param p_exception an initialized exception
650  */ 
651 char* libvlc_vlm_show_media( libvlc_instance_t *, char *, libvlc_exception_t * );
652
653 #define LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( attr, returnType, getType, default)\
654 returnType libvlc_vlm_get_media_## attr( libvlc_instance_t *, \
655                         char *, int , libvlc_exception_t * );
656
657 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( position, float, Float, -1);
658 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( time, int, Integer, -1);
659 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( length, int, Integer, -1);
660 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( rate, int, Integer, -1);
661 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( title, int, Integer, 0);
662 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( chapter, int, Integer, 0);
663 LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( seekable, int, Bool, 0);
664
665 #undef LIBVLC_VLM_GET_MEDIA_ATTRIBUTE
666
667 /** @} */
668 /** @} */
669
670 /*****************************************************************************
671  * Message log handling
672  *****************************************************************************/
673
674 /** defgroup libvlc_log Log
675  * \ingroup libvlc
676  * LibVLC Message Logging
677  * @{
678  */
679
680 /** This structure is opaque. It represents a libvlc log instance */
681 typedef struct libvlc_log_t libvlc_log_t;
682
683 /** This structure is opaque. It represents a libvlc log iterator */
684 typedef struct libvlc_log_iterator_t libvlc_log_iterator_t;
685
686 typedef struct libvlc_log_message_t
687 {
688     unsigned    sizeof_msg;   /* sizeof() of message structure, must be filled in by user */
689     int         i_severity;   /* 0=INFO, 1=ERR, 2=WARN, 3=DBG */
690     const char *psz_type;     /* module type */
691     const char *psz_name;     /* module name */
692     const char *psz_header;   /* optional header */
693     const char *psz_message;  /* message */
694 } libvlc_log_message_t;
695
696 /**
697  * Returns the VLC messaging verbosity level
698  * \param p_instance libvlc instance
699  * \param exception an initialized exception pointer
700  */
701 unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance, libvlc_exception_t *p_e );
702
703 /**
704  * Set the VLC messaging verbosity level
705  * \param p_log libvlc log instance
706  * \param exception an initialized exception pointer
707  */
708 void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level, libvlc_exception_t *p_e );
709
710 /**
711  * Open an instance to VLC message log 
712  * \param p_instance libvlc instance
713  * \param exception an initialized exception pointer
714  */
715 libvlc_log_t *libvlc_log_open( const libvlc_instance_t *, libvlc_exception_t *);
716
717 /**
718  * Close an instance of VLC message log 
719  * \param p_log libvlc log instance
720  * \param exception an initialized exception pointer
721  */
722 void libvlc_log_close( libvlc_log_t *, libvlc_exception_t *);
723
724 /**
725  * Returns the number of messages in log
726  * \param p_log libvlc log instance
727  * \param exception an initialized exception pointer
728  */
729 unsigned libvlc_log_count( const libvlc_log_t *, libvlc_exception_t *);
730
731 /**
732  * Clear all messages in log
733  *  the log should be cleared on a regular basis to avoid clogging
734  * \param p_log libvlc log instance
735  * \param exception an initialized exception pointer
736  */
737 void libvlc_log_clear( libvlc_log_t *, libvlc_exception_t *);
738
739 /**
740  * Allocate and returns a new iterator to messages in log
741  * \param p_log libvlc log instance
742  * \param exception an initialized exception pointer
743  */
744 libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
745
746 /**
747  * Releases a previoulsy allocated iterator
748  * \param p_log libvlc log iterator 
749  * \param exception an initialized exception pointer
750  */
751 void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e );
752
753 /**
754  * Returns whether log iterator has more messages 
755  * \param p_log libvlc log iterator
756  * \param exception an initialized exception pointer
757  */
758 int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e );
759
760 /**
761  * Returns next log message
762  *   the content of message must not be freed
763  * \param p_log libvlc log iterator
764  * \param exception an initialized exception pointer
765  */
766 libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
767                                                 struct libvlc_log_message_t *buffer,
768                                                 libvlc_exception_t *p_e );
769
770 /** @} */
771
772 # ifdef __cplusplus
773 }
774 # endif
775
776 #endif /* <vlc/libvlc.h> */