1 /*****************************************************************************
2 * libvlc.h: libvlc external API
3 *****************************************************************************
4 * Copyright (C) 1998-2005 the VideoLAN team
7 * Authors: Clément Stenac <zorglub@videolan.org>
8 * Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
9 * Pierre d'Herbemont <pdherbemont@videolan.org>
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.
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.
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 *****************************************************************************/
27 * \defgroup libvlc Libvlc
28 * This is libvlc, the base library of the VLC program.
43 /*****************************************************************************
45 *****************************************************************************/
46 /** \defgroup libvlc_exception Exceptions
48 * LibVLC Exceptions handling
53 * Initialize an exception structure. This can be called several times to
54 * reuse an exception structure.
56 * \param p_exception the exception to initialize
58 VLC_PUBLIC_API
void libvlc_exception_init( libvlc_exception_t
*p_exception
);
61 * Has an exception been raised?
63 * \param p_exception the exception to query
64 * \return 0 if the exception was raised, 1 otherwise
67 libvlc_exception_raised( const libvlc_exception_t
*p_exception
);
70 * Raise an exception using a user-provided message.
72 * \param p_exception the exception to raise
73 * \param psz_message the exception message format string
74 * \param ... the format string arguments
77 libvlc_exception_raise( libvlc_exception_t
*p_exception
,
78 const char *psz_format
, ... );
81 * Clear an exception object so it can be reused.
82 * The exception object must have be initialized.
84 * \param p_exception the exception to clear
86 VLC_PUBLIC_API
void libvlc_exception_clear( libvlc_exception_t
* );
89 * Get an exception's message.
91 * \param p_exception the exception to query
92 * \return the exception message or NULL if not applicable (exception not
93 * raised, for example)
95 VLC_PUBLIC_API
const char *
96 libvlc_exception_get_message( const libvlc_exception_t
*p_exception
);
100 /*****************************************************************************
102 *****************************************************************************/
104 /** \defgroup libvlc_core Core
111 * Create and initialize a libvlc instance.
113 * \param argc the number of arguments
114 * \param argv command-line-type arguments. argv[0] must be the path of the
116 * \param p_e an initialized exception pointer
117 * \return the libvlc instance
119 VLC_PUBLIC_API libvlc_instance_t
*
120 libvlc_new( int , const char *const *, libvlc_exception_t
*);
123 * Return a libvlc instance identifier for legacy APIs. Use of this
124 * function is discouraged, you should convert your program to use the
127 * \param p_instance the instance
128 * \return the instance identifier
130 VLC_PUBLIC_API
int libvlc_get_vlc_id( libvlc_instance_t
*p_instance
);
133 * Decrement the reference count of a libvlc instance, and destroy it
134 * if it reaches zero.
136 * \param p_instance the instance to destroy
138 VLC_PUBLIC_API
void libvlc_release( libvlc_instance_t
* );
141 * Increments the reference count of a libvlc instance.
142 * The initial reference count is 1 after libvlc_new() returns.
144 * \param p_instance the instance to reference
146 VLC_PUBLIC_API
void libvlc_retain( libvlc_instance_t
* );
150 /*****************************************************************************
152 *****************************************************************************/
153 /** \defgroup libvlc_media_descriptor Media Descriptor
155 * LibVLC Media Descriptor
160 * Create a media descriptor with the given MRL.
162 * \param p_instance the instance
163 * \param psz_mrl the MRL to read
164 * \param p_e an initialized exception pointer
165 * \return the newly created media descriptor
167 VLC_PUBLIC_API libvlc_media_descriptor_t
* libvlc_media_descriptor_new(
168 libvlc_instance_t
*p_instance
,
169 const char * psz_mrl
,
170 libvlc_exception_t
*p_e
);
173 * Create a media descriptor as an empty node with the passed name.
175 * \param p_instance the instance
176 * \param psz_name the name of the node
177 * \param p_e an initialized exception pointer
178 * \return the new empty media descriptor
180 VLC_PUBLIC_API libvlc_media_descriptor_t
* libvlc_media_descriptor_new_as_node(
181 libvlc_instance_t
*p_instance
,
182 const char * psz_name
,
183 libvlc_exception_t
*p_e
);
186 * Add an option to the media descriptor.
188 * This option will be used to determine how the media_instance will
189 * read the media_descriptor. This allows to use VLC's advanced
190 * reading/streaming options on a per-media basis.
192 * The options are detailed in vlc --long-help, for instance "--sout-all"
194 * \param p_instance the instance
195 * \param psz_mrl the MRL to read
196 * \param p_e an initialized exception pointer
198 VLC_PUBLIC_API
void libvlc_media_descriptor_add_option(
199 libvlc_media_descriptor_t
* p_md
,
200 const char * ppsz_options
,
201 libvlc_exception_t
* p_e
);
203 VLC_PUBLIC_API
void libvlc_media_descriptor_retain(
204 libvlc_media_descriptor_t
*p_meta_desc
);
206 VLC_PUBLIC_API
void libvlc_media_descriptor_release(
207 libvlc_media_descriptor_t
*p_meta_desc
);
209 VLC_PUBLIC_API
char * libvlc_media_descriptor_get_mrl( libvlc_media_descriptor_t
* p_md
,
210 libvlc_exception_t
* p_e
);
212 VLC_PUBLIC_API libvlc_media_descriptor_t
* libvlc_media_descriptor_duplicate( libvlc_media_descriptor_t
* );
215 * Read the meta of the media descriptor.
217 * \param p_meta_desc the media descriptor to read
218 * \param p_meta_desc the meta to read
219 * \param p_e an initialized exception pointer
220 * \return the media descriptor's meta
222 VLC_PUBLIC_API
char * libvlc_media_descriptor_get_meta(
223 libvlc_media_descriptor_t
*p_meta_desc
,
224 libvlc_meta_t e_meta
,
225 libvlc_exception_t
*p_e
);
227 VLC_PUBLIC_API libvlc_state_t
libvlc_media_descriptor_get_state(
228 libvlc_media_descriptor_t
*p_meta_desc
,
229 libvlc_exception_t
*p_e
);
231 VLC_PUBLIC_API libvlc_media_list_t
*
232 libvlc_media_descriptor_subitems( libvlc_media_descriptor_t
*p_md
,
233 libvlc_exception_t
*p_e
);
235 VLC_PUBLIC_API libvlc_event_manager_t
*
236 libvlc_media_descriptor_event_manager( libvlc_media_descriptor_t
* p_md
,
237 libvlc_exception_t
* p_e
);
239 VLC_PUBLIC_API libvlc_time_t
240 libvlc_media_descriptor_get_duration( libvlc_media_descriptor_t
* p_md
,
241 libvlc_exception_t
* p_e
);
244 libvlc_media_descriptor_is_preparsed( libvlc_media_descriptor_t
* p_md
,
245 libvlc_exception_t
* p_e
);
248 libvlc_media_descriptor_set_user_data( libvlc_media_descriptor_t
* p_md
,
249 void * p_new_user_data
,
250 libvlc_exception_t
* p_e
);
251 VLC_PUBLIC_API
void *
252 libvlc_media_descriptor_get_user_data( libvlc_media_descriptor_t
* p_md
,
253 libvlc_exception_t
* p_e
);
257 /*****************************************************************************
259 *****************************************************************************/
260 /** \defgroup libvlc_media_instance Media Instance
262 * LibVLC Media Instance, object that let you play a media descriptor
263 * in a libvlc_drawable_t
268 * Create an empty Media Instance object
270 * \param p_libvlc_instance the libvlc instance in which the Media Instance
272 * \param p_e an initialized exception pointer
274 VLC_PUBLIC_API libvlc_media_instance_t
* libvlc_media_instance_new( libvlc_instance_t
*, libvlc_exception_t
* );
277 * Create a Media Instance object from a Media Descriptor
279 * \param p_md the media descriptor. Afterwards the p_md can be safely
281 * \param p_e an initialized exception pointer
283 VLC_PUBLIC_API libvlc_media_instance_t
* libvlc_media_instance_new_from_media_descriptor( libvlc_media_descriptor_t
*, libvlc_exception_t
* );
286 * Release a media_instance after use
288 * \param p_mi the Media Instance to free
290 VLC_PUBLIC_API
void libvlc_media_instance_release( libvlc_media_instance_t
* );
291 VLC_PUBLIC_API
void libvlc_media_instance_retain( libvlc_media_instance_t
* );
293 /** Set the media descriptor that will be used by the media_instance. If any,
294 * previous md will be released.
296 * \param p_mi the Media Instance
297 * \param p_md the Media Descriptor. Afterwards the p_md can be safely
299 * \param p_e an initialized exception pointer
301 VLC_PUBLIC_API
void libvlc_media_instance_set_media_descriptor( libvlc_media_instance_t
*, libvlc_media_descriptor_t
*, libvlc_exception_t
* );
304 * Get the media descriptor used by the media_instance.
306 * \param p_mi the Media Instance
307 * \param p_e an initialized exception pointer
308 * \return the media descriptor associated with p_mi, or NULL if no
309 * media descriptor is associated
311 VLC_PUBLIC_API libvlc_media_descriptor_t
* libvlc_media_instance_get_media_descriptor( libvlc_media_instance_t
*, libvlc_exception_t
* );
314 * Get the Event Manager from which the media instance send event.
316 * \param p_mi the Media Instance
317 * \param p_e an initialized exception pointer
318 * \return the event manager associated with p_mi
320 VLC_PUBLIC_API libvlc_event_manager_t
* libvlc_media_instance_event_manager ( libvlc_media_instance_t
*, libvlc_exception_t
* );
325 * \param p_mi the Media Instance
326 * \param p_e an initialized exception pointer
328 VLC_PUBLIC_API
void libvlc_media_instance_play ( libvlc_media_instance_t
*, libvlc_exception_t
* );
333 * \param p_mi the Media Instance
334 * \param p_e an initialized exception pointer
336 VLC_PUBLIC_API
void libvlc_media_instance_pause ( libvlc_media_instance_t
*, libvlc_exception_t
* );
341 * \param p_mi the Media Instance
342 * \param p_e an initialized exception pointer
344 VLC_PUBLIC_API
void libvlc_media_instance_stop ( libvlc_media_instance_t
*, libvlc_exception_t
* );
347 * Set the drawable where the media instance should render its video output
349 * \param p_mi the Media Instance
350 * \param drawable the libvlc_drawable_t where the media instance
351 * should render its video
352 * \param p_e an initialized exception pointer
354 VLC_PUBLIC_API
void libvlc_media_instance_set_drawable ( libvlc_media_instance_t
*, libvlc_drawable_t
, libvlc_exception_t
* );
357 * Get the drawable where the media instance should render its video output
359 * \param p_mi the Media Instance
360 * \param p_e an initialized exception pointer
361 * \return the libvlc_drawable_t where the media instance
362 * should render its video
364 VLC_PUBLIC_API libvlc_drawable_t
365 libvlc_media_instance_get_drawable ( libvlc_media_instance_t
*, libvlc_exception_t
* );
367 /** \bug This might go away ... to be replaced by a broader system */
368 VLC_PUBLIC_API libvlc_time_t
libvlc_media_instance_get_length ( libvlc_media_instance_t
*, libvlc_exception_t
*);
369 VLC_PUBLIC_API libvlc_time_t
libvlc_media_instance_get_time ( libvlc_media_instance_t
*, libvlc_exception_t
*);
370 VLC_PUBLIC_API
void libvlc_media_instance_set_time ( libvlc_media_instance_t
*, libvlc_time_t
, libvlc_exception_t
*);
371 VLC_PUBLIC_API
float libvlc_media_instance_get_position ( libvlc_media_instance_t
*, libvlc_exception_t
*);
372 VLC_PUBLIC_API
void libvlc_media_instance_set_position ( libvlc_media_instance_t
*, float, libvlc_exception_t
*);
373 VLC_PUBLIC_API
void libvlc_media_instance_set_chapter ( libvlc_media_instance_t
*, int, libvlc_exception_t
*);
374 VLC_PUBLIC_API
int libvlc_media_instance_get_chapter (libvlc_media_instance_t
*, libvlc_exception_t
*);
375 VLC_PUBLIC_API
int libvlc_media_instance_get_chapter_count( libvlc_media_instance_t
*, libvlc_exception_t
*);
376 VLC_PUBLIC_API
int libvlc_media_instance_will_play ( libvlc_media_instance_t
*, libvlc_exception_t
*);
377 VLC_PUBLIC_API
float libvlc_media_instance_get_rate ( libvlc_media_instance_t
*, libvlc_exception_t
*);
378 VLC_PUBLIC_API
void libvlc_media_instance_set_rate ( libvlc_media_instance_t
*, float, libvlc_exception_t
*);
379 VLC_PUBLIC_API libvlc_state_t
libvlc_media_instance_get_state ( libvlc_media_instance_t
*, libvlc_exception_t
*);
380 VLC_PUBLIC_API
float libvlc_media_instance_get_fps( libvlc_media_instance_t
*, libvlc_exception_t
*);
383 * Does this media instance have a video output?
385 * \param p_md the media instance
386 * \param p_e an initialized exception pointer
388 VLC_PUBLIC_API
int libvlc_media_instance_has_vout( libvlc_media_instance_t
*, libvlc_exception_t
*);
391 * Is this media instance seekable?
393 * \param p_input the input
394 * \param p_e an initialized exception pointer
396 VLC_PUBLIC_API
int libvlc_media_instance_is_seekable( libvlc_media_instance_t
*p_mi
, libvlc_exception_t
*p_e
);
399 * Can this media instance be paused?
401 * \param p_input the input
402 * \param p_e an initialized exception pointer
404 VLC_PUBLIC_API
int libvlc_media_instance_can_pause( libvlc_media_instance_t
*p_mi
, libvlc_exception_t
*p_e
);
406 /** \defgroup libvlc_video Video
407 * \ingroup libvlc_media_instance
408 * LibVLC Video handling
413 * Toggle fullscreen status on video output.
415 * \param p_input the input
416 * \param p_e an initialized exception pointer
418 VLC_PUBLIC_API
void libvlc_toggle_fullscreen( libvlc_media_instance_t
*, libvlc_exception_t
* );
421 * Enable or disable fullscreen on a video output.
423 * \param p_input the input
424 * \param b_fullscreen boolean for fullscreen status
425 * \param p_e an initialized exception pointer
427 VLC_PUBLIC_API
void libvlc_set_fullscreen( libvlc_media_instance_t
*, int, libvlc_exception_t
* );
430 * Get current fullscreen status.
432 * \param p_input the input
433 * \param p_e an initialized exception pointer
434 * \return the fullscreen status (boolean)
436 VLC_PUBLIC_API
int libvlc_get_fullscreen( libvlc_media_instance_t
*, libvlc_exception_t
* );
439 * Get current video height.
441 * \param p_input the input
442 * \param p_e an initialized exception pointer
443 * \return the video height
445 VLC_PUBLIC_API
int libvlc_video_get_height( libvlc_media_instance_t
*, libvlc_exception_t
* );
448 * Get current video width.
450 * \param p_input the input
451 * \param p_e an initialized exception pointer
452 * \return the video width
454 VLC_PUBLIC_API
int libvlc_video_get_width( libvlc_media_instance_t
*, libvlc_exception_t
* );
457 * Get current video aspect ratio.
459 * \param p_input the input
460 * \param p_e an initialized exception pointer
461 * \return the video aspect ratio
463 VLC_PUBLIC_API
char *libvlc_video_get_aspect_ratio( libvlc_media_instance_t
*, libvlc_exception_t
* );
466 * Set new video aspect ratio.
468 * \param p_input the input
469 * \param psz_aspect new video aspect-ratio
470 * \param p_e an initialized exception pointer
472 VLC_PUBLIC_API
void libvlc_video_set_aspect_ratio( libvlc_media_instance_t
*, char *, libvlc_exception_t
* );
475 * Get current video subtitle.
477 * \param p_input the input
478 * \param p_e an initialized exception pointer
479 * \return the video subtitle selected
481 VLC_PUBLIC_API
int libvlc_video_get_spu( libvlc_media_instance_t
*, libvlc_exception_t
* );
484 * Set new video subtitle.
486 * \param p_input the input
487 * \param i_spu new video subtitle to select
488 * \param p_e an initialized exception pointer
490 VLC_PUBLIC_API
void libvlc_video_set_spu( libvlc_media_instance_t
*, int , libvlc_exception_t
* );
493 * Get current crop filter geometry.
495 * \param p_input the input
496 * \param p_e an initialized exception pointer
497 * \return the crop filter geometry
499 VLC_PUBLIC_API
char *libvlc_video_get_crop_geometry( libvlc_media_instance_t
*, libvlc_exception_t
* );
502 * Set new crop filter geometry.
504 * \param p_input the input
505 * \param psz_geometry new crop filter geometry
506 * \param p_e an initialized exception pointer
508 VLC_PUBLIC_API
void libvlc_video_set_crop_geometry( libvlc_media_instance_t
*, char *, libvlc_exception_t
* );
511 * Toggle teletext transparent status on video output.
513 * \param p_input the input
514 * \param p_e an initialized exception pointer
516 VLC_PUBLIC_API
void libvlc_toggle_teletext( libvlc_media_instance_t
*, libvlc_exception_t
* );
519 * Get current teletext page requested.
521 * \param p_input the input
522 * \param p_e an initialized exception pointer
523 * \return the current teletext page requested.
525 VLC_PUBLIC_API
int libvlc_video_get_teletext( libvlc_media_instance_t
*, libvlc_exception_t
* );
528 * Set new teletext page to retrieve.
530 * \param p_input the input
531 * \param i_page teletex page number requested
532 * \param p_e an initialized exception pointer
534 VLC_PUBLIC_API
void libvlc_video_set_teletext( libvlc_media_instance_t
*, int, libvlc_exception_t
* );
537 * Take a snapshot of the current video window.
539 * If i_width AND i_height is 0, original size is used.
540 * If i_width XOR i_height is 0, original aspect-ratio is preserved.
542 * \param p_input the input
543 * \param psz_filepath the path where to save the screenshot to
544 * \param i_width the snapshot's width
545 * \param i_height the snapshot's height
546 * \param p_e an initialized exception pointer
548 VLC_PUBLIC_API
void libvlc_video_take_snapshot( libvlc_media_instance_t
*, char *,unsigned int, unsigned int, libvlc_exception_t
* );
550 VLC_PUBLIC_API
int libvlc_video_destroy( libvlc_media_instance_t
*, libvlc_exception_t
*);
553 * Resize the current video output window.
555 * \param p_instance libvlc instance
556 * \param width new width for video output window
557 * \param height new height for video output window
558 * \param p_e an initialized exception pointer
559 * \return the success status (boolean)
561 VLC_PUBLIC_API
void libvlc_video_resize( libvlc_media_instance_t
*, int, int, libvlc_exception_t
*);
564 * Change the parent for the current the video output.
566 * \param p_instance libvlc instance
567 * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
568 * \param p_e an initialized exception pointer
569 * \return the success status (boolean)
571 VLC_PUBLIC_API
int libvlc_video_reparent( libvlc_media_instance_t
*, libvlc_drawable_t
, libvlc_exception_t
* );
574 * Tell windowless video output to redraw rectangular area (MacOS X only).
576 * \param p_instance libvlc instance
577 * \param area coordinates within video drawable
578 * \param p_e an initialized exception pointer
580 VLC_PUBLIC_API
void libvlc_video_redraw_rectangle( libvlc_media_instance_t
*, const libvlc_rectangle_t
*, libvlc_exception_t
* );
583 * Set the default video output's parent.
585 * This setting will be used as default for all video outputs.
587 * \param p_instance libvlc instance
588 * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
589 * \param p_e an initialized exception pointer
591 VLC_PUBLIC_API
void libvlc_video_set_parent( libvlc_instance_t
*, libvlc_drawable_t
, libvlc_exception_t
* );
594 * Set the default video output parent.
596 * This setting will be used as default for all video outputs.
598 * \param p_instance libvlc instance
599 * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
600 * \param p_e an initialized exception pointer
602 VLC_PUBLIC_API libvlc_drawable_t
libvlc_video_get_parent( libvlc_instance_t
*, libvlc_exception_t
* );
605 * Set the default video output size.
607 * This setting will be used as default for all video outputs.
609 * \param p_instance libvlc instance
610 * \param width new width for video drawable
611 * \param height new height for video drawable
612 * \param p_e an initialized exception pointer
614 VLC_PUBLIC_API
void libvlc_video_set_size( libvlc_instance_t
*, int, int, libvlc_exception_t
* );
617 * Set the default video output viewport for a windowless video output
620 * This setting will be used as default for all video outputs.
622 * \param p_instance libvlc instance
623 * \param view coordinates within video drawable
624 * \param clip coordinates within video drawable
625 * \param p_e an initialized exception pointer
627 VLC_PUBLIC_API
void libvlc_video_set_viewport( libvlc_instance_t
*, const libvlc_rectangle_t
*, const libvlc_rectangle_t
*, libvlc_exception_t
* );
631 /** \defgroup libvlc_audio Audio
632 * \ingroup libvlc_media_instance
633 * LibVLC Audio handling
638 * Toggle mute status.
640 * \param p_instance libvlc instance
641 * \param p_e an initialized exception pointer
643 VLC_PUBLIC_API
void libvlc_audio_toggle_mute( libvlc_instance_t
*, libvlc_exception_t
* );
646 * Get current mute status.
648 * \param p_instance libvlc instance
649 * \param p_e an initialized exception pointer
650 * \return the mute status (boolean)
652 VLC_PUBLIC_API
int libvlc_audio_get_mute( libvlc_instance_t
*, libvlc_exception_t
* );
657 * \param p_instance libvlc instance
658 * \param status If status is VLC_TRUE then mute, otherwise unmute
659 * \param p_e an initialized exception pointer
661 VLC_PUBLIC_API
void libvlc_audio_set_mute( libvlc_instance_t
*, int , libvlc_exception_t
* );
664 * Get current audio level.
666 * \param p_instance libvlc instance
667 * \param p_e an initialized exception pointer
668 * \return the audio level (int)
670 VLC_PUBLIC_API
int libvlc_audio_get_volume( libvlc_instance_t
*, libvlc_exception_t
* );
673 * Set current audio level.
675 * \param p_instance libvlc instance
676 * \param i_volume the volume (int)
677 * \param p_e an initialized exception pointer
679 VLC_PUBLIC_API
void libvlc_audio_set_volume( libvlc_instance_t
*, int, libvlc_exception_t
*);
682 * Get number of available audio tracks.
684 * \param p_mi media instance
685 * \param p_e an initialized exception
686 * \return the number of available audio tracks (int)
688 VLC_PUBLIC_API
int libvlc_audio_get_track_count( libvlc_media_instance_t
*, libvlc_exception_t
* );
691 * Get current audio track.
693 * \param p_input input instance
694 * \param p_e an initialized exception pointer
695 * \return the audio track (int)
697 VLC_PUBLIC_API
int libvlc_audio_get_track( libvlc_media_instance_t
*, libvlc_exception_t
* );
700 * Set current audio track.
702 * \param p_input input instance
703 * \param i_track the track (int)
704 * \param p_e an initialized exception pointer
706 VLC_PUBLIC_API
void libvlc_audio_set_track( libvlc_media_instance_t
*, int, libvlc_exception_t
* );
709 * Get current audio channel.
711 * \param p_instance input instance
712 * \param p_e an initialized exception pointer
713 * \return the audio channel (int)
715 VLC_PUBLIC_API
int libvlc_audio_get_channel( libvlc_instance_t
*, libvlc_exception_t
* );
718 * Set current audio channel.
720 * \param p_instance input instance
721 * \param i_channel the audio channel (int)
722 * \param p_e an initialized exception pointer
724 VLC_PUBLIC_API
void libvlc_audio_set_channel( libvlc_instance_t
*, int, libvlc_exception_t
* );
728 /** @} media_instance */
730 /*****************************************************************************
732 *****************************************************************************/
734 /** \defgroup libvlc_callbacks Callbacks
741 * Register for an event notification.
743 * \param p_event_manager the event manager to which you want to attach to.
744 * Generally it is obtained by vlc_my_object_event_manager() where
745 * my_object is the object you want to listen to.
746 * \param i_event_type the desired event to which we want to listen
747 * \param f_callback the function to call when i_event_type occurs
748 * \param user_data user provided data to carry with the event
749 * \param p_e an initialized exception pointer
751 VLC_PUBLIC_API
void libvlc_event_attach( libvlc_event_manager_t
*p_event_manager
,
752 libvlc_event_type_t i_event_type
,
753 libvlc_callback_t f_callback
,
755 libvlc_exception_t
*p_e
);
758 * Unregister an event notification.
760 * \param p_event_manager the event manager
761 * \param i_event_type the desired event to which we want to unregister
762 * \param f_callback the function to call when i_event_type occurs
763 * \param p_e an initialized exception pointer
765 VLC_PUBLIC_API
void libvlc_event_detach( libvlc_event_manager_t
*p_event_manager
,
766 libvlc_event_type_t i_event_type
,
767 libvlc_callback_t f_callback
,
769 libvlc_exception_t
*p_e
);
772 * Get an event's type name.
774 * \param i_event_type the desired event
776 VLC_PUBLIC_API
const char * libvlc_event_type_name( libvlc_event_type_t event_type
);
780 /*****************************************************************************
782 *****************************************************************************/
783 /** \defgroup libvlc_media_list MediaList
785 * LibVLC Media List, a media list holds multiple media descriptors
790 * Create an empty media list.
792 * \param p_libvlc the event manager
793 * \param i_event_type the desired event to which we want to unregister
794 * \param f_callback the function to call when i_event_type occurs
795 * \param p_e an initialized exception pointer
798 VLC_PUBLIC_API libvlc_media_list_t
*
799 libvlc_media_list_new( libvlc_instance_t
*, libvlc_exception_t
* );
802 libvlc_media_list_release( libvlc_media_list_t
* );
805 libvlc_media_list_retain( libvlc_media_list_t
* );
807 VLC_DEPRECATED_API
void
808 libvlc_media_list_add_file_content( libvlc_media_list_t
* p_mlist
,
809 const char * psz_uri
,
810 libvlc_exception_t
* p_e
);
813 libvlc_media_list_set_media_descriptor( libvlc_media_list_t
*,
814 libvlc_media_descriptor_t
*,
815 libvlc_exception_t
*);
817 VLC_PUBLIC_API libvlc_media_descriptor_t
*
818 libvlc_media_list_media_descriptor( libvlc_media_list_t
*,
819 libvlc_exception_t
*);
822 libvlc_media_list_add_media_descriptor( libvlc_media_list_t
*,
823 libvlc_media_descriptor_t
*,
824 libvlc_exception_t
* );
826 libvlc_media_list_insert_media_descriptor( libvlc_media_list_t
*,
827 libvlc_media_descriptor_t
*,
829 libvlc_exception_t
* );
831 libvlc_media_list_remove_index( libvlc_media_list_t
*, int,
832 libvlc_exception_t
* );
835 libvlc_media_list_count( libvlc_media_list_t
* p_mlist
,
836 libvlc_exception_t
* p_e
);
838 VLC_PUBLIC_API libvlc_media_descriptor_t
*
839 libvlc_media_list_item_at_index( libvlc_media_list_t
*, int,
840 libvlc_exception_t
* );
842 libvlc_media_list_index_of_item( libvlc_media_list_t
*,
843 libvlc_media_descriptor_t
*,
844 libvlc_exception_t
* );
846 /* This indicates if this media list is read-only from a user point of view */
848 libvlc_media_list_is_readonly( libvlc_media_list_t
* p_mlist
);
851 libvlc_media_list_lock( libvlc_media_list_t
* );
853 libvlc_media_list_unlock( libvlc_media_list_t
* );
855 VLC_PUBLIC_API libvlc_media_list_view_t
*
856 libvlc_media_list_flat_view( libvlc_media_list_t
*,
857 libvlc_exception_t
* );
859 VLC_PUBLIC_API libvlc_media_list_view_t
*
860 libvlc_media_list_hierarchical_view( libvlc_media_list_t
*,
861 libvlc_exception_t
* );
863 VLC_PUBLIC_API libvlc_media_list_view_t
*
864 libvlc_media_list_hierarchical_node_view( libvlc_media_list_t
*,
865 libvlc_exception_t
* );
867 VLC_PUBLIC_API libvlc_event_manager_t
*
868 libvlc_media_list_event_manager( libvlc_media_list_t
*,
869 libvlc_exception_t
* );
871 /*****************************************************************************
873 *****************************************************************************/
874 /** \defgroup libvlc_media_list_view MediaListView
875 * \ingroup libvlc_media_list
876 * LibVLC Media List View, represent a media_list using a different layout
880 libvlc_media_list_view_retain( libvlc_media_list_view_t
* p_mlv
);
883 libvlc_media_list_view_release( libvlc_media_list_view_t
* p_mlv
);
885 VLC_PUBLIC_API libvlc_event_manager_t
*
886 libvlc_media_list_view_event_manager( libvlc_media_list_view_t
* p_mlv
);
889 libvlc_media_list_view_count( libvlc_media_list_view_t
* p_mlv
,
890 libvlc_exception_t
* p_e
);
892 VLC_PUBLIC_API libvlc_media_descriptor_t
*
893 libvlc_media_list_view_item_at_index( libvlc_media_list_view_t
* p_mlv
,
895 libvlc_exception_t
* p_e
);
897 VLC_PUBLIC_API libvlc_media_list_view_t
*
898 libvlc_media_list_view_children_at_index( libvlc_media_list_view_t
* p_mlv
,
900 libvlc_exception_t
* p_e
);
902 VLC_PUBLIC_API libvlc_media_list_view_t
*
903 libvlc_media_list_view_children_for_item( libvlc_media_list_view_t
* p_mlv
,
904 libvlc_media_descriptor_t
* p_md
,
905 libvlc_exception_t
* p_e
);
909 libvlc_media_list_view_index_of_item( libvlc_media_list_view_t
* p_mlv
,
910 libvlc_media_descriptor_t
* p_md
,
911 libvlc_exception_t
* p_e
);
914 libvlc_media_list_view_insert_at_index( libvlc_media_list_view_t
* p_mlv
,
915 libvlc_media_descriptor_t
* p_md
,
917 libvlc_exception_t
* p_e
);
920 libvlc_media_list_view_remove_at_index( libvlc_media_list_view_t
* p_mlv
,
922 libvlc_exception_t
* p_e
);
925 libvlc_media_list_view_add_item( libvlc_media_list_view_t
* p_mlv
,
926 libvlc_media_descriptor_t
* p_md
,
927 libvlc_exception_t
* p_e
);
929 VLC_PUBLIC_API libvlc_media_list_t
*
930 libvlc_media_list_view_parent_media_list( libvlc_media_list_view_t
* p_mlv
,
931 libvlc_exception_t
* p_e
);
933 /** @} media_list_view */
935 /*****************************************************************************
937 *****************************************************************************/
938 /** \defgroup libvlc_media_list_player MediaListPlayer
940 * LibVLC Media List Player, play a media_list. You can see that as a media
944 VLC_PUBLIC_API libvlc_media_list_player_t
*
945 libvlc_media_list_player_new( libvlc_instance_t
* p_instance
,
946 libvlc_exception_t
* p_e
);
948 libvlc_media_list_player_release( libvlc_media_list_player_t
* p_mlp
);
951 libvlc_media_list_player_set_media_instance(
952 libvlc_media_list_player_t
* p_mlp
,
953 libvlc_media_instance_t
* p_mi
,
954 libvlc_exception_t
* p_e
);
957 libvlc_media_list_player_set_media_list(
958 libvlc_media_list_player_t
* p_mlp
,
959 libvlc_media_list_t
* p_mlist
,
960 libvlc_exception_t
* p_e
);
963 libvlc_media_list_player_play( libvlc_media_list_player_t
* p_mlp
,
964 libvlc_exception_t
* p_e
);
967 libvlc_media_list_player_pause( libvlc_media_list_player_t
* p_mlp
,
968 libvlc_exception_t
* p_e
);
971 libvlc_media_list_player_is_playing( libvlc_media_list_player_t
* p_mlp
,
972 libvlc_exception_t
* p_e
);
974 VLC_PUBLIC_API libvlc_state_t
975 libvlc_media_list_player_get_state( libvlc_media_list_player_t
* p_mlp
,
976 libvlc_exception_t
* p_e
);
979 libvlc_media_list_player_play_item_at_index(
980 libvlc_media_list_player_t
* p_mlp
,
982 libvlc_exception_t
* p_e
);
985 libvlc_media_list_player_play_item(
986 libvlc_media_list_player_t
* p_mlp
,
987 libvlc_media_descriptor_t
* p_md
,
988 libvlc_exception_t
* p_e
);
991 libvlc_media_list_player_stop( libvlc_media_list_player_t
* p_mlp
,
992 libvlc_exception_t
* p_e
);
995 libvlc_media_list_player_next( libvlc_media_list_player_t
* p_mlp
,
996 libvlc_exception_t
* p_e
);
998 /** @} media_list_player */
1000 /** @} media_list */
1002 /*****************************************************************************
1004 *****************************************************************************/
1005 /** \defgroup libvlc_media_library Media Library
1007 * LibVLC Media Library
1010 VLC_PUBLIC_API libvlc_media_library_t
*
1011 libvlc_media_library_new( libvlc_instance_t
* p_inst
,
1012 libvlc_exception_t
* p_e
);
1014 libvlc_media_library_release( libvlc_media_library_t
* p_mlib
);
1016 libvlc_media_library_retain( libvlc_media_library_t
* p_mlib
);
1020 libvlc_media_library_load( libvlc_media_library_t
* p_mlib
,
1021 libvlc_exception_t
* p_e
);
1024 libvlc_media_library_save( libvlc_media_library_t
* p_mlib
,
1025 libvlc_exception_t
* p_e
);
1027 VLC_PUBLIC_API libvlc_media_list_t
*
1028 libvlc_media_library_media_list( libvlc_media_library_t
* p_mlib
,
1029 libvlc_exception_t
* p_e
);
1035 /*****************************************************************************
1036 * Services/Media Discovery
1037 *****************************************************************************/
1038 /** \defgroup libvlc_media_discoverer Media Discoverer
1040 * LibVLC Media Discoverer
1044 VLC_PUBLIC_API libvlc_media_discoverer_t
*
1045 libvlc_media_discoverer_new_from_name( libvlc_instance_t
* p_inst
,
1046 const char * psz_name
,
1047 libvlc_exception_t
* p_e
);
1048 VLC_PUBLIC_API
void libvlc_media_discoverer_release( libvlc_media_discoverer_t
* p_mdis
);
1049 VLC_PUBLIC_API
char * libvlc_media_discoverer_localized_name( libvlc_media_discoverer_t
* p_mdis
);
1051 VLC_PUBLIC_API libvlc_media_list_t
* libvlc_media_discoverer_media_list( libvlc_media_discoverer_t
* p_mdis
);
1053 VLC_PUBLIC_API libvlc_event_manager_t
*
1054 libvlc_media_discoverer_event_manager( libvlc_media_discoverer_t
* p_mdis
);
1057 libvlc_media_discoverer_is_running( libvlc_media_discoverer_t
* p_mdis
);
1062 /*****************************************************************************
1063 * Message log handling
1064 *****************************************************************************/
1066 /** \defgroup libvlc_log Log
1068 * LibVLC Message Logging
1073 * Return the VLC messaging verbosity level.
1075 * \param p_instance libvlc instance
1076 * \param exception an initialized exception pointer
1078 VLC_PUBLIC_API
unsigned libvlc_get_log_verbosity( const libvlc_instance_t
*p_instance
,
1079 libvlc_exception_t
*p_e
);
1082 * Set the VLC messaging verbosity level.
1084 * \param p_log libvlc log instance
1085 * \param exception an initialized exception pointer
1087 VLC_PUBLIC_API
void libvlc_set_log_verbosity( libvlc_instance_t
*p_instance
, unsigned level
,
1088 libvlc_exception_t
*p_e
);
1091 * Open a VLC message log instance.
1093 * \param p_instance libvlc instance
1094 * \param exception an initialized exception pointer
1096 VLC_PUBLIC_API libvlc_log_t
*libvlc_log_open( libvlc_instance_t
*, libvlc_exception_t
*);
1099 * Close a VLC message log instance.
1101 * \param p_log libvlc log instance
1102 * \param exception an initialized exception pointer
1104 VLC_PUBLIC_API
void libvlc_log_close( libvlc_log_t
*, libvlc_exception_t
*);
1107 * Returns the number of messages in a log instance.
1109 * \param p_log libvlc log instance
1110 * \param exception an initialized exception pointer
1112 VLC_PUBLIC_API
unsigned libvlc_log_count( const libvlc_log_t
*, libvlc_exception_t
*);
1115 * Clear a log instance.
1117 * All messages in the log are removed. The log should be cleared on a
1118 * regular basis to avoid clogging.
1120 * \param p_log libvlc log instance
1121 * \param exception an initialized exception pointer
1123 VLC_PUBLIC_API
void libvlc_log_clear( libvlc_log_t
*, libvlc_exception_t
*);
1126 * Allocate and returns a new iterator to messages in log.
1128 * \param p_log libvlc log instance
1129 * \param exception an initialized exception pointer
1131 VLC_PUBLIC_API libvlc_log_iterator_t
*libvlc_log_get_iterator( const libvlc_log_t
*, libvlc_exception_t
*);
1134 * Release a previoulsy allocated iterator.
1136 * \param p_log libvlc log iterator
1137 * \param exception an initialized exception pointer
1139 VLC_PUBLIC_API
void libvlc_log_iterator_free( libvlc_log_iterator_t
*p_iter
, libvlc_exception_t
*p_e
);
1142 * Return whether log iterator has more messages.
1144 * \param p_log libvlc log iterator
1145 * \param exception an initialized exception pointer
1147 VLC_PUBLIC_API
int libvlc_log_iterator_has_next( const libvlc_log_iterator_t
*p_iter
, libvlc_exception_t
*p_e
);
1150 * Return the next log message.
1152 * The message contents must not be freed
1154 * \param p_log libvlc log iterator
1155 * \param exception an initialized exception pointer
1157 VLC_PUBLIC_API libvlc_log_message_t
*libvlc_log_iterator_next( libvlc_log_iterator_t
*p_iter
,
1158 struct libvlc_log_message_t
*buffer
,
1159 libvlc_exception_t
*p_e
);
1167 #endif /* <vlc/libvlc.h> */