include/vlc/libvlc.h

   1 /*****************************************************************************
   2  * libvlc.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2009 the VideoLAN team
   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
  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  * \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 unuseful warnings from libvlc with our deprecated APIs */
  51 #   define LIBVLC_DEPRECATED LIBVLC_API
  52 #elif defined(__GNUC__) && \
  53       (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
  54 # define LIBVLC_DEPRECATED LIBVLC_API __attribute__((deprecated))
  55 #else
  56 # define LIBVLC_DEPRECATED LIBVLC_API
  57 #endif
  58
  59 # ifdef __cplusplus
  60 extern "C" {
  61 # endif
  62
  63 #include <stdarg.h>
  64 #include <vlc/libvlc_structures.h>
  65
  66 /** \defgroup libvlc_core LibVLC core
  67  * \ingroup libvlc
  68  * Before it can do anything useful, LibVLC must be initialized.
  69  * You can create one (or more) instance(s) of LibVLC in a given process,
  70  * with libvlc_new() and destroy them with libvlc_release().
  71  *
  72  * \version Unless otherwise stated, these functions are available
  73  * from LibVLC versions numbered 1.1.0 or more.
  74  * Earlier versions (0.9.x and 1.0.x) are <b>not</b> compatible.
  75  * @{
  76  */
  77
  78 /** \defgroup libvlc_error LibVLC error handling
  79  * @{
  80  */
  81
  82 /**
  83  * A human-readable error message for the last LibVLC error in the calling
  84  * thread. The resulting string is valid until another error occurs (at least
  85  * until the next LibVLC call).
  86  *
  87  * @warning
  88  * This will be NULL if there was no error.
  89  */
  90 LIBVLC_API const char *libvlc_errmsg (void);
  91
  92 /**
  93  * Clears the LibVLC error status for the current thread. This is optional.
  94  * By default, the error status is automatically overridden when a new error
  95  * occurs, and destroyed when the thread exits.
  96  */
  97 LIBVLC_API void libvlc_clearerr (void);
  98
  99 /**
 100  * Sets the LibVLC error status and message for the current thread.
 101  * Any previous error is overridden.
 102  * \return a nul terminated string in any case
 103  */
 104 const char *libvlc_vprinterr (const char *fmt, va_list ap);
 105
 106 /**
 107  * Sets the LibVLC error status and message for the current thread.
 108  * Any previous error is overridden.
 109  * \return a nul terminated string in any case
 110  */
 111 const char *libvlc_printerr (const char *fmt, ...);
 112
 113 /**@} */
 114
 115 /**
 116  * Create and initialize a libvlc instance.
 117  * This functions accept a list of "command line" arguments similar to the
 118  * main(). These arguments affect the LibVLC instance default configuration.
 119  *
 120  * \version
 121  * Arguments are meant to be passed from the command line to LibVLC, just like
 122  * VLC media player does. The list of valid arguments depends on the LibVLC
 123  * version, the operating system and platform, and set of available LibVLC
 124  * plugins. Invalid or unsupported arguments will cause the function to fail
 125  * (i.e. return NULL). Also, some arguments may alter the behaviour or
 126  * otherwise interfere with other LibVLC functions.
 127  *
 128  * \warning
 129  * There is absolutely no warranty or promise of forward, backward and
 130  * cross-platform compatibility with regards to libvlc_new() arguments.
 131  * We recommend that you do not use them, other than when debugging.
 132  *
 133  * \param argc the number of arguments (should be 0)
 134  * \param argv list of arguments (should be NULL)
 135  * \return the libvlc instance or NULL in case of error
 136  */
 137 LIBVLC_API libvlc_instance_t *
 138 libvlc_new( int argc , const char *const *argv );
 139
 140 /**
 141  * Decrement the reference count of a libvlc instance, and destroy it
 142  * if it reaches zero.
 143  *
 144  * \param p_instance the instance to destroy
 145  */
 146 LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
 147
 148 /**
 149  * Increments the reference count of a libvlc instance.
 150  * The initial reference count is 1 after libvlc_new() returns.
 151  *
 152  * \param p_instance the instance to reference
 153  */
 154 LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
 155
 156 /**
 157  * Try to start a user interface for the libvlc instance.
 158  *
 159  * \param p_instance the instance
 160  * \param name interface name, or NULL for default
 161  * \return 0 on success, -1 on error.
 162  */
 163 LIBVLC_API
 164 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
 165
 166 /**
 167  * Registers a callback for the LibVLC exit event. This is mostly useful if
 168  * you have started at least one interface with libvlc_add_intf().
 169  * Typically, this function will wake up your application main loop (from
 170  * another thread).
 171  *
 172  * \param p_instance LibVLC instance
 173  * \param cb callback to invoke when LibVLC wants to exit
 174  * \param opaque data pointer for the callback
 175  * \warning This function and libvlc_wait() cannot be used at the same time.
 176  * Use either or none of them but not both.
 177  */
 178 LIBVLC_API
 179 void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
 180                               void (*cb) (void *), void *opaque );
 181
 182 /**
 183  * Waits until an interface causes the instance to exit.
 184  * You should start at least one interface first, using libvlc_add_intf().
 185  *
 186  * \param p_instance the instance
 187  */
 188 LIBVLC_API
 189 void libvlc_wait( libvlc_instance_t *p_instance );
 190
 191 /**
 192  * Sets the application name. LibVLC passes this as the user agent string
 193  * when a protocol requires it.
 194  *
 195  * \param p_instance LibVLC instance
 196  * \param name human-readable application name, e.g. "FooBar player 1.2.3"
 197  * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
 198  * \version LibVLC 1.1.1 or later
 199  */
 200 LIBVLC_API
 201 void libvlc_set_user_agent( libvlc_instance_t *p_instance,
 202                             const char *name, const char *http );
 203
 204 /**
 205  * Retrieve libvlc version.
 206  *
 207  * Example: "1.1.0-git The Luggage"
 208  *
 209  * \return a string containing the libvlc version
 210  */
 211 LIBVLC_API const char * libvlc_get_version(void);
 212
 213 /**
 214  * Retrieve libvlc compiler version.
 215  *
 216  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 217  *
 218  * \return a string containing the libvlc compiler version
 219  */
 220 LIBVLC_API const char * libvlc_get_compiler(void);
 221
 222 /**
 223  * Retrieve libvlc changeset.
 224  *
 225  * Example: "aa9bce0bc4"
 226  *
 227  * \return a string containing the libvlc changeset
 228  */
 229 LIBVLC_API const char * libvlc_get_changeset(void);
 230
 231 /**
 232  * Frees an heap allocation returned by a LibVLC function.
 233  * If you know you're using the same underlying C run-time as the LibVLC
 234  * implementation, then you can call ANSI C free() directly instead.
 235  *
 236  * \param ptr the pointer
 237  */
 238 LIBVLC_API void libvlc_free( void *ptr );
 239
 240 /** \defgroup libvlc_event LibVLC asynchronous events
 241  * LibVLC emits asynchronous events.
 242  *
 243  * Several LibVLC objects (such @ref libvlc_instance_t as
 244  * @ref libvlc_media_player_t) generate events asynchronously. Each of them
 245  * provides @ref libvlc_event_manager_t event manager. You can subscribe to
 246  * events with libvlc_event_attach() and unsubscribe with
 247  * libvlc_event_detach().
 248  * @{
 249  */
 250
 251 /**
 252  * Event manager that belongs to a libvlc object, and from whom events can
 253  * be received.
 254  */
 255 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
 256
 257 struct libvlc_event_t;
 258
 259 /**
 260  * Type of a LibVLC event.
 261  */
 262 typedef int libvlc_event_type_t;
 263
 264 /**
 265  * Callback function notification
 266  * \param p_event the event triggering the callback
 267  */
 268 typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
 269
 270 /**
 271  * Register for an event notification.
 272  *
 273  * \param p_event_manager the event manager to which you want to attach to.
 274  *        Generally it is obtained by vlc_my_object_event_manager() where
 275  *        my_object is the object you want to listen to.
 276  * \param i_event_type the desired event to which we want to listen
 277  * \param f_callback the function to call when i_event_type occurs
 278  * \param user_data user provided data to carry with the event
 279  * \return 0 on success, ENOMEM on error
 280  */
 281 LIBVLC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
 282                                         libvlc_event_type_t i_event_type,
 283                                         libvlc_callback_t f_callback,
 284                                         void *user_data );
 285
 286 /**
 287  * Unregister an event notification.
 288  *
 289  * \param p_event_manager the event manager
 290  * \param i_event_type the desired event to which we want to unregister
 291  * \param f_callback the function to call when i_event_type occurs
 292  * \param p_user_data user provided data to carry with the event
 293  */
 294 LIBVLC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
 295                                          libvlc_event_type_t i_event_type,
 296                                          libvlc_callback_t f_callback,
 297                                          void *p_user_data );
 298
 299 /**
 300  * Get an event's type name.
 301  *
 302  * \param event_type the desired event
 303  */
 304 LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
 305
 306 /** @} */
 307
 308 /** \defgroup libvlc_log LibVLC logging
 309  * libvlc_log_* functions provide access to the LibVLC messages log.
 310  * This is used for debugging or by advanced users.
 311  * @{
 312  */
 313
 314 /**
 315  * Always returns minus one.
 316  * This function is only provided for backward compatibility.
 317  *
 318  * \param p_instance ignored
 319  * \return always -1
 320  */
 321 LIBVLC_DEPRECATED
 322 LIBVLC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
 323
 324 /**
 325  * This function does nothing.
 326  * It is only provided for backward compatibility.
 327  *
 328  * \param p_instance ignored
 329  * \param level ignored
 330  */
 331 LIBVLC_DEPRECATED
 332 LIBVLC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
 333
 334 /**
 335  * This function does nothing useful.
 336  * It is only provided for backward compatibility.
 337  *
 338  * \param p_instance libvlc instance
 339  * \return an unique pointer or NULL on error
 340  */
 341 LIBVLC_DEPRECATED
 342 LIBVLC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
 343
 344 /**
 345  * Frees memory allocated by libvlc_log_open().
 346  *
 347  * \param p_log libvlc log instance or NULL
 348  */
 349 LIBVLC_DEPRECATED
 350 LIBVLC_API void libvlc_log_close( libvlc_log_t *p_log );
 351
 352 /**
 353  * Always returns zero.
 354  * This function is only provided for backward compatibility.
 355  *
 356  * \param p_log ignored
 357  * \return always zero
 358  */
 359 LIBVLC_DEPRECATED
 360 LIBVLC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
 361
 362 /**
 363  * This function does nothing.
 364  * It is only provided for backward compatibility.
 365  *
 366  * \param p_log ignored
 367  */
 368 LIBVLC_DEPRECATED
 369 LIBVLC_API void libvlc_log_clear( libvlc_log_t *p_log );
 370
 371 /**
 372  * This function does nothing useful.
 373  * It is only provided for backward compatibility.
 374  *
 375  * \param p_log ignored
 376  * \return an unique pointer or NULL on error or if the parameter was NULL
 377  */
 378 LIBVLC_DEPRECATED
 379 LIBVLC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
 380
 381 /**
 382  * Frees memory allocated by libvlc_log_get_iterator().
 383  *
 384  * \param p_iter libvlc log iterator or NULL
 385  */
 386 LIBVLC_DEPRECATED
 387 LIBVLC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
 388
 389 /**
 390  * Always returns zero.
 391  * This function is only provided for backward compatibility.
 392  *
 393  * \param p_iter ignored
 394  * \return always zero
 395  */
 396 LIBVLC_DEPRECATED
 397 LIBVLC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
 398
 399 /**
 400  * Always returns NULL.
 401  * This function is only provided for backward compatibility.
 402  *
 403  * \param p_iter libvlc log iterator or NULL
 404  * \param p_buffer ignored
 405  * \return always NULL
 406  */
 407 LIBVLC_DEPRECATED
 408 LIBVLC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
 409                                                            libvlc_log_message_t *p_buffer );
 410
 411 /** @} */
 412
 413 /**
 414  * Description of a module.
 415  */
 416 typedef struct libvlc_module_description_t
 417 {
 418     char *psz_name;
 419     char *psz_shortname;
 420     char *psz_longname;
 421     char *psz_help;
 422     struct libvlc_module_description_t *p_next;
 423 } libvlc_module_description_t;
 424
 425 /**
 426  * Release a list of module descriptions.
 427  *
 428  * \param p_list the list to be released
 429  */
 430 LIBVLC_API
 431 void libvlc_module_description_list_release( libvlc_module_description_t *p_list );
 432
 433 /**
 434  * Returns a list of audio filters that are available.
 435  *
 436  * \param p_instance libvlc instance
 437  *
 438  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 439  *         In case of an error, NULL is returned.
 440  *
 441  * \see libvlc_module_description_t
 442  * \see libvlc_module_description_list_release
 443  */
 444 LIBVLC_API
 445 libvlc_module_description_t *libvlc_audio_filter_list_get( libvlc_instance_t *p_instance );
 446
 447 /**
 448  * Returns a list of video filters that are available.
 449  *
 450  * \param p_instance libvlc instance
 451  *
 452  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 453  *         In case of an error, NULL is returned.
 454  *
 455  * \see libvlc_module_description_t
 456  * \see libvlc_module_description_list_release
 457  */
 458 LIBVLC_API
 459 libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );
 460
 461 /** @} */
 462
 463 /** \defgroup libvlc_clock LibVLC time
 464  * These functions provide access to the LibVLC time/clock.
 465  * @{
 466  */
 467
 468 /**
 469  * Return the current time as defined by LibVLC. The unit is the microsecond.
 470  * Time increases monotonically (regardless of time zone changes and RTC
 471  * adjustements).
 472  * The origin is arbitrary but consistent across the whole system
 473  * (e.g. the system uptim, the time since the system was booted).
 474  * \note On systems that support it, the POSIX monotonic clock is used.
 475  */
 476 LIBVLC_API
 477 int64_t libvlc_clock(void);
 478
 479 /**
 480  * Return the delay (in microseconds) until a certain timestamp.
 481  * \param pts timestamp
 482  * \return negative if timestamp is in the past,
 483  * positive if it is in the future
 484  */
 485 static inline int64_t libvlc_delay(int64_t pts)
 486 {
 487     return pts - libvlc_clock();
 488 }
 489
 490 /** @} */
 491
 492 # ifdef __cplusplus
 493 }
 494 # endif
 495
 496 #endif /* <vlc/libvlc.h> */