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