libvlc.h 14.7 KB
Newer Older
Clément Stenac's avatar
Clément Stenac committed
1
/*****************************************************************************
2
 * libvlc.h:  libvlc external API
Clément Stenac's avatar
Clément Stenac committed
3
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
4
 * Copyright (C) 1998-2009 VLC authors and VideoLAN
Pierre's avatar
Pierre committed
5
 * $Id$
Clément Stenac's avatar
Clément Stenac committed
6
 *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
7
 * Authors: Clément Stenac <zorglub@videolan.org>
8
 *          Jean-Paul Saman <jpsaman@videolan.org>
9
 *          Pierre d'Herbemont <pdherbemont@videolan.org>
Clément Stenac's avatar
Clément Stenac committed
10
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
11 12 13
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
Clément Stenac's avatar
Clément Stenac committed
14 15 16 17
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
18 19
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
Clément Stenac's avatar
Clément Stenac committed
20
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
21 22 23
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
Clément Stenac's avatar
Clément Stenac committed
24 25
 *****************************************************************************/

26 27 28 29 30
/**
 * \file
 * This file defines libvlc external API
 */

Clément Stenac's avatar
Clément Stenac committed
31
/**
32 33 34
 * \defgroup libvlc LibVLC
 * LibVLC is the external programming interface of the VLC media player.
 * It is used to embed VLC into other applications or frameworks.
Clément Stenac's avatar
Clément Stenac committed
35 36 37
 * @{
 */

38 39
#ifndef VLC_LIBVLC_H
#define VLC_LIBVLC_H 1
Clément Stenac's avatar
Clément Stenac committed
40

41
#if defined (WIN32) && defined (DLL_EXPORT)
42
# define LIBVLC_API __declspec(dllexport)
43
#elif defined (__GNUC__) && (__GNUC__ >= 4)
44
# define LIBVLC_API __attribute__((visibility("default")))
45
#else
46
# define LIBVLC_API
47 48 49 50
#endif

#ifdef __LIBVLC__
/* Avoid unuseful warnings from libvlc with our deprecated APIs */
51
#   define LIBVLC_DEPRECATED LIBVLC_API
52 53
#elif defined(__GNUC__) && \
      (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
54
# define LIBVLC_DEPRECATED LIBVLC_API __attribute__((deprecated))
55
#else
56
# define LIBVLC_DEPRECATED LIBVLC_API
57
#endif
Clément Stenac's avatar
Clément Stenac committed
58 59 60 61 62

# ifdef __cplusplus
extern "C" {
# endif

63
#include <stdarg.h>
64 65
#include <vlc/libvlc_structures.h>

66 67 68 69 70 71
/** \defgroup libvlc_core LibVLC core
 * \ingroup libvlc
 * Before it can do anything useful, LibVLC must be initialized.
 * You can create one (or more) instance(s) of LibVLC in a given process,
 * with libvlc_new() and destroy them with libvlc_release().
 *
72 73 74
 * \version Unless otherwise stated, these functions are available
 * from LibVLC versions numbered 1.1.0 or more.
 * Earlier versions (0.9.x and 1.0.x) are <b>not</b> compatible.
75 76 77 78
 * @{
 */

/** \defgroup libvlc_error LibVLC error handling
79 80 81 82 83 84 85 86 87 88 89
 * @{
 */

/**
 * A human-readable error message for the last LibVLC error in the calling
 * thread. The resulting string is valid until another error occurs (at least
 * until the next LibVLC call).
 *
 * @warning
 * This will be NULL if there was no error.
 */
90
LIBVLC_API const char *libvlc_errmsg (void);
91 92 93

/**
 * Clears the LibVLC error status for the current thread. This is optional.
Rémi Duraffort's avatar
Rémi Duraffort committed
94
 * By default, the error status is automatically overridden when a new error
95 96
 * occurs, and destroyed when the thread exits.
 */
97
LIBVLC_API void libvlc_clearerr (void);
98 99 100

/**
 * Sets the LibVLC error status and message for the current thread.
Rémi Duraffort's avatar
Rémi Duraffort committed
101
 * Any previous error is overridden.
102
 * \return a nul terminated string in any case
103 104 105 106 107
 */
const char *libvlc_vprinterr (const char *fmt, va_list ap);

/**
 * Sets the LibVLC error status and message for the current thread.
Rémi Duraffort's avatar
Rémi Duraffort committed
108
 * Any previous error is overridden.
109
 * \return a nul terminated string in any case
110 111 112 113 114
 */
const char *libvlc_printerr (const char *fmt, ...);

/**@} */

Clément Stenac's avatar
Clément Stenac committed
115
/**
Sam Hocevar's avatar
Sam Hocevar committed
116
 * Create and initialize a libvlc instance.
117 118
 * This functions accept a list of "command line" arguments similar to the
 * main(). These arguments affect the LibVLC instance default configuration.
Sam Hocevar's avatar
Sam Hocevar committed
119
 *
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
 * \version
 * Arguments are meant to be passed from the command line to LibVLC, just like
 * VLC media player does. The list of valid arguments depends on the LibVLC
 * version, the operating system and platform, and set of available LibVLC
 * plugins. Invalid or unsupported arguments will cause the function to fail
 * (i.e. return NULL). Also, some arguments may alter the behaviour or
 * otherwise interfere with other LibVLC functions.
 *
 * \warning
 * There is absolutely no warranty or promise of forward, backward and
 * cross-platform compatibility with regards to libvlc_new() arguments.
 * We recommend that you do not use them, other than when debugging.
 *
 * \param argc the number of arguments (should be 0)
 * \param argv list of arguments (should be NULL)
135
 * \return the libvlc instance or NULL in case of error
Clément Stenac's avatar
Clément Stenac committed
136
 */
137
LIBVLC_API libvlc_instance_t *
138
libvlc_new( int argc , const char *const *argv );
Clément Stenac's avatar
Clément Stenac committed
139 140

/**
Sam Hocevar's avatar
Sam Hocevar committed
141
 * Decrement the reference count of a libvlc instance, and destroy it
142
 * if it reaches zero.
Sam Hocevar's avatar
Sam Hocevar committed
143
 *
Clément Stenac's avatar
Clément Stenac committed
144 145
 * \param p_instance the instance to destroy
 */
146
LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
147 148 149

/**
 * Increments the reference count of a libvlc instance.
Sam Hocevar's avatar
Sam Hocevar committed
150 151 152
 * The initial reference count is 1 after libvlc_new() returns.
 *
 * \param p_instance the instance to reference
153
 */
154
LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
Clément Stenac's avatar
Clément Stenac committed
155

156
/**
157
 * Try to start a user interface for the libvlc instance.
158 159 160
 *
 * \param p_instance the instance
 * \param name interface name, or NULL for default
161
 * \return 0 on success, -1 on error.
162
 */
163
LIBVLC_API
164
int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
165

166 167 168 169 170 171 172 173 174 175 176 177
/**
 * Registers a callback for the LibVLC exit event. This is mostly useful if
 * you have started at least one interface with libvlc_add_intf().
 * Typically, this function will wake up your application main loop (from
 * another thread).
 *
 * \param p_instance LibVLC instance
 * \param cb callback to invoke when LibVLC wants to exit
 * \param opaque data pointer for the callback
 * \warning This function and libvlc_wait() cannot be used at the same time.
 * Use either or none of them but not both.
 */
178
LIBVLC_API
179 180 181
void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
                              void (*cb) (void *), void *opaque );

182 183 184 185 186 187
/**
 * Waits until an interface causes the instance to exit.
 * You should start at least one interface first, using libvlc_add_intf().
 *
 * \param p_instance the instance
 */
188
LIBVLC_API
189 190
void libvlc_wait( libvlc_instance_t *p_instance );

191 192 193 194 195 196 197 198 199
/**
 * Sets the application name. LibVLC passes this as the user agent string
 * when a protocol requires it.
 *
 * \param p_instance LibVLC instance
 * \param name human-readable application name, e.g. "FooBar player 1.2.3"
 * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
 * \version LibVLC 1.1.1 or later
 */
200
LIBVLC_API
201 202 203
void libvlc_set_user_agent( libvlc_instance_t *p_instance,
                            const char *name, const char *http );

204 205 206
/**
 * Retrieve libvlc version.
 *
207
 * Example: "1.1.0-git The Luggage"
208 209 210
 *
 * \return a string containing the libvlc version
 */
211
LIBVLC_API const char * libvlc_get_version(void);
212 213 214 215 216 217 218 219

/**
 * Retrieve libvlc compiler version.
 *
 * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 *
 * \return a string containing the libvlc compiler version
 */
220
LIBVLC_API const char * libvlc_get_compiler(void);
221 222 223 224 225 226 227 228

/**
 * Retrieve libvlc changeset.
 *
 * Example: "aa9bce0bc4"
 *
 * \return a string containing the libvlc changeset
 */
229
LIBVLC_API const char * libvlc_get_changeset(void);
230

231 232 233 234 235 236 237
/**
 * Frees an heap allocation returned by a LibVLC function.
 * If you know you're using the same underlying C run-time as the LibVLC
 * implementation, then you can call ANSI C free() directly instead.
 *
 * \param ptr the pointer
 */
238
LIBVLC_API void libvlc_free( void *ptr );
239

240 241 242 243 244 245 246 247
/** \defgroup libvlc_event LibVLC asynchronous events
 * LibVLC emits asynchronous events.
 *
 * Several LibVLC objects (such @ref libvlc_instance_t as
 * @ref libvlc_media_player_t) generate events asynchronously. Each of them
 * provides @ref libvlc_event_manager_t event manager. You can subscribe to
 * events with libvlc_event_attach() and unsubscribe with
 * libvlc_event_detach().
Clément Stenac's avatar
Clément Stenac committed
248 249 250
 * @{
 */

251
/**
252 253
 * Event manager that belongs to a libvlc object, and from whom events can
 * be received.
254
 */
255
typedef struct libvlc_event_manager_t libvlc_event_manager_t;
256 257 258 259 260 261 262 263

struct libvlc_event_t;

/**
 * Type of a LibVLC event.
 */
typedef int libvlc_event_type_t;

264
/**
265 266
 * Callback function notification
 * \param p_event the event triggering the callback
267
 */
268
typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
269

270
/**
271
 * Register for an event notification.
272
 *
273 274 275 276 277 278
 * \param p_event_manager the event manager to which you want to attach to.
 *        Generally it is obtained by vlc_my_object_event_manager() where
 *        my_object is the object you want to listen to.
 * \param i_event_type the desired event to which we want to listen
 * \param f_callback the function to call when i_event_type occurs
 * \param user_data user provided data to carry with the event
279
 * \return 0 on success, ENOMEM on error
280
 */
281
LIBVLC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
282 283 284
                                        libvlc_event_type_t i_event_type,
                                        libvlc_callback_t f_callback,
                                        void *user_data );
285 286

/**
287
 * Unregister an event notification.
288
 *
289 290 291 292
 * \param p_event_manager the event manager
 * \param i_event_type the desired event to which we want to unregister
 * \param f_callback the function to call when i_event_type occurs
 * \param p_user_data user provided data to carry with the event
293
 */
294
LIBVLC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
295 296
                                         libvlc_event_type_t i_event_type,
                                         libvlc_callback_t f_callback,
297
                                         void *p_user_data );
298

299 300 301 302 303
/**
 * Get an event's type name.
 *
 * \param event_type the desired event
 */
304
LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
305

306 307
/** @} */

308 309 310
/** \defgroup libvlc_log LibVLC logging
 * libvlc_log_* functions provide access to the LibVLC messages log.
 * This is used for debugging or by advanced users.
311 312 313 314
 * @{
 */

/**
315 316
 * Always returns minus one.
 * This function is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
317
 *
318 319
 * \param p_instance ignored
 * \return always -1
320
 */
321
LIBVLC_DEPRECATED
322
LIBVLC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
323 324

/**
325 326
 * This function does nothing.
 * It is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
327
 *
328 329
 * \param p_instance ignored
 * \param level ignored
330
 */
331
LIBVLC_DEPRECATED
332
LIBVLC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
333 334

/**
335 336
 * This function does nothing useful.
 * It is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
337
 *
338
 * \param p_instance libvlc instance
339
 * \return an unique pointer or NULL on error
340
 */
341
LIBVLC_DEPRECATED
342
LIBVLC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
343 344

/**
345
 * Frees memory allocated by libvlc_log_open().
Sam Hocevar's avatar
Sam Hocevar committed
346
 *
347
 * \param p_log libvlc log instance or NULL
348
 */
349
LIBVLC_DEPRECATED
350
LIBVLC_API void libvlc_log_close( libvlc_log_t *p_log );
351 352

/**
353 354
 * Always returns zero.
 * This function is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
355
 *
356 357
 * \param p_log ignored
 * \return always zero
358
 */
359
LIBVLC_DEPRECATED
360
LIBVLC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
361 362

/**
363 364
 * This function does nothing.
 * It is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
365
 *
366
 * \param p_log ignored
367
 */
368
LIBVLC_DEPRECATED
369
LIBVLC_API void libvlc_log_clear( libvlc_log_t *p_log );
370 371

/**
372 373
 * This function does nothing useful.
 * It is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
374
 *
375 376
 * \param p_log ignored
 * \return an unique pointer or NULL on error or if the parameter was NULL
377
 */
378
LIBVLC_DEPRECATED
379
LIBVLC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
380 381

/**
382
 * Frees memory allocated by libvlc_log_get_iterator().
Sam Hocevar's avatar
Sam Hocevar committed
383
 *
384
 * \param p_iter libvlc log iterator or NULL
385
 */
386
LIBVLC_DEPRECATED
387
LIBVLC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
388 389

/**
390 391
 * Always returns zero.
 * This function is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
392
 *
393 394
 * \param p_iter ignored
 * \return always zero
395
 */
396
LIBVLC_DEPRECATED
397
LIBVLC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
398 399

/**
400 401
 * Always returns NULL.
 * This function is only provided for backward compatibility.
Sam Hocevar's avatar
Sam Hocevar committed
402
 *
403
 * \param p_iter libvlc log iterator or NULL
404 405
 * \param p_buffer ignored
 * \return always NULL
406
 */
407
LIBVLC_DEPRECATED
408
LIBVLC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
409
                                                           libvlc_log_message_t *p_buffer );
410 411

/** @} */
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429

/**
 * Description of a module.
 */
typedef struct libvlc_module_description_t
{
    char *psz_name;
    char *psz_shortname;
    char *psz_longname;
    char *psz_help;
    struct libvlc_module_description_t *p_next;
} libvlc_module_description_t;

/**
 * Release a list of module descriptions.
 *
 * \param p_list the list to be released
 */
430
LIBVLC_API
431 432 433 434 435 436 437 438 439 440 441 442 443
void libvlc_module_description_list_release( libvlc_module_description_t *p_list );

/**
 * Returns a list of audio filters that are available.
 *
 * \param p_instance libvlc instance
 *
 * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 *         In case of an error, NULL is returned.
 *
 * \see libvlc_module_description_t
 * \see libvlc_module_description_list_release
 */
444
LIBVLC_API
445 446 447 448 449 450 451 452 453 454 455 456 457
libvlc_module_description_t *libvlc_audio_filter_list_get( libvlc_instance_t *p_instance );

/**
 * Returns a list of video filters that are available.
 *
 * \param p_instance libvlc instance
 *
 * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
 *         In case of an error, NULL is returned.
 *
 * \see libvlc_module_description_t
 * \see libvlc_module_description_list_release
 */
458
LIBVLC_API
459 460
libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );

461
/** @} */
462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489

/** \defgroup libvlc_clock LibVLC time
 * These functions provide access to the LibVLC time/clock.
 * @{
 */

/**
 * Return the current time as defined by LibVLC. The unit is the microsecond.
 * Time increases monotonically (regardless of time zone changes and RTC
 * adjustements).
 * The origin is arbitrary but consistent across the whole system
 * (e.g. the system uptim, the time since the system was booted).
 * \note On systems that support it, the POSIX monotonic clock is used.
 */
LIBVLC_API
int64_t libvlc_clock(void);

/**
 * Return the delay (in microseconds) until a certain timestamp.
 * \param pts timestamp
 * \return negative if timestamp is in the past,
 * positive if it is in the future
 */
static inline int64_t libvlc_delay(int64_t pts)
{
    return pts - libvlc_clock();
}

490
/** @} */
491

Clément Stenac's avatar
Clément Stenac committed
492 493 494 495
# ifdef __cplusplus
}
# endif

Clément Stenac's avatar
Clément Stenac committed
496
#endif /* <vlc/libvlc.h> */