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  * This is libvlc, the base library of the VLC program.
  34  *
  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 /*****************************************************************************
  65  * Exception handling
  66  *****************************************************************************/
  67 /** \defgroup libvlc_exception libvlc_exception
  68  * \ingroup libvlc_core
  69  * LibVLC Exceptions handling
  70  * @{
  71  */
  72
  73 /**
  74  * Initialize an exception structure. This can be called several times to
  75  * reuse an exception structure.
  76  *
  77  * \param p_exception the exception to initialize
  78  */
  79 VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
  80
  81 /**
  82  * Has an exception been raised?
  83  *
  84  * \param p_exception the exception to query
  85  * \return 0 if the exception was raised, 1 otherwise
  86  */
  87 VLC_PUBLIC_API int
  88 libvlc_exception_raised( const libvlc_exception_t *p_exception );
  89
  90 /**
  91  * Raise an exception using a user-provided message.
  92  *
  93  * \param p_exception the exception to raise
  94  * \param psz_format the exception message format string
  95  * \param ... the format string arguments
  96  */
  97 VLC_PUBLIC_API void
  98 libvlc_exception_raise( libvlc_exception_t *p_exception,
  99                         const char *psz_format, ... );
 100
 101 /**
 102  * Clear an exception object so it can be reused.
 103  * The exception object must have be initialized.
 104  *
 105  * \param p_exception the exception to clear
 106  */
 107 VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
 108
 109 /**@} */
 110
 111 /*****************************************************************************
 112  * Error handling
 113  *****************************************************************************/
 114 /** \defgroup libvlc_error libvlc_error
 115  * \ingroup libvlc_core
 116  * LibVLC error handling
 117  * @{
 118  */
 119
 120 /**
 121  * A human-readable error message for the last LibVLC error in the calling
 122  * thread. The resulting string is valid until another error occurs (at least
 123  * until the next LibVLC call).
 124  *
 125  * @warning
 126  * This will be NULL if there was no error.
 127  */
 128 const char *libvlc_errmsg (void);
 129
 130 /**
 131  * Clears the LibVLC error status for the current thread. This is optional.
 132  * By default, the error status is automatically overriden when a new error
 133  * occurs, and destroyed when the thread exits.
 134  */
 135 void libvlc_clearerr (void);
 136
 137 /**
 138  * Sets the LibVLC error status and message for the current thread.
 139  * Any previous error is overriden.
 140  * @return a nul terminated string in any case
 141  */
 142 const char *libvlc_vprinterr (const char *fmt, va_list ap);
 143
 144 /**
 145  * Sets the LibVLC error status and message for the current thread.
 146  * Any previous error is overriden.
 147  * @return a nul terminated string in any case
 148  */
 149 const char *libvlc_printerr (const char *fmt, ...);
 150
 151 /**@} */
 152
 153
 154 /*****************************************************************************
 155  * Core handling
 156  *****************************************************************************/
 157
 158 /** \defgroup libvlc_core libvlc_core
 159  * \ingroup libvlc
 160  * LibVLC Core
 161  * @{
 162  */
 163
 164 /**
 165  * Create and initialize a libvlc instance.
 166  *
 167  * \param argc the number of arguments
 168  * \param argv command-line-type arguments. argv[0] must be the path of the
 169  *        calling program.
 170  * \param p_e an initialized exception pointer
 171  * \return the libvlc instance
 172  */
 173 VLC_PUBLIC_API libvlc_instance_t *
 174 libvlc_new( int , const char *const *, libvlc_exception_t *);
 175
 176 /**
 177  * Decrement the reference count of a libvlc instance, and destroy it
 178  * if it reaches zero.
 179  *
 180  * \param p_instance the instance to destroy
 181  */
 182 VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
 183
 184 /**
 185  * Increments the reference count of a libvlc instance.
 186  * The initial reference count is 1 after libvlc_new() returns.
 187  *
 188  * \param p_instance the instance to reference
 189  */
 190 VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
 191
 192 /**
 193  * Try to start a user interface for the libvlc instance.
 194  *
 195  * \param p_instance the instance
 196  * \param name interface name, or NULL for default
 197  * \param p_exception an initialized exception pointer
 198  * \return 0 on success, -1 on error.
 199  */
 200 VLC_PUBLIC_API
 201 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name,
 202                      libvlc_exception_t *p_exception );
 203
 204 /**
 205  * Waits until an interface causes the instance to exit.
 206  * You should start at least one interface first, using libvlc_add_intf().
 207  *
 208  * \param p_instance the instance
 209  */
 210 VLC_PUBLIC_API
 211 void libvlc_wait( libvlc_instance_t *p_instance );
 212
 213 /**
 214  * Retrieve libvlc version.
 215  *
 216  * Example: "0.9.0-git Grishenko"
 217  *
 218  * \return a string containing the libvlc version
 219  */
 220 VLC_PUBLIC_API const char * libvlc_get_version(void);
 221
 222 /**
 223  * Retrieve libvlc compiler version.
 224  *
 225  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 226  *
 227  * \return a string containing the libvlc compiler version
 228  */
 229 VLC_PUBLIC_API const char * libvlc_get_compiler(void);
 230
 231 /**
 232  * Retrieve libvlc changeset.
 233  *
 234  * Example: "aa9bce0bc4"
 235  *
 236  * \return a string containing the libvlc changeset
 237  */
 238 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
 239
 240 struct vlc_object_t;
 241
 242 /**
 243  * Get the internal main VLC object.
 244  * Use of this function is usually a hack and should be avoided.
 245  * @note
 246  * You will need to link with libvlccore to make any use of the underlying VLC
 247  * object. The libvlccore programming and binary interfaces are not stable.
 248  * @warning
 249  * Remember to release the object with vlc_object_release().
 250  *
 251  * \param p_instance the libvlc instance
 252  * @return a VLC object of type "libvlc"
 253  */
 254 VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *p_instance);
 255
 256 /**
 257  * Frees an heap allocation (char *) returned by a LibVLC API.
 258  * If you know you're using the same underlying C run-time as the LibVLC
 259  * implementation, then you can call ANSI C free() directly instead.
 260  */
 261 VLC_PUBLIC_API void libvlc_free( void *ptr );
 262
 263 /** @}*/
 264
 265 /*****************************************************************************
 266  * Event handling
 267  *****************************************************************************/
 268
 269 /** \defgroup libvlc_event libvlc_event
 270  * \ingroup libvlc_core
 271  * LibVLC Events
 272  * @{
 273  */
 274
 275 /**
 276  * Event manager that belongs to a libvlc object, and from whom events can
 277  * be received.
 278  */
 279
 280 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
 281 typedef struct libvlc_event_t libvlc_event_t;
 282 typedef uint32_t libvlc_event_type_t;
 283
 284 /**
 285  * Callback function notification
 286  * \param p_event the event triggering the callback
 287  */
 288
 289 typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
 290
 291 /**
 292  * Register for an event notification.
 293  *
 294  * \param p_event_manager the event manager to which you want to attach to.
 295  *        Generally it is obtained by vlc_my_object_event_manager() where
 296  *        my_object is the object you want to listen to.
 297  * \param i_event_type the desired event to which we want to listen
 298  * \param f_callback the function to call when i_event_type occurs
 299  * \param user_data user provided data to carry with the event
 300  * \param p_e an initialized exception pointer
 301  */
 302 VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
 303                                          libvlc_event_type_t i_event_type,
 304                                          libvlc_callback_t f_callback,
 305                                          void *user_data,
 306                                          libvlc_exception_t *p_e );
 307
 308 /**
 309  * Unregister an event notification.
 310  *
 311  * \param p_event_manager the event manager
 312  * \param i_event_type the desired event to which we want to unregister
 313  * \param f_callback the function to call when i_event_type occurs
 314  * \param p_user_data user provided data to carry with the event
 315  * \param p_e an initialized exception pointer
 316  */
 317 VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
 318                                          libvlc_event_type_t i_event_type,
 319                                          libvlc_callback_t f_callback,
 320                                          void *p_user_data,
 321                                          libvlc_exception_t *p_e );
 322
 323 /**
 324  * Get an event's type name.
 325  *
 326  * \param i_event_type the desired event
 327  */
 328 VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
 329
 330 /** @} */
 331
 332 /*****************************************************************************
 333  * Message log handling
 334  *****************************************************************************/
 335
 336 /** \defgroup libvlc_log libvlc_log
 337  * \ingroup libvlc_core
 338  * LibVLC Message Logging
 339  * @{
 340  */
 341
 342 /**
 343  * Return the VLC messaging verbosity level.
 344  *
 345  * \param p_instance libvlc instance
 346  * \return verbosity level for messages
 347  */
 348 VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
 349
 350 /**
 351  * Set the VLC messaging verbosity level.
 352  *
 353  * \param p_instance libvlc log instance
 354  * \param level log level
 355  */
 356 VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
 357
 358 /**
 359  * Open a VLC message log instance.
 360  *
 361  * \param p_instance libvlc instance
 362  * \param p_e an initialized exception pointer
 363  * \return log message instance
 364  */
 365 VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *);
 366
 367 /**
 368  * Close a VLC message log instance.
 369  *
 370  * \param p_log libvlc log instance or NULL
 371  */
 372 VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );
 373
 374 /**
 375  * Returns the number of messages in a log instance.
 376  *
 377  * \param p_log libvlc log instance or NULL
 378  * \param p_e an initialized exception pointer
 379  * \return number of log messages, 0 if p_log is NULL
 380  */
 381 VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
 382
 383 /**
 384  * Clear a log instance.
 385  *
 386  * All messages in the log are removed. The log should be cleared on a
 387  * regular basis to avoid clogging.
 388  *
 389  * \param p_log libvlc log instance or NULL
 390  */
 391 VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );
 392
 393 /**
 394  * Allocate and returns a new iterator to messages in log.
 395  *
 396  * \param p_log libvlc log instance
 397  * \param p_e an initialized exception pointer
 398  * \return log iterator object
 399  */
 400 VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
 401
 402 /**
 403  * Release a previoulsy allocated iterator.
 404  *
 405  * \param p_iter libvlc log iterator or NULL
 406  */
 407 VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
 408
 409 /**
 410  * Return whether log iterator has more messages.
 411  *
 412  * \param p_iter libvlc log iterator or NULL
 413  * \return true if iterator has more message objects, else false
 414  */
 415 VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
 416
 417 /**
 418  * Return the next log message.
 419  *
 420  * The message contents must not be freed
 421  *
 422  * \param p_iter libvlc log iterator or NULL
 423  * \param p_buffer log buffer
 424  * \param p_e an initialized exception pointer
 425  * \return log message object
 426  */
 427 VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
 428                                                                libvlc_log_message_t *p_buffer,
 429                                                                libvlc_exception_t *p_e );
 430
 431 /** @} */
 432
 433 # ifdef __cplusplus
 434 }
 435 # endif
 436
 437 #endif /* <vlc/libvlc.h> */