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