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