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