git.sesse.net Git - vlc/blob - 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 VLC_PUBLIC_API __declspec(dllexport)
  43 #else
  44 # define VLC_PUBLIC_API
  45 #endif
  46
  47 #ifdef __LIBVLC__
  48 /* Avoid unuseful warnings from libvlc with our deprecated APIs */
  49 #   define VLC_DEPRECATED_API VLC_PUBLIC_API
  50 #elif defined(__GNUC__) && \
  51       (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
  52 # define VLC_DEPRECATED_API VLC_PUBLIC_API __attribute__((deprecated))
  53 #else
  54 # define VLC_DEPRECATED_API VLC_PUBLIC_API
  55 #endif
  56
  57 # ifdef __cplusplus
  58 extern "C" {
  59 # endif
  60
  61 #include <stdarg.h>
  62 #include <vlc/libvlc_structures.h>
  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 /** \defgroup libvlc_error LibVLC error handling
  77  * @{
  78  */
  79
  80 /**
  81  * A human-readable error message for the last LibVLC error in the calling
  82  * thread. The resulting string is valid until another error occurs (at least
  83  * until the next LibVLC call).
  84  *
  85  * @warning
  86  * This will be NULL if there was no error.
  87  */
  88 VLC_PUBLIC_API const char *libvlc_errmsg (void);
  89
  90 /**
  91  * Clears the LibVLC error status for the current thread. This is optional.
  92  * By default, the error status is automatically overridden when a new error
  93  * occurs, and destroyed when the thread exits.
  94  */
  95 VLC_PUBLIC_API void libvlc_clearerr (void);
  96
  97 /**
  98  * Sets the LibVLC error status and message for the current thread.
  99  * Any previous error is overridden.
 100  * \return a nul terminated string in any case
 101  */
 102 const char *libvlc_vprinterr (const char *fmt, va_list ap);
 103
 104 /**
 105  * Sets the LibVLC error status and message for the current thread.
 106  * Any previous error is overridden.
 107  * \return a nul terminated string in any case
 108  */
 109 const char *libvlc_printerr (const char *fmt, ...);
 110
 111 /**@} */
 112
 113 /**
 114  * Create and initialize a libvlc instance.
 115  * This functions accept a list of "command line" arguments similar to the
 116  * main(). These arguments affect the LibVLC instance default configuration.
 117  *
 118  * \version
 119  * Arguments are meant to be passed from the command line to LibVLC, just like
 120  * VLC media player does. The list of valid arguments depends on the LibVLC
 121  * version, the operating system and platform, and set of available LibVLC
 122  * plugins. Invalid or unsupported arguments will cause the function to fail
 123  * (i.e. return NULL). Also, some arguments may alter the behaviour or
 124  * otherwise interfere with other LibVLC functions.
 125  *
 126  * \warning
 127  * There is absolutely no warranty or promise of forward, backward and
 128  * cross-platform compatibility with regards to libvlc_new() arguments.
 129  * We recommend that you do not use them, other than when debugging.
 130  *
 131  * \param argc the number of arguments (should be 0)
 132  * \param argv list of arguments (should be NULL)
 133  * \return the libvlc instance or NULL in case of error
 134  */
 135 VLC_PUBLIC_API libvlc_instance_t *
 136 libvlc_new( int argc , const char *const *argv );
 137
 138 /**
 139  * Decrement the reference count of a libvlc instance, and destroy it
 140  * if it reaches zero.
 141  *
 142  * \param p_instance the instance to destroy
 143  */
 144 VLC_PUBLIC_API void libvlc_release( libvlc_instance_t *p_instance );
 145
 146 /**
 147  * Increments the reference count of a libvlc instance.
 148  * The initial reference count is 1 after libvlc_new() returns.
 149  *
 150  * \param p_instance the instance to reference
 151  */
 152 VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t *p_instance );
 153
 154 /**
 155  * Try to start a user interface for the libvlc instance.
 156  *
 157  * \param p_instance the instance
 158  * \param name interface name, or NULL for default
 159  * \return 0 on success, -1 on error.
 160  */
 161 VLC_PUBLIC_API
 162 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
 163
 164 /**
 165  * Registers a callback for the LibVLC exit event. This is mostly useful if
 166  * you have started at least one interface with libvlc_add_intf().
 167  * Typically, this function will wake up your application main loop (from
 168  * another thread).
 169  *
 170  * \param p_instance LibVLC instance
 171  * \param cb callback to invoke when LibVLC wants to exit
 172  * \param opaque data pointer for the callback
 173  * \warning This function and libvlc_wait() cannot be used at the same time.
 174  * Use either or none of them but not both.
 175  */
 176 VLC_PUBLIC_API
 177 void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
 178                               void (*cb) (void *), void *opaque );
 179
 180 /**
 181  * Waits until an interface causes the instance to exit.
 182  * You should start at least one interface first, using libvlc_add_intf().
 183  *
 184  * \param p_instance the instance
 185  */
 186 VLC_PUBLIC_API
 187 void libvlc_wait( libvlc_instance_t *p_instance );
 188
 189 /**
 190  * Sets the application name. LibVLC passes this as the user agent string
 191  * when a protocol requires it.
 192  *
 193  * \param p_instance LibVLC instance
 194  * \param name human-readable application name, e.g. "FooBar player 1.2.3"
 195  * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
 196  * \version LibVLC 1.1.1 or later
 197  */
 198 VLC_PUBLIC_API
 199 void libvlc_set_user_agent( libvlc_instance_t *p_instance,
 200                             const char *name, const char *http );
 201
 202 /**
 203  * Retrieve libvlc version.
 204  *
 205  * Example: "1.1.0-git The Luggage"
 206  *
 207  * \return a string containing the libvlc version
 208  */
 209 VLC_PUBLIC_API const char * libvlc_get_version(void);
 210
 211 /**
 212  * Retrieve libvlc compiler version.
 213  *
 214  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 215  *
 216  * \return a string containing the libvlc compiler version
 217  */
 218 VLC_PUBLIC_API const char * libvlc_get_compiler(void);
 219
 220 /**
 221  * Retrieve libvlc changeset.
 222  *
 223  * Example: "aa9bce0bc4"
 224  *
 225  * \return a string containing the libvlc changeset
 226  */
 227 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
 228
 229 /**
 230  * Frees an heap allocation returned by a LibVLC function.
 231  * If you know you're using the same underlying C run-time as the LibVLC
 232  * implementation, then you can call ANSI C free() directly instead.
 233  *
 234  * \param ptr the pointer
 235  */
 236 VLC_PUBLIC_API void libvlc_free( void *ptr );
 237
 238 /** \defgroup libvlc_event LibVLC asynchronous events
 239  * LibVLC emits asynchronous events.
 240  *
 241  * Several LibVLC objects (such @ref libvlc_instance_t as
 242  * @ref libvlc_media_player_t) generate events asynchronously. Each of them
 243  * provides @ref libvlc_event_manager_t event manager. You can subscribe to
 244  * events with libvlc_event_attach() and unsubscribe with
 245  * libvlc_event_detach().
 246  * @{
 247  */
 248
 249 /**
 250  * Event manager that belongs to a libvlc object, and from whom events can
 251  * be received.
 252  */
 253 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
 254
 255 struct libvlc_event_t;
 256
 257 /**
 258  * Type of a LibVLC event.
 259  */
 260 typedef int libvlc_event_type_t;
 261
 262 /**
 263  * Callback function notification
 264  * \param p_event the event triggering the callback
 265  */
 266 typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
 267
 268 /**
 269  * Register for an event notification.
 270  *
 271  * \param p_event_manager the event manager to which you want to attach to.
 272  *        Generally it is obtained by vlc_my_object_event_manager() where
 273  *        my_object is the object you want to listen to.
 274  * \param i_event_type the desired event to which we want to listen
 275  * \param f_callback the function to call when i_event_type occurs
 276  * \param user_data user provided data to carry with the event
 277  * \return 0 on success, ENOMEM on error
 278  */
 279 VLC_PUBLIC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
 280                                         libvlc_event_type_t i_event_type,
 281                                         libvlc_callback_t f_callback,
 282                                         void *user_data );
 283
 284 /**
 285  * Unregister an event notification.
 286  *
 287  * \param p_event_manager the event manager
 288  * \param i_event_type the desired event to which we want to unregister
 289  * \param f_callback the function to call when i_event_type occurs
 290  * \param p_user_data user provided data to carry with the event
 291  */
 292 VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
 293                                          libvlc_event_type_t i_event_type,
 294                                          libvlc_callback_t f_callback,
 295                                          void *p_user_data );
 296
 297 /**
 298  * Get an event's type name.
 299  *
 300  * \param event_type the desired event
 301  */
 302 VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
 303
 304 /** @} */
 305
 306 /** \defgroup libvlc_log LibVLC logging
 307  * libvlc_log_* functions provide access to the LibVLC messages log.
 308  * This is used for debugging or by advanced users.
 309  * @{
 310  */
 311
 312 /**
 313  * Return the VLC messaging verbosity level.
 314  *
 315  * \param p_instance libvlc instance
 316  * \return verbosity level for messages
 317  */
 318 VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
 319
 320 /**
 321  * Set the VLC messaging verbosity level.
 322  *
 323  * \param p_instance libvlc log instance
 324  * \param level log level
 325  */
 326 VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
 327
 328 /**
 329  * Open a VLC message log instance.
 330  *
 331  * \param p_instance libvlc instance
 332  * \return log message instance or NULL on error
 333  */
 334 VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
 335
 336 /**
 337  * Close a VLC message log instance.
 338  *
 339  * \param p_log libvlc log instance or NULL
 340  */
 341 VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );
 342
 343 /**
 344  * Returns the number of messages in a log instance.
 345  *
 346  * \param p_log libvlc log instance or NULL
 347  * \return number of log messages, 0 if p_log is NULL
 348  */
 349 VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
 350
 351 /**
 352  * Clear a log instance.
 353  *
 354  * All messages in the log are removed. The log should be cleared on a
 355  * regular basis to avoid clogging.
 356  *
 357  * \param p_log libvlc log instance or NULL
 358  */
 359 VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );
 360
 361 /**
 362  * Allocate and returns a new iterator to messages in log.
 363  *
 364  * \param p_log libvlc log instance
 365  * \return log iterator object or NULL on error
 366  */
 367 VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
 368
 369 /**
 370  * Release a previoulsy allocated iterator.
 371  *
 372  * \param p_iter libvlc log iterator or NULL
 373  */
 374 VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
 375
 376 /**
 377  * Return whether log iterator has more messages.
 378  *
 379  * \param p_iter libvlc log iterator or NULL
 380  * \return true if iterator has more message objects, else false
 381  */
 382 VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
 383
 384 /**
 385  * Return the next log message.
 386  *
 387  * The message contents must not be freed
 388  *
 389  * \param p_iter libvlc log iterator or NULL
 390  * \param p_buffer log buffer
 391  * \return log message object or NULL if none left
 392  */
 393 VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
 394                                                                libvlc_log_message_t *p_buffer );
 395
 396 /** @} */
 397 /** @} */
 398 /** @} */
 399
 400 # ifdef __cplusplus
 401 }
 402 # endif
 403
 404 #endif /* <vlc/libvlc.h> */