home *** CD-ROM | disk | FTP | other *** search
/ mail.altrad.com / 2015.02.mail.altrad.com.tar / mail.altrad.com / TEST / vlc-2-0-5-win32.exe / sdk / include / vlc / libvlc.h < prev    next >
C/C++ Source or Header  |  2012-12-12  |  15KB  |  497 lines
  1. /*****************************************************************************
  2.  * libvlc.h:  libvlc external API
  3.  *****************************************************************************
  4.  * Copyright (C) 1998-2009 VLC authors and VideoLAN
  5.  * $Id: f7f4530556bbdc06d35bdceca35b87e0f6f18df3 $
  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. # 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. LIBVLC_API 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. LIBVLC_API 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> */
  497.