git.sesse.net Git - vlc/blob - include/vlc/libvlc.h

   1 /*****************************************************************************
   2  * libvlc.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2009 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Clément Stenac <zorglub@videolan.org>
   8  *          Jean-Paul Saman <jpsaman@videolan.org>
   9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU Lesser General Public License as published by
  13  * the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24  *****************************************************************************/
  25
  26 /**
  27  * \file
  28  * This file defines libvlc external API
  29  */
  30
  31 /**
  32  * \defgroup libvlc LibVLC
  33  * LibVLC is the external programming interface of the VLC media player.
  34  * It is used to embed VLC into other applications or frameworks.
  35  * @{
  36  */
  37
  38 #ifndef VLC_LIBVLC_H
  39 #define VLC_LIBVLC_H 1
  40
  41 #if defined (_WIN32) && defined (DLL_EXPORT)
  42 # define LIBVLC_API __declspec(dllexport)
  43 #elif defined (__GNUC__) && (__GNUC__ >= 4)
  44 # define LIBVLC_API __attribute__((visibility("default")))
  45 #else
  46 # define LIBVLC_API
  47 #endif
  48
  49 #ifdef __LIBVLC__
  50 /* Avoid unhelpful warnings from libvlc with our deprecated APIs */
  51 #   define LIBVLC_DEPRECATED
  52 #elif defined(__GNUC__) && \
  53       (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
  54 # define LIBVLC_DEPRECATED __attribute__((deprecated))
  55 #else
  56 # define LIBVLC_DEPRECATED
  57 #endif
  58
  59 #include <stdio.h>
  60 #include <stdarg.h>
  61
  62 # ifdef __cplusplus
  63 extern "C" {
  64 # endif
  65
  66 #include <vlc/libvlc_structures.h>
  67
  68 /** \defgroup libvlc_core LibVLC core
  69  * \ingroup libvlc
  70  * Before it can do anything useful, LibVLC must be initialized.
  71  * You can create one (or more) instance(s) of LibVLC in a given process,
  72  * with libvlc_new() and destroy them with libvlc_release().
  73  *
  74  * \version Unless otherwise stated, these functions are available
  75  * from LibVLC versions numbered 1.1.0 or more.
  76  * Earlier versions (0.9.x and 1.0.x) are <b>not</b> compatible.
  77  * @{
  78  */
  79
  80 /** \defgroup libvlc_error LibVLC error handling
  81  * @{
  82  */
  83
  84 /**
  85  * A human-readable error message for the last LibVLC error in the calling
  86  * thread. The resulting string is valid until another error occurs (at least
  87  * until the next LibVLC call).
  88  *
  89  * @warning
  90  * This will be NULL if there was no error.
  91  */
  92 LIBVLC_API const char *libvlc_errmsg (void);
  93
  94 /**
  95  * Clears the LibVLC error status for the current thread. This is optional.
  96  * By default, the error status is automatically overridden when a new error
  97  * occurs, and destroyed when the thread exits.
  98  */
  99 LIBVLC_API void libvlc_clearerr (void);
 100
 101 /**
 102  * Sets the LibVLC error status and message for the current thread.
 103  * Any previous error is overridden.
 104  * \param fmt the format string
 105  * \param ap the arguments
 106  * \return a nul terminated string in any case
 107  */
 108 LIBVLC_API const char *libvlc_vprinterr (const char *fmt, va_list ap);
 109
 110 /**
 111  * Sets the LibVLC error status and message for the current thread.
 112  * Any previous error is overridden.
 113  * \param fmt the format string
 114  * \param args the arguments
 115  * \return a nul terminated string in any case
 116  */
 117 LIBVLC_API const char *libvlc_printerr (const char *fmt, ...);
 118
 119 /**@} */
 120
 121 /**
 122  * Create and initialize a libvlc instance.
 123  * This functions accept a list of "command line" arguments similar to the
 124  * main(). These arguments affect the LibVLC instance default configuration.
 125  *
 126  * \version
 127  * Arguments are meant to be passed from the command line to LibVLC, just like
 128  * VLC media player does. The list of valid arguments depends on the LibVLC
 129  * version, the operating system and platform, and set of available LibVLC
 130  * plugins. Invalid or unsupported arguments will cause the function to fail
 131  * (i.e. return NULL). Also, some arguments may alter the behaviour or
 132  * otherwise interfere with other LibVLC functions.
 133  *
 134  * \warning
 135  * There is absolutely no warranty or promise of forward, backward and
 136  * cross-platform compatibility with regards to libvlc_new() arguments.
 137  * We recommend that you do not use them, other than when debugging.
 138  *
 139  * \param argc the number of arguments (should be 0)
 140  * \param argv list of arguments (should be NULL)
 141  * \return the libvlc instance or NULL in case of error
 142  */
 143 LIBVLC_API libvlc_instance_t *
 144 libvlc_new( int argc , const char *const *argv );
 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 LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
 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 LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
 161
 162 /**
 163  * Try to start a user interface for the libvlc instance.
 164  *
 165  * \param p_instance the instance
 166  * \param name interface name, or NULL for default
 167  * \return 0 on success, -1 on error.
 168  */
 169 LIBVLC_API
 170 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
 171
 172 /**
 173  * Registers a callback for the LibVLC exit event. This is mostly useful if
 174  * the VLC playlist and/or at least one interface are started with
 175  * libvlc_playlist_play() or libvlc_add_intf() respectively.
 176  * Typically, this function will wake up your application main loop (from
 177  * another thread).
 178  *
 179  * \note This function should be called before the playlist or interface are
 180  * started. Otherwise, there is a small race condition: the exit event could
 181  * be raised before the handler is registered.
 182  *
 183  * \param p_instance LibVLC instance
 184  * \param cb callback to invoke when LibVLC wants to exit,
 185  *           or NULL to disable the exit handler (as by default)
 186  * \param opaque data pointer for the callback
 187  * \warning This function and libvlc_wait() cannot be used at the same time.
 188  */
 189 LIBVLC_API
 190 void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
 191                               void (*cb) (void *), void *opaque );
 192
 193 /**
 194  * Waits until an interface causes the instance to exit.
 195  * You should start at least one interface first, using libvlc_add_intf().
 196  *
 197  * \param p_instance the instance
 198  * \warning This function wastes one thread doing basically nothing.
 199  * libvlc_set_exit_handler() should be used instead.
 200  */
 201 LIBVLC_DEPRECATED LIBVLC_API
 202 void libvlc_wait( libvlc_instance_t *p_instance );
 203
 204 /**
 205  * Sets the application name. LibVLC passes this as the user agent string
 206  * when a protocol requires it.
 207  *
 208  * \param p_instance LibVLC instance
 209  * \param name human-readable application name, e.g. "FooBar player 1.2.3"
 210  * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
 211  * \version LibVLC 1.1.1 or later
 212  */
 213 LIBVLC_API
 214 void libvlc_set_user_agent( libvlc_instance_t *p_instance,
 215                             const char *name, const char *http );
 216
 217 /**
 218  * Sets some meta-information about the application.
 219  * See also libvlc_set_user_agent().
 220  *
 221  * \param p_instance LibVLC instance
 222  * \param id Java-style application identifier, e.g. "com.acme.foobar"
 223  * \param version application version numbers, e.g. "1.2.3"
 224  * \param icon application icon name, e.g. "foobar"
 225  * \version LibVLC 2.1.0 or later.
 226  */
 227 LIBVLC_API
 228 void libvlc_set_app_id( libvlc_instance_t *p_instance, const char *id,
 229                         const char *version, const char *icon );
 230
 231 /**
 232  * Retrieve libvlc version.
 233  *
 234  * Example: "1.1.0-git The Luggage"
 235  *
 236  * \return a string containing the libvlc version
 237  */
 238 LIBVLC_API const char * libvlc_get_version(void);
 239
 240 /**
 241  * Retrieve libvlc compiler version.
 242  *
 243  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 244  *
 245  * \return a string containing the libvlc compiler version
 246  */
 247 LIBVLC_API const char * libvlc_get_compiler(void);
 248
 249 /**
 250  * Retrieve libvlc changeset.
 251  *
 252  * Example: "aa9bce0bc4"
 253  *
 254  * \return a string containing the libvlc changeset
 255  */
 256 LIBVLC_API const char * libvlc_get_changeset(void);
 257
 258 /**
 259  * Frees an heap allocation returned by a LibVLC function.
 260  * If you know you're using the same underlying C run-time as the LibVLC
 261  * implementation, then you can call ANSI C free() directly instead.
 262  *
 263  * \param ptr the pointer
 264  */
 265 LIBVLC_API void libvlc_free( void *ptr );
 266
 267 /** \defgroup libvlc_event LibVLC asynchronous events
 268  * LibVLC emits asynchronous events.
 269  *
 270  * Several LibVLC objects (such @ref libvlc_instance_t as
 271  * @ref libvlc_media_player_t) generate events asynchronously. Each of them
 272  * provides @ref libvlc_event_manager_t event manager. You can subscribe to
 273  * events with libvlc_event_attach() and unsubscribe with
 274  * libvlc_event_detach().
 275  * @{
 276  */
 277
 278 /**
 279  * Event manager that belongs to a libvlc object, and from whom events can
 280  * be received.
 281  */
 282 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
 283
 284 struct libvlc_event_t;
 285
 286 /**
 287  * Type of a LibVLC event.
 288  */
 289 typedef int libvlc_event_type_t;
 290
 291 /**
 292  * Callback function notification
 293  * \param p_event the event triggering the callback
 294  */
 295 typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
 296
 297 /**
 298  * Register for an event notification.
 299  *
 300  * \param p_event_manager the event manager to which you want to attach to.
 301  *        Generally it is obtained by vlc_my_object_event_manager() where
 302  *        my_object is the object you want to listen to.
 303  * \param i_event_type the desired event to which we want to listen
 304  * \param f_callback the function to call when i_event_type occurs
 305  * \param user_data user provided data to carry with the event
 306  * \return 0 on success, ENOMEM on error
 307  */
 308 LIBVLC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
 309                                         libvlc_event_type_t i_event_type,
 310                                         libvlc_callback_t f_callback,
 311                                         void *user_data );
 312
 313 /**
 314  * Unregister an event notification.
 315  *
 316  * \param p_event_manager the event manager
 317  * \param i_event_type the desired event to which we want to unregister
 318  * \param f_callback the function to call when i_event_type occurs
 319  * \param p_user_data user provided data to carry with the event
 320  */
 321 LIBVLC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
 322                                          libvlc_event_type_t i_event_type,
 323                                          libvlc_callback_t f_callback,
 324                                          void *p_user_data );
 325
 326 /**
 327  * Get an event's type name.
 328  *
 329  * \param event_type the desired event
 330  */
 331 LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
 332
 333 /** @} */
 334
 335 /** \defgroup libvlc_log LibVLC logging
 336  * libvlc_log_* functions provide access to the LibVLC messages log.
 337  * This is used for logging and debugging.
 338  * @{
 339  */
 340
 341 /**
 342  * Logging messages level.
 343  * \note Future LibVLC versions may define new levels.
 344  */
 345 enum libvlc_log_level
 346 {
 347     LIBVLC_DEBUG=0,   /**< Debug message */
 348     LIBVLC_NOTICE=2,  /**< Important informational message */
 349     LIBVLC_WARNING=3, /**< Warning (potential error) message */
 350     LIBVLC_ERROR=4    /**< Error message */
 351 };
 352
 353 typedef struct vlc_log_t libvlc_log_t;
 354
 355 /**
 356  * Gets debugging information about a log message: the name of the VLC module
 357  * emitting the message and the message location within the source code.
 358  *
 359  * The returned module name and file name will be NULL if unknown.
 360  * The returned line number will similarly be zero if unknown.
 361  *
 362  * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
 363  * \param module module name storage (or NULL) [OUT]
 364  * \param file source code file name storage (or NULL) [OUT]
 365  * \param line source code file line number storage (or NULL) [OUT]
 366  * \warning The returned module name and source code file name, if non-NULL,
 367  * are only valid until the logging callback returns.
 368  *
 369  * \version LibVLC 2.1.0 or later
 370  */
 371 LIBVLC_API void libvlc_log_get_context(const libvlc_log_t *ctx,
 372                        const char **module, const char **file, unsigned *line);
 373
 374 /**
 375  * Gets VLC object information about a log message: the type name of the VLC
 376  * object emitting the message, the object header if any and a temporaly-unique
 377  * object identifier. This information is mainly meant for <b>manual</b>
 378  * troubleshooting.
 379  *
 380  * The returned type name may be "generic" if unknown, but it cannot be NULL.
 381  * The returned header will be NULL if unset; in current versions, the header
 382  * is used to distinguish for VLM inputs.
 383  * The returned object ID will be zero if the message is not associated with
 384  * any VLC object.
 385  *
 386  * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
 387  * \param name object name storage (or NULL) [OUT]
 388  * \param header object header (or NULL) [OUT]
 389  * \param line source code file line number storage (or NULL) [OUT]
 390  * \warning The returned module name and source code file name, if non-NULL,
 391  * are only valid until the logging callback returns.
 392  *
 393  * \version LibVLC 2.1.0 or later
 394  */
 395 LIBVLC_API void libvlc_log_get_object(const libvlc_log_t *ctx,
 396                         const char **name, const char **header, uintptr_t *id);
 397
 398 /**
 399  * Callback prototype for LibVLC log message handler.
 400  * \param data data pointer as given to libvlc_log_set()
 401  * \param level message level (@ref enum libvlc_log_level)
 402  * \param ctx message context (meta-information about the message)
 403  * \param fmt printf() format string (as defined by ISO C11)
 404  * \param args variable argument list for the format
 405  * \note Log message handlers <b>must</b> be thread-safe.
 406  * \warning The message context pointer, the format string parameters and the
 407  *          variable arguments are only valid until the callback returns.
 408  */
 409 typedef void (*libvlc_log_cb)(void *data, int level, const libvlc_log_t *ctx,
 410                               const char *fmt, va_list args);
 411
 412 /**
 413  * Unsets the logging callback for a LibVLC instance. This is rarely needed:
 414  * the callback is implicitly unset when the instance is destroyed.
 415  * This function will wait for any pending callbacks invocation to complete
 416  * (causing a deadlock if called from within the callback).
 417  *
 418  * \param p_instance libvlc instance
 419  * \version LibVLC 2.1.0 or later
 420  */
 421 LIBVLC_API void libvlc_log_unset( libvlc_instance_t * );
 422
 423 /**
 424  * Sets the logging callback for a LibVLC instance.
 425  * This function is thread-safe: it will wait for any pending callbacks
 426  * invocation to complete.
 427  *
 428  * \param cb callback function pointer
 429  * \param data opaque data pointer for the callback function
 430  *
 431  * \note Some log messages (especially debug) are emitted by LibVLC while
 432  * is being initialized. These messages cannot be captured with this interface.
 433  *
 434  * \warning A deadlock may occur if this function is called from the callback.
 435  *
 436  * \param p_instance libvlc instance
 437  * \version LibVLC 2.1.0 or later
 438  */
 439 LIBVLC_API void libvlc_log_set( libvlc_instance_t *,
 440                                 libvlc_log_cb cb, void *data );
 441
 442
 443 /**
 444  * Sets up logging to a file.
 445  * \param p_instance libvlc instance
 446  * \param stream FILE pointer opened for writing
 447  *         (the FILE pointer must remain valid until libvlc_log_unset())
 448  * \version LibVLC 2.1.0 or later
 449  */
 450 LIBVLC_API void libvlc_log_set_file( libvlc_instance_t *, FILE *stream );
 451
 452 /**
 453  * Always returns minus one.
 454  * This function is only provided for backward compatibility.
 455  *
 456  * \param p_instance ignored
 457  * \return always -1
 458  */
 459 LIBVLC_DEPRECATED LIBVLC_API
 460 unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
 461
 462 /**
 463  * This function does nothing.
 464  * It is only provided for backward compatibility.
 465  *
 466  * \param p_instance ignored
 467  * \param level ignored
 468  */
 469 LIBVLC_DEPRECATED LIBVLC_API
 470 void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
 471
 472 /**
 473  * This function does nothing useful.
 474  * It is only provided for backward compatibility.
 475  *
 476  * \param p_instance libvlc instance
 477  * \return an unique pointer or NULL on error
 478  */
 479 LIBVLC_DEPRECATED LIBVLC_API
 480 libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
 481
 482 /**
 483  * Frees memory allocated by libvlc_log_open().
 484  *
 485  * \param p_log libvlc log instance or NULL
 486  */
 487 LIBVLC_DEPRECATED LIBVLC_API
 488 void libvlc_log_close( libvlc_log_t *p_log );
 489
 490 /**
 491  * Always returns zero.
 492  * This function is only provided for backward compatibility.
 493  *
 494  * \param p_log ignored
 495  * \return always zero
 496  */
 497 LIBVLC_DEPRECATED LIBVLC_API
 498 unsigned libvlc_log_count( const libvlc_log_t *p_log );
 499
 500 /**
 501  * This function does nothing.
 502  * It is only provided for backward compatibility.
 503  *
 504  * \param p_log ignored
 505  */
 506 LIBVLC_DEPRECATED LIBVLC_API
 507 void libvlc_log_clear( libvlc_log_t *p_log );
 508
 509 /**
 510  * This function does nothing useful.
 511  * It is only provided for backward compatibility.
 512  *
 513  * \param p_log ignored
 514  * \return an unique pointer or NULL on error or if the parameter was NULL
 515  */
 516 LIBVLC_DEPRECATED LIBVLC_API
 517 libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
 518
 519 /**
 520  * Frees memory allocated by libvlc_log_get_iterator().
 521  *
 522  * \param p_iter libvlc log iterator or NULL
 523  */
 524 LIBVLC_DEPRECATED LIBVLC_API
 525 void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
 526
 527 /**
 528  * Always returns zero.
 529  * This function is only provided for backward compatibility.
 530  *
 531  * \param p_iter ignored
 532  * \return always zero
 533  */
 534 LIBVLC_DEPRECATED LIBVLC_API
 535 int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
 536
 537 /**
 538  * Always returns NULL.
 539  * This function is only provided for backward compatibility.
 540  *
 541  * \param p_iter libvlc log iterator or NULL
 542  * \param p_buf ignored
 543  * \return always NULL
 544  */
 545 LIBVLC_DEPRECATED LIBVLC_API
 546 libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
 547                                                 libvlc_log_message_t *p_buf );
 548
 549 /** @} */
 550
 551 /**
 552  * Description of a module.
 553  */
 554 typedef struct libvlc_module_description_t
 555 {
 556     char *psz_name;
 557     char *psz_shortname;
 558     char *psz_longname;
 559     char *psz_help;
 560     struct libvlc_module_description_t *p_next;
 561 } libvlc_module_description_t;
 562
 563 /**
 564  * Release a list of module descriptions.
 565  *
 566  * \param p_list the list to be released
 567  */
 568 LIBVLC_API
 569 void libvlc_module_description_list_release( libvlc_module_description_t *p_list );
 570
 571 /**
 572  * Returns a list of audio filters that are available.
 573  *
 574  * \param p_instance libvlc instance
 575  *
 576  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 577  *         In case of an error, NULL is returned.
 578  *
 579  * \see libvlc_module_description_t
 580  * \see libvlc_module_description_list_release
 581  */
 582 LIBVLC_API
 583 libvlc_module_description_t *libvlc_audio_filter_list_get( libvlc_instance_t *p_instance );
 584
 585 /**
 586  * Returns a list of video filters that are available.
 587  *
 588  * \param p_instance libvlc instance
 589  *
 590  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 591  *         In case of an error, NULL is returned.
 592  *
 593  * \see libvlc_module_description_t
 594  * \see libvlc_module_description_list_release
 595  */
 596 LIBVLC_API
 597 libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );
 598
 599 /** @} */
 600
 601 /** \defgroup libvlc_clock LibVLC time
 602  * These functions provide access to the LibVLC time/clock.
 603  * @{
 604  */
 605
 606 /**
 607  * Return the current time as defined by LibVLC. The unit is the microsecond.
 608  * Time increases monotonically (regardless of time zone changes and RTC
 609  * adjustements).
 610  * The origin is arbitrary but consistent across the whole system
 611  * (e.g. the system uptim, the time since the system was booted).
 612  * \note On systems that support it, the POSIX monotonic clock is used.
 613  */
 614 LIBVLC_API
 615 int64_t libvlc_clock(void);
 616
 617 /**
 618  * Return the delay (in microseconds) until a certain timestamp.
 619  * \param pts timestamp
 620  * \return negative if timestamp is in the past,
 621  * positive if it is in the future
 622  */
 623 static inline int64_t libvlc_delay(int64_t pts)
 624 {
 625     return pts - libvlc_clock();
 626 }
 627
 628 /** @} */
 629
 630 # ifdef __cplusplus
 631 }
 632 # endif
 633
 634 #endif /* <vlc/libvlc.h> */