]> git.sesse.net Git - vlc/blob - include/vlc/libvlc.h
libvlc: libvlc_video_set_parent and libvlc_video_get_parent are deprecated.
[vlc] / include / vlc / libvlc.h
1 /*****************************************************************************
2  * libvlc.h:  libvlc external API
3  *****************************************************************************
4  * Copyright (C) 1998-2005 the VideoLAN team
5  * $Id$
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24  *****************************************************************************/
25
26 /**
27  * \defgroup libvlc libvlc
28  * This is libvlc, the base library of the VLC program.
29  *
30  * @{
31  */
32
33
34 #ifndef VLC_LIBVLC_H
35 #define VLC_LIBVLC_H 1
36
37 #if defined (WIN32) && defined (DLL_EXPORT)
38 # define VLC_PUBLIC_API __declspec(dllexport)
39 #else
40 # define VLC_PUBLIC_API
41 #endif
42
43 #ifdef __LIBVLC__
44 /* Avoid unuseful warnings from libvlc with our deprecated APIs */
45 #   define VLC_DEPRECATED_API VLC_PUBLIC_API
46 #elif defined(__GNUC__) && \
47       (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
48 # define VLC_DEPRECATED_API VLC_PUBLIC_API __attribute__((deprecated))
49 #else
50 # define VLC_DEPRECATED_API VLC_PUBLIC_API
51 #endif
52
53 # ifdef __cplusplus
54 extern "C" {
55 # endif
56
57 /*****************************************************************************
58  * Exception handling
59  *****************************************************************************/
60 /** \defgroup libvlc_exception libvlc_exception
61  * \ingroup libvlc_core
62  * LibVLC Exceptions handling
63  * @{
64  */
65
66 /**
67  * Initialize an exception structure. This can be called several times to
68  * reuse an exception structure.
69  *
70  * \param p_exception the exception to initialize
71  */
72 VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
73
74 /**
75  * Has an exception been raised?
76  *
77  * \param p_exception the exception to query
78  * \return 0 if the exception was raised, 1 otherwise
79  */
80 VLC_PUBLIC_API int
81 libvlc_exception_raised( const libvlc_exception_t *p_exception );
82
83 /**
84  * Raise an exception using a user-provided message.
85  *
86  * \param p_exception the exception to raise
87  * \param psz_format the exception message format string
88  * \param ... the format string arguments
89  */
90 VLC_PUBLIC_API void
91 libvlc_exception_raise( libvlc_exception_t *p_exception,
92                         const char *psz_format, ... );
93
94 /**
95  * Clear an exception object so it can be reused.
96  * The exception object must have be initialized.
97  *
98  * \param p_exception the exception to clear
99  */
100 VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
101
102 /**
103  * Get an exception's message.
104  *
105  * \param p_exception the exception to query
106  * \return the exception message or NULL if not applicable (exception not
107  *         raised, for example)
108  */
109 VLC_PUBLIC_API const char *
110 libvlc_exception_get_message( const libvlc_exception_t *p_exception );
111
112 /**@} */
113
114 /*****************************************************************************
115  * Core handling
116  *****************************************************************************/
117
118 /** \defgroup libvlc_core libvlc_core
119  * \ingroup libvlc
120  * LibVLC Core
121  * @{
122  */
123
124 /**
125  * Create and initialize a libvlc instance.
126  *
127  * \param argc the number of arguments
128  * \param argv command-line-type arguments. argv[0] must be the path of the
129  *        calling program.
130  * \param p_e an initialized exception pointer
131  * \return the libvlc instance
132  */
133 VLC_PUBLIC_API libvlc_instance_t *
134 libvlc_new( int , const char *const *, libvlc_exception_t *);
135
136 /**
137  * Return a libvlc instance identifier for legacy APIs. Use of this
138  * function is discouraged, you should convert your program to use the
139  * new API.
140  *
141  * \param p_instance the instance
142  * \return the instance identifier
143  */
144 VLC_PUBLIC_API int libvlc_get_vlc_id( libvlc_instance_t *p_instance );
145
146 /**
147  * Decrement the reference count of a libvlc instance, and destroy it
148  * if it reaches zero.
149  *
150  * \param p_instance the instance to destroy
151  */
152 VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
153
154 /**
155  * Increments the reference count of a libvlc instance.
156  * The initial reference count is 1 after libvlc_new() returns.
157  *
158  * \param p_instance the instance to reference
159  */
160 VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
161
162 /**
163  * Try to start a user interface for the libvlc instance, and wait until the
164  * user exits.
165  *
166  * \param p_instance the instance
167  * \param name interface name, or NULL for default
168  * \param p_exception an initialized exception pointer
169  */
170 VLC_PUBLIC_API
171 void libvlc_add_intf( libvlc_instance_t *p_instance, const char *name,
172                       libvlc_exception_t *p_exception );
173
174 /**
175  * Waits until an interface causes the instance to exit.
176  * You should start at least one interface first, using libvlc_add_intf().
177  *
178  * \param p_instance the instance
179  */
180 VLC_PUBLIC_API
181 void libvlc_wait( libvlc_instance_t *p_instance );
182
183 /**
184  * Retrieve libvlc version.
185  *
186  * Example: "0.9.0-git Grishenko"
187  *
188  * \return a string containing the libvlc version
189  */
190 VLC_PUBLIC_API const char * libvlc_get_version(void);
191
192 /**
193  * Retrieve libvlc compiler version.
194  *
195  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
196  *
197  * \return a string containing the libvlc compiler version
198  */
199 VLC_PUBLIC_API const char * libvlc_get_compiler(void);
200
201 /**
202  * Retrieve libvlc changeset.
203  *
204  * Example: "aa9bce0bc4"
205  *
206  * \return a string containing the libvlc changeset
207  */
208 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
209
210 /** @}*/
211
212 /*****************************************************************************
213  * media
214  *****************************************************************************/
215 /** \defgroup libvlc_media libvlc_media
216  * \ingroup libvlc
217  * LibVLC Media
218  * @{
219  */
220
221 /**
222  * Create a media with the given MRL.
223  *
224  * \param p_instance the instance
225  * \param psz_mrl the MRL to read
226  * \param p_e an initialized exception pointer
227  * \return the newly created media
228  */
229 VLC_PUBLIC_API libvlc_media_t * libvlc_media_new(
230                                    libvlc_instance_t *p_instance,
231                                    const char * psz_mrl,
232                                    libvlc_exception_t *p_e );
233
234 /**
235  * Create a media as an empty node with the passed name.
236  *
237  * \param p_instance the instance
238  * \param psz_name the name of the node
239  * \param p_e an initialized exception pointer
240  * \return the new empty media
241  */
242 VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node(
243                                    libvlc_instance_t *p_instance,
244                                    const char * psz_name,
245                                    libvlc_exception_t *p_e );
246
247 /**
248  * Add an option to the media.
249  *
250  * This option will be used to determine how the media_player will
251  * read the media. This allows to use VLC's advanced
252  * reading/streaming options on a per-media basis.
253  *
254  * The options are detailed in vlc --long-help, for instance "--sout-all"
255  *
256  * \param p_instance the instance
257  * \param ppsz_options the options (as a string)
258  * \param p_e an initialized exception pointer
259  */
260 VLC_PUBLIC_API void libvlc_media_add_option(
261                                    libvlc_media_t * p_md,
262                                    const char * ppsz_options,
263                                    libvlc_exception_t * p_e );
264
265 VLC_PUBLIC_API void libvlc_media_retain(
266                                    libvlc_media_t *p_meta_desc );
267
268 VLC_PUBLIC_API void libvlc_media_release(
269                                    libvlc_media_t *p_meta_desc );
270
271 VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md,
272                                                        libvlc_exception_t * p_e );
273
274 VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t * );
275
276 /**
277  * Read the meta of the media.
278  *
279  * \param p_meta_desc the media to read
280  * \param e_meta_desc the meta to read
281  * \param p_e an initialized exception pointer
282  * \return the media's meta
283  */
284 VLC_PUBLIC_API char * libvlc_media_get_meta(
285                                    libvlc_media_t *p_meta_desc,
286                                    libvlc_meta_t e_meta,
287                                    libvlc_exception_t *p_e );
288
289 VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state(
290                                    libvlc_media_t *p_meta_desc,
291                                    libvlc_exception_t *p_e );
292
293 VLC_PUBLIC_API libvlc_media_list_t *
294     libvlc_media_subitems( libvlc_media_t *p_md,
295                                       libvlc_exception_t *p_e );
296
297 VLC_PUBLIC_API libvlc_event_manager_t *
298     libvlc_media_event_manager( libvlc_media_t * p_md,
299                                            libvlc_exception_t * p_e );
300
301 VLC_PUBLIC_API libvlc_time_t
302    libvlc_media_get_duration( libvlc_media_t * p_md,
303                                          libvlc_exception_t * p_e );
304
305 VLC_PUBLIC_API int
306    libvlc_media_is_preparsed( libvlc_media_t * p_md,
307                                          libvlc_exception_t * p_e );
308
309 VLC_PUBLIC_API void
310     libvlc_media_set_user_data( libvlc_media_t * p_md,
311                                            void * p_new_user_data,
312                                            libvlc_exception_t * p_e);
313 VLC_PUBLIC_API void *
314     libvlc_media_get_user_data( libvlc_media_t * p_md,
315                                            libvlc_exception_t * p_e);
316
317 /** @}*/
318
319 /*****************************************************************************
320  * Media Player
321  *****************************************************************************/
322 /** \defgroup libvlc_media_player libvlc_media_player
323  * \ingroup libvlc
324  * LibVLC Media Player, object that let you play a media
325  * in a libvlc_drawable_t
326  * @{
327  */
328
329 /**
330  * Create an empty Media Player object
331  *
332  * \param p_libvlc_instance the libvlc instance in which the Media Player
333  *        should be created.
334  * \param p_e an initialized exception pointer
335  */
336 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *, libvlc_exception_t * );
337
338 /**
339  * Create a Media Player object from a Media
340  *
341  * \param p_md the media. Afterwards the p_md can be safely
342  *        destroyed.
343  * \param p_e an initialized exception pointer
344  */
345 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *, libvlc_exception_t * );
346
347 /**
348  * Release a media_player after use
349  *
350  * \param p_mi the Media Player to free
351  */
352 VLC_PUBLIC_API void libvlc_media_player_release( libvlc_media_player_t * );
353 VLC_PUBLIC_API void libvlc_media_player_retain( libvlc_media_player_t * );
354
355 /** Set the media that will be used by the media_player. If any,
356  * previous md will be released.
357  *
358  * \param p_mi the Media Player
359  * \param p_md the Media. Afterwards the p_md can be safely
360  *        destroyed.
361  * \param p_e an initialized exception pointer
362  */
363 VLC_PUBLIC_API void libvlc_media_player_set_media( libvlc_media_player_t *, libvlc_media_t *, libvlc_exception_t * );
364
365 /**
366  * Get the media used by the media_player.
367  *
368  * \param p_mi the Media Player
369  * \param p_e an initialized exception pointer
370  * \return the media associated with p_mi, or NULL if no
371  *         media is associated
372  */
373 VLC_PUBLIC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *, libvlc_exception_t * );
374
375 /**
376  * Get the Event Manager from which the media player send event.
377  *
378  * \param p_mi the Media Player
379  * \param p_e an initialized exception pointer
380  * \return the event manager associated with p_mi
381  */
382 VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *, libvlc_exception_t * );
383
384 /**
385  * Play
386  *
387  * \param p_mi the Media Player
388  * \param p_e an initialized exception pointer
389  */
390 VLC_PUBLIC_API void libvlc_media_player_play ( libvlc_media_player_t *, libvlc_exception_t * );
391
392 /**
393  * Pause
394  *
395  * \param p_mi the Media Player
396  * \param p_e an initialized exception pointer
397  */
398 VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t *, libvlc_exception_t * );
399
400 /**
401  * Stop
402  *
403  * \param p_mi the Media Player
404  * \param p_e an initialized exception pointer
405  */
406 VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *, libvlc_exception_t * );
407
408 /**
409  * Set the drawable where the media player should render its video output
410  *
411  * \param p_mi the Media Player
412  * \param drawable the libvlc_drawable_t where the media player
413  *        should render its video
414  * \param p_e an initialized exception pointer
415  */
416 VLC_PUBLIC_API void libvlc_media_player_set_drawable ( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
417
418 /**
419  * Get the drawable where the media player should render its video output
420  *
421  * \param p_mi the Media Player
422  * \param p_e an initialized exception pointer
423  * \return the libvlc_drawable_t where the media player
424  *         should render its video
425  */
426 VLC_PUBLIC_API libvlc_drawable_t
427                     libvlc_media_player_get_drawable ( libvlc_media_player_t *, libvlc_exception_t * );
428
429 /** \bug This might go away ... to be replaced by a broader system */
430 VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_length     ( libvlc_media_player_t *, libvlc_exception_t *);
431 VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_time       ( libvlc_media_player_t *, libvlc_exception_t *);
432 VLC_PUBLIC_API void           libvlc_media_player_set_time       ( libvlc_media_player_t *, libvlc_time_t, libvlc_exception_t *);
433 VLC_PUBLIC_API float          libvlc_media_player_get_position   ( libvlc_media_player_t *, libvlc_exception_t *);
434 VLC_PUBLIC_API void           libvlc_media_player_set_position   ( libvlc_media_player_t *, float, libvlc_exception_t *);
435 VLC_PUBLIC_API void           libvlc_media_player_set_chapter    ( libvlc_media_player_t *, int, libvlc_exception_t *);
436 VLC_PUBLIC_API int            libvlc_media_player_get_chapter    (libvlc_media_player_t *, libvlc_exception_t *);
437 VLC_PUBLIC_API int            libvlc_media_player_get_chapter_count( libvlc_media_player_t *, libvlc_exception_t *);
438 VLC_PUBLIC_API int            libvlc_media_player_will_play      ( libvlc_media_player_t *, libvlc_exception_t *);
439 VLC_PUBLIC_API float          libvlc_media_player_get_rate       ( libvlc_media_player_t *, libvlc_exception_t *);
440 VLC_PUBLIC_API void           libvlc_media_player_set_rate       ( libvlc_media_player_t *, float, libvlc_exception_t *);
441 VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state   ( libvlc_media_player_t *, libvlc_exception_t *);
442 VLC_PUBLIC_API float          libvlc_media_player_get_fps( libvlc_media_player_t *, libvlc_exception_t *);
443
444 /**
445  * Does this media player have a video output?
446  *
447  * \param p_md the media player
448  * \param p_e an initialized exception pointer
449  */
450 VLC_PUBLIC_API int  libvlc_media_player_has_vout( libvlc_media_player_t *, libvlc_exception_t *);
451
452 /**
453  * Is this media player seekable?
454  *
455  * \param p_input the input
456  * \param p_e an initialized exception pointer
457  */
458 VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e );
459
460 /**
461  * Can this media player be paused?
462  *
463  * \param p_input the input
464  * \param p_e an initialized exception pointer
465  */
466 VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e );
467
468 /** \defgroup libvlc_video libvlc_video
469  * \ingroup libvlc_media_player
470  * LibVLC Video handling
471  * @{
472  */
473
474 /**
475  * Toggle fullscreen status on video output.
476  *
477  * \param p_mediaplayer the media player
478  * \param p_e an initialized exception pointer
479  */
480 VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *, libvlc_exception_t * );
481
482 /**
483  * Enable or disable fullscreen on a video output.
484  *
485  * \param p_mediaplayer the media player
486  * \param b_fullscreen boolean for fullscreen status
487  * \param p_e an initialized exception pointer
488  */
489 VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int, libvlc_exception_t * );
490
491 /**
492  * Get current fullscreen status.
493  *
494  * \param p_mediaplayer the media player
495  * \param p_e an initialized exception pointer
496  * \return the fullscreen status (boolean)
497  */
498 VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t *, libvlc_exception_t * );
499
500 /**
501  * Get current video height.
502  *
503  * \param p_mediaplayer the media player
504  * \param p_e an initialized exception pointer
505  * \return the video height
506  */
507 VLC_PUBLIC_API int libvlc_video_get_height( libvlc_media_player_t *, libvlc_exception_t * );
508
509 /**
510  * Get current video width.
511  *
512  * \param p_mediaplayer the media player
513  * \param p_e an initialized exception pointer
514  * \return the video width
515  */
516 VLC_PUBLIC_API int libvlc_video_get_width( libvlc_media_player_t *, libvlc_exception_t * );
517
518 /**
519  * Get current video aspect ratio.
520  *
521  * \param p_mediaplayer the media player
522  * \param p_e an initialized exception pointer
523  * \return the video aspect ratio
524  */
525 VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *, libvlc_exception_t * );
526
527 /**
528  * Set new video aspect ratio.
529  *
530  * \param p_mediaplayer the media player
531  * \param psz_aspect new video aspect-ratio
532  * \param p_e an initialized exception pointer
533  */
534 VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, char *, libvlc_exception_t * );
535
536 /**
537  * Get current video subtitle.
538  *
539  * \param p_mediaplayer the media player
540  * \param p_e an initialized exception pointer
541  * \return the video subtitle selected
542  */
543 VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t *, libvlc_exception_t * );
544
545 /**
546  * Set new video subtitle.
547  *
548  * \param p_mediaplayer the media player
549  * \param i_spu new video subtitle to select
550  * \param p_e an initialized exception pointer
551  */
552 VLC_PUBLIC_API void libvlc_video_set_spu( libvlc_media_player_t *, int , libvlc_exception_t * );
553
554 /**
555  * Set new video subtitle file.
556  *
557  * \param p_mediaplayer the media player
558  * \param psz_subtitle new video subtitle file
559  * \param p_e an initialized exception pointer
560  * \return the success status (boolean)
561  */
562 VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, char *, libvlc_exception_t * );
563
564 /**
565  * Get current crop filter geometry.
566  *
567  * \param p_mediaplayer the media player
568  * \param p_e an initialized exception pointer
569  * \return the crop filter geometry
570  */
571 VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *, libvlc_exception_t * );
572
573 /**
574  * Set new crop filter geometry.
575  *
576  * \param p_mediaplayer the media player
577  * \param psz_geometry new crop filter geometry
578  * \param p_e an initialized exception pointer
579  */
580 VLC_PUBLIC_API void libvlc_video_set_crop_geometry( libvlc_media_player_t *, char *, libvlc_exception_t * );
581
582 /**
583  * Toggle teletext transparent status on video output.
584  *
585  * \param p_mediaplayer the media player
586  * \param p_e an initialized exception pointer
587  */
588 VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t *, libvlc_exception_t * );
589
590 /**
591  * Get current teletext page requested.
592  *
593  * \param p_mediaplayer the media player
594  * \param p_e an initialized exception pointer
595  * \return the current teletext page requested.
596  */
597 VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_player_t *, libvlc_exception_t * );
598
599 /**
600  * Set new teletext page to retrieve.
601  *
602  * \param p_mediaplayer the media player
603  * \param i_page teletex page number requested
604  * \param p_e an initialized exception pointer
605  */
606 VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_player_t *, int, libvlc_exception_t * );
607
608 /**
609  * Take a snapshot of the current video window.
610  *
611  * If i_width AND i_height is 0, original size is used.
612  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
613  *
614  * \param p_mediaplayer the media player
615  * \param psz_filepath the path where to save the screenshot to
616  * \param i_width the snapshot's width
617  * \param i_height the snapshot's height
618  * \param p_e an initialized exception pointer
619  */
620 VLC_PUBLIC_API void libvlc_video_take_snapshot( libvlc_media_player_t *, char *,unsigned int, unsigned int, libvlc_exception_t * );
621
622 /**
623  * Resize the current video output window.
624  *
625  * \param p_instance libvlc instance
626  * \param width new width for video output window
627  * \param height new height for video output window
628  * \param p_e an initialized exception pointer
629  * \return the success status (boolean)
630  */
631 VLC_PUBLIC_API void libvlc_video_resize( libvlc_media_player_t *, int, int, libvlc_exception_t *);
632
633 /**
634  * Change the parent for the current the video output.
635  *
636  * \param p_instance libvlc instance
637  * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
638  * \param p_e an initialized exception pointer
639  * \return the success status (boolean)
640  */
641 VLC_PUBLIC_API int libvlc_video_reparent( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
642
643 /**
644  * Tell windowless video output to redraw rectangular area (MacOS X only).
645  *
646  * \param p_instance libvlc instance
647  * \param area coordinates within video drawable
648  * \param p_e an initialized exception pointer
649  */
650 VLC_PUBLIC_API void libvlc_video_redraw_rectangle( libvlc_media_player_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
651
652 /**
653  * Set the default video output size.
654  *
655  * This setting will be used as default for all video outputs.
656  *
657  * \param p_instance libvlc instance
658  * \param width new width for video drawable
659  * \param height new height for video drawable
660  * \param p_e an initialized exception pointer
661  */
662 VLC_PUBLIC_API void libvlc_video_set_size( libvlc_instance_t *, int, int, libvlc_exception_t * );
663
664 /**
665  * Set the default video output viewport for a windowless video output
666  * (MacOS X only).
667  *
668  * This setting will be used as default for all video outputs.
669  *
670  * \param p_instance libvlc instance
671  * \param view coordinates within video drawable
672  * \param clip coordinates within video drawable
673  * \param p_e an initialized exception pointer
674  */
675 VLC_PUBLIC_API void libvlc_video_set_viewport( libvlc_instance_t *, const libvlc_rectangle_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
676
677 /** @} video */
678
679 /** \defgroup libvlc_audio libvlc_audio
680  * \ingroup libvlc_media_player
681  * LibVLC Audio handling
682  * @{
683  */
684
685 /**
686  * Toggle mute status.
687  *
688  * \param p_instance libvlc instance
689  * \param p_e an initialized exception pointer
690  */
691 VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_instance_t *, libvlc_exception_t * );
692
693 /**
694  * Get current mute status.
695  *
696  * \param p_instance libvlc instance
697  * \param p_e an initialized exception pointer
698  * \return the mute status (boolean)
699  */
700 VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_instance_t *, libvlc_exception_t * );
701
702 /**
703  * Set mute status.
704  *
705  * \param p_instance libvlc instance
706  * \param status If status is true then mute, otherwise unmute
707  * \param p_e an initialized exception pointer
708  */
709 VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_instance_t *, int , libvlc_exception_t * );
710
711 /**
712  * Get current audio level.
713  *
714  * \param p_instance libvlc instance
715  * \param p_e an initialized exception pointer
716  * \return the audio level (int)
717  */
718 VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_instance_t *, libvlc_exception_t * );
719
720 /**
721  * Set current audio level.
722  *
723  * \param p_instance libvlc instance
724  * \param i_volume the volume (int)
725  * \param p_e an initialized exception pointer
726  */
727 VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *);
728
729 /**
730  * Get number of available audio tracks.
731  *
732  * \param p_mi media player
733  * \param p_e an initialized exception
734  * \return the number of available audio tracks (int)
735  */
736 VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t *,  libvlc_exception_t * );
737
738 /**
739  * Get current audio track.
740  *
741  * \param p_mi media player
742  * \param p_e an initialized exception pointer
743  * \return the audio track (int)
744  */
745 VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t *, libvlc_exception_t * );
746
747 /**
748  * Set current audio track.
749  *
750  * \param p_mi media player
751  * \param i_track the track (int)
752  * \param p_e an initialized exception pointer
753  */
754 VLC_PUBLIC_API void libvlc_audio_set_track( libvlc_media_player_t *, int, libvlc_exception_t * );
755
756 /**
757  * Get current audio channel.
758  *
759  * \param p_instance vlc instance
760  * \param p_e an initialized exception pointer
761  * \return the audio channel (int)
762  */
763 VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * );
764
765 /**
766  * Set current audio channel.
767  *
768  * \param p_instance vlc instance
769  * \param i_channel the audio channel (int)
770  * \param p_e an initialized exception pointer
771  */
772 VLC_PUBLIC_API void libvlc_audio_set_channel( libvlc_instance_t *, int, libvlc_exception_t * );
773
774 /** @} audio */
775
776 /** @} media_player */
777
778 /*****************************************************************************
779  * Event handling
780  *****************************************************************************/
781
782 /** \defgroup libvlc_event libvlc_event
783  * \ingroup libvlc_core
784  * LibVLC Events
785  * @{
786  */
787
788 /**
789  * Register for an event notification.
790  *
791  * \param p_event_manager the event manager to which you want to attach to.
792  *        Generally it is obtained by vlc_my_object_event_manager() where
793  *        my_object is the object you want to listen to.
794  * \param i_event_type the desired event to which we want to listen
795  * \param f_callback the function to call when i_event_type occurs
796  * \param user_data user provided data to carry with the event
797  * \param p_e an initialized exception pointer
798  */
799 VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
800                                          libvlc_event_type_t i_event_type,
801                                          libvlc_callback_t f_callback,
802                                          void *user_data,
803                                          libvlc_exception_t *p_e );
804
805 /**
806  * Unregister an event notification.
807  *
808  * \param p_event_manager the event manager
809  * \param i_event_type the desired event to which we want to unregister
810  * \param f_callback the function to call when i_event_type occurs
811  * \param p_user_data user provided data to carry with the event
812  * \param p_e an initialized exception pointer
813  */
814 VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
815                                          libvlc_event_type_t i_event_type,
816                                          libvlc_callback_t f_callback,
817                                          void *p_user_data,
818                                          libvlc_exception_t *p_e );
819
820 /**
821  * Get an event's type name.
822  *
823  * \param i_event_type the desired event
824  */
825 VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
826
827 /** @} */
828
829 /*****************************************************************************
830  * Media Library
831  *****************************************************************************/
832 /** \defgroup libvlc_media_library libvlc_media_library
833  * \ingroup libvlc
834  * LibVLC Media Library
835  * @{
836  */
837 VLC_PUBLIC_API libvlc_media_library_t *
838     libvlc_media_library_new( libvlc_instance_t * p_inst,
839                               libvlc_exception_t * p_e );
840 VLC_PUBLIC_API void
841     libvlc_media_library_release( libvlc_media_library_t * p_mlib );
842 VLC_PUBLIC_API void
843     libvlc_media_library_retain( libvlc_media_library_t * p_mlib );
844
845
846 VLC_PUBLIC_API void
847     libvlc_media_library_load( libvlc_media_library_t * p_mlib,
848                                libvlc_exception_t * p_e );
849
850 VLC_PUBLIC_API void
851     libvlc_media_library_save( libvlc_media_library_t * p_mlib,
852                                libvlc_exception_t * p_e );
853
854 VLC_PUBLIC_API libvlc_media_list_t *
855     libvlc_media_library_media_list( libvlc_media_library_t * p_mlib,
856                                      libvlc_exception_t * p_e );
857
858
859 /** @} */
860
861
862 /*****************************************************************************
863  * Services/Media Discovery
864  *****************************************************************************/
865 /** \defgroup libvlc_media_discoverer libvlc_media_discoverer
866  * \ingroup libvlc
867  * LibVLC Media Discoverer
868  * @{
869  */
870
871 VLC_PUBLIC_API libvlc_media_discoverer_t *
872 libvlc_media_discoverer_new_from_name( libvlc_instance_t * p_inst,
873                                        const char * psz_name,
874                                        libvlc_exception_t * p_e );
875 VLC_PUBLIC_API void   libvlc_media_discoverer_release( libvlc_media_discoverer_t * p_mdis );
876 VLC_PUBLIC_API char * libvlc_media_discoverer_localized_name( libvlc_media_discoverer_t * p_mdis );
877
878 VLC_PUBLIC_API libvlc_media_list_t * libvlc_media_discoverer_media_list( libvlc_media_discoverer_t * p_mdis );
879
880 VLC_PUBLIC_API libvlc_event_manager_t *
881         libvlc_media_discoverer_event_manager( libvlc_media_discoverer_t * p_mdis );
882
883 VLC_PUBLIC_API int
884         libvlc_media_discoverer_is_running( libvlc_media_discoverer_t * p_mdis );
885
886 /**@} */
887
888
889 /*****************************************************************************
890  * Message log handling
891  *****************************************************************************/
892
893 /** \defgroup libvlc_log libvlc_log
894  * \ingroup libvlc_core
895  * LibVLC Message Logging
896  * @{
897  */
898
899 /**
900  * Return the VLC messaging verbosity level.
901  *
902  * \param p_instance libvlc instance
903  * \param p_e an initialized exception pointer
904  */
905 VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance,
906                                                   libvlc_exception_t *p_e );
907
908 /**
909  * Set the VLC messaging verbosity level.
910  *
911  * \param p_instance libvlc log instance
912  * \param level log level
913  * \param p_e an initialized exception pointer
914  */
915 VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level,
916                                               libvlc_exception_t *p_e );
917
918 /**
919  * Open a VLC message log instance.
920  *
921  * \param p_instance libvlc instance
922  * \param p_e an initialized exception pointer
923  */
924 VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *);
925
926 /**
927  * Close a VLC message log instance.
928  *
929  * \param p_log libvlc log instance
930  * \param p_e an initialized exception pointer
931  */
932 VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *, libvlc_exception_t *);
933
934 /**
935  * Returns the number of messages in a log instance.
936  *
937  * \param p_log libvlc log instance
938  * \param p_e an initialized exception pointer
939  */
940 VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *, libvlc_exception_t *);
941
942 /**
943  * Clear a log instance.
944  *
945  * All messages in the log are removed. The log should be cleared on a
946  * regular basis to avoid clogging.
947  *
948  * \param p_log libvlc log instance
949  * \param p_e an initialized exception pointer
950  */
951 VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *, libvlc_exception_t *);
952
953 /**
954  * Allocate and returns a new iterator to messages in log.
955  *
956  * \param p_log libvlc log instance
957  * \param p_e an initialized exception pointer
958  */
959 VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
960
961 /**
962  * Release a previoulsy allocated iterator.
963  *
964  * \param p_iter libvlc log iterator
965  * \param p_e an initialized exception pointer
966  */
967 VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e );
968
969 /**
970  * Return whether log iterator has more messages.
971  *
972  * \param p_iter libvlc log iterator
973  * \param p_e an initialized exception pointer
974  */
975 VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e );
976
977 /**
978  * Return the next log message.
979  *
980  * The message contents must not be freed
981  *
982  * \param p_iter libvlc log iterator
983  * \param p_buffer log buffer
984  * \param p_e an initialized exception pointer
985  */
986 VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
987                                                                libvlc_log_message_t *p_buffer,
988                                                                libvlc_exception_t *p_e );
989
990 /** @} */
991
992 # ifdef __cplusplus
993 }
994 # endif
995
996 #endif /* <vlc/libvlc.h> */