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