libvlc.h 21.3 KB
Newer Older
zorglub's avatar
zorglub committed
1
/*****************************************************************************
2
 * libvlc.h:  libvlc external API
zorglub's avatar
zorglub 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$
zorglub's avatar
zorglub 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>
zorglub's avatar
zorglub 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
zorglub's avatar
zorglub 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.
zorglub's avatar
zorglub 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.
zorglub's avatar
zorglub committed
24
25
26
 *****************************************************************************/

/**
27
28
29
 * \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.
zorglub's avatar
zorglub committed
30
 * @{
31
32
 * \file
 * LibVLC core external API
zorglub's avatar
zorglub committed
33
34
 */

35
36
#ifndef VLC_LIBVLC_H
#define VLC_LIBVLC_H 1
zorglub's avatar
zorglub committed
37

38
#if defined (_WIN32) && defined (DLL_EXPORT)
39
# define LIBVLC_API __declspec(dllexport)
40
#elif defined (__GNUC__) && (__GNUC__ >= 4)
41
# define LIBVLC_API __attribute__((visibility("default")))
42
#else
43
# define LIBVLC_API
44
45
46
#endif

#ifdef __LIBVLC__
47
48
/* Avoid unhelpful warnings from libvlc with our deprecated APIs */
#   define LIBVLC_DEPRECATED
49
50
#elif defined(__GNUC__) && \
      (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
51
# define LIBVLC_DEPRECATED __attribute__((deprecated))
52
#else
53
# define LIBVLC_DEPRECATED
54
#endif
zorglub's avatar
zorglub committed
55

56
57
58
#include <stdio.h>
#include <stdarg.h>

zorglub's avatar
zorglub committed
59
60
61
62
# ifdef __cplusplus
extern "C" {
# endif

63
64
#include <vlc/libvlc_structures.h>

65
66
67
68
69
70
/** \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().
 *
71
72
73
 * \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.
74
75
76
77
 * @{
 */

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

/**
 * 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.
 */
89
LIBVLC_API const char *libvlc_errmsg (void);
90
91
92

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

/**
 * Sets the LibVLC error status and message for the current thread.
ivoire's avatar
ivoire committed
100
 * Any previous error is overridden.
Olivier Aubert's avatar
Olivier Aubert committed
101
102
 * \param fmt the format string
 * \param ap the arguments
103
 * \return a nul terminated string in any case
104
 */
105
LIBVLC_API const char *libvlc_vprinterr (const char *fmt, va_list ap);
106
107
108

/**
 * Sets the LibVLC error status and message for the current thread.
ivoire's avatar
ivoire committed
109
 * Any previous error is overridden.
Olivier Aubert's avatar
Olivier Aubert committed
110
111
 * \param fmt the format string
 * \param args the arguments
112
 * \return a nul terminated string in any case
113
 */
114
LIBVLC_API const char *libvlc_printerr (const char *fmt, ...);
115
116
117

/**@} */

zorglub's avatar
zorglub committed
118
/**
sam's avatar
sam committed
119
 * Create and initialize a libvlc instance.
120
121
 * This functions accept a list of "command line" arguments similar to the
 * main(). These arguments affect the LibVLC instance default configuration.
sam's avatar
sam committed
122
 *
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 * \note
 * LibVLC may create threads. Therefore, any thread-unsafe process
 * initialization must be performed before calling libvlc_new(). In particular
 * and where applicable:
 * - setlocale() and textdomain(),
 * - setenv(), unsetenv() and putenv(),
 * - with the X11 display system, XInitThreads()
 *   (see also libvlc_media_player_set_xwindow()) and
 * - on Microsoft Windows, SetErrorMode().
 * - sigprocmask() shall never be invoked; pthread_sigmask() can be used.
 *
 * On POSIX systems, the SIGCHLD signal must <b>not</b> be ignored, i.e. the
 * signal handler must set to SIG_DFL or a function pointer, not SIG_IGN.
 * Also while LibVLC is active, the wait() function shall not be called, and
 * any call to waitpid() shall use a strictly positive value for the first
 * parameter (i.e. the PID). Failure to follow those rules may lead to a
 * deadlock or a busy loop.
 *
 * Also on POSIX systems, it is recommended that the SIGPIPE signal be blocked,
 * even if it is not, in principles, necessary.
 *
 * On Microsoft Windows Vista/2008, the process error mode
 * SEM_FAILCRITICALERRORS flag <b>must</b> with the SetErrorMode() function
 * before using LibVLC. On later versions, it is optional and unnecessary.
 *
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 * \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)
163
 * \return the libvlc instance or NULL in case of error
zorglub's avatar
zorglub committed
164
 */
165
LIBVLC_API libvlc_instance_t *
ivoire's avatar
ivoire committed
166
libvlc_new( int argc , const char *const *argv );
zorglub's avatar
zorglub committed
167
168

/**
sam's avatar
sam committed
169
 * Decrement the reference count of a libvlc instance, and destroy it
170
 * if it reaches zero.
sam's avatar
sam committed
171
 *
zorglub's avatar
zorglub committed
172
173
 * \param p_instance the instance to destroy
 */
174
LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
175
176
177

/**
 * Increments the reference count of a libvlc instance.
sam's avatar
sam committed
178
179
180
 * The initial reference count is 1 after libvlc_new() returns.
 *
 * \param p_instance the instance to reference
181
 */
182
LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
zorglub's avatar
zorglub committed
183

184
/**
185
 * Try to start a user interface for the libvlc instance.
186
187
188
 *
 * \param p_instance the instance
 * \param name interface name, or NULL for default
189
 * \return 0 on success, -1 on error.
190
 */
191
LIBVLC_API
192
int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
193

194
195
/**
 * Registers a callback for the LibVLC exit event. This is mostly useful if
196
197
 * the VLC playlist and/or at least one interface are started with
 * libvlc_playlist_play() or libvlc_add_intf() respectively.
198
199
200
 * Typically, this function will wake up your application main loop (from
 * another thread).
 *
201
202
203
204
 * \note This function should be called before the playlist or interface are
 * started. Otherwise, there is a small race condition: the exit event could
 * be raised before the handler is registered.
 *
205
 * \param p_instance LibVLC instance
206
207
 * \param cb callback to invoke when LibVLC wants to exit,
 *           or NULL to disable the exit handler (as by default)
208
209
210
 * \param opaque data pointer for the callback
 * \warning This function and libvlc_wait() cannot be used at the same time.
 */
211
LIBVLC_API
212
213
214
void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
                              void (*cb) (void *), void *opaque );

215
216
217
218
219
/**
 * 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
220
221
 * \warning This function wastes one thread doing basically nothing.
 * libvlc_set_exit_handler() should be used instead.
222
 */
223
LIBVLC_DEPRECATED LIBVLC_API
224
225
void libvlc_wait( libvlc_instance_t *p_instance );

226
227
228
229
230
231
232
233
234
/**
 * 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
 */
235
LIBVLC_API
236
237
238
void libvlc_set_user_agent( libvlc_instance_t *p_instance,
                            const char *name, const char *http );

239
/**
240
 * Sets some meta-information about the application.
241
242
243
244
245
246
247
248
249
250
251
252
 * See also libvlc_set_user_agent().
 *
 * \param p_instance LibVLC instance
 * \param id Java-style application identifier, e.g. "com.acme.foobar"
 * \param version application version numbers, e.g. "1.2.3"
 * \param icon application icon name, e.g. "foobar"
 * \version LibVLC 2.1.0 or later.
 */
LIBVLC_API
void libvlc_set_app_id( libvlc_instance_t *p_instance, const char *id,
                        const char *version, const char *icon );

253
254
255
/**
 * Retrieve libvlc version.
 *
256
 * Example: "1.1.0-git The Luggage"
257
258
259
 *
 * \return a string containing the libvlc version
 */
260
LIBVLC_API const char * libvlc_get_version(void);
261
262
263
264
265
266
267
268

/**
 * Retrieve libvlc compiler version.
 *
 * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 *
 * \return a string containing the libvlc compiler version
 */
269
LIBVLC_API const char * libvlc_get_compiler(void);
270
271
272
273
274
275
276
277

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

280
281
282
283
284
285
286
/**
 * 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
 */
287
LIBVLC_API void libvlc_free( void *ptr );
288

289
290
291
292
293
294
295
296
/** \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().
zorglub's avatar
zorglub committed
297
298
299
 * @{
 */

300
/**
301
302
 * Event manager that belongs to a libvlc object, and from whom events can
 * be received.
303
 */
304
typedef struct libvlc_event_manager_t libvlc_event_manager_t;
305
306
307
308
309
310
311
312

struct libvlc_event_t;

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

313
/**
314
315
 * Callback function notification
 * \param p_event the event triggering the callback
316
 */
317
typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
318

319
/**
320
 * Register for an event notification.
321
 *
322
323
324
325
326
327
 * \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
328
 * \return 0 on success, ENOMEM on error
329
 */
330
LIBVLC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
331
332
333
                                        libvlc_event_type_t i_event_type,
                                        libvlc_callback_t f_callback,
                                        void *user_data );
334
335

/**
336
 * Unregister an event notification.
337
 *
338
339
340
341
 * \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
342
 */
343
LIBVLC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
344
345
                                         libvlc_event_type_t i_event_type,
                                         libvlc_callback_t f_callback,
346
                                         void *p_user_data );
347

348
349
350
351
352
/**
 * Get an event's type name.
 *
 * \param event_type the desired event
 */
353
LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
354

355
356
/** @} */

357
358
/** \defgroup libvlc_log LibVLC logging
 * libvlc_log_* functions provide access to the LibVLC messages log.
359
 * This is used for logging and debugging.
360
361
362
 * @{
 */

363
364
365
366
367
368
/**
 * Logging messages level.
 * \note Future LibVLC versions may define new levels.
 */
enum libvlc_log_level
{
369
370
371
372
    LIBVLC_DEBUG=0,   /**< Debug message */
    LIBVLC_NOTICE=2,  /**< Important informational message */
    LIBVLC_WARNING=3, /**< Warning (potential error) message */
    LIBVLC_ERROR=4    /**< Error message */
373
374
};

375
376
typedef struct vlc_log_t libvlc_log_t;

377
/**
378
 * Gets debugging information about a log message: the name of the VLC module
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 * emitting the message and the message location within the source code.
 *
 * The returned module name and file name will be NULL if unknown.
 * The returned line number will similarly be zero if unknown.
 *
 * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
 * \param module module name storage (or NULL) [OUT]
 * \param file source code file name storage (or NULL) [OUT]
 * \param line source code file line number storage (or NULL) [OUT]
 * \warning The returned module name and source code file name, if non-NULL,
 * are only valid until the logging callback returns.
 *
 * \version LibVLC 2.1.0 or later
 */
393
394
LIBVLC_API void libvlc_log_get_context(const libvlc_log_t *ctx,
                       const char **module, const char **file, unsigned *line);
395
396

/**
397
 * Gets VLC object information about a log message: the type name of the VLC
398
 * object emitting the message, the object header if any and a temporaly-unique
Pierre Ynard's avatar
Pierre Ynard committed
399
 * object identifier. This information is mainly meant for <b>manual</b>
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 * troubleshooting.
 *
 * The returned type name may be "generic" if unknown, but it cannot be NULL.
 * The returned header will be NULL if unset; in current versions, the header
 * is used to distinguish for VLM inputs.
 * The returned object ID will be zero if the message is not associated with
 * any VLC object.
 *
 * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
 * \param name object name storage (or NULL) [OUT]
 * \param header object header (or NULL) [OUT]
 * \param line source code file line number storage (or NULL) [OUT]
 * \warning The returned module name and source code file name, if non-NULL,
 * are only valid until the logging callback returns.
 *
 * \version LibVLC 2.1.0 or later
 */
417
418
LIBVLC_API void libvlc_log_get_object(const libvlc_log_t *ctx,
                        const char **name, const char **header, uintptr_t *id);
419

420
421
/**
 * Callback prototype for LibVLC log message handler.
422
 * \param data data pointer as given to libvlc_log_set()
423
 * \param level message level (@ref libvlc_log_level)
424
 * \param ctx message context (meta-information about the message)
425
426
427
 * \param fmt printf() format string (as defined by ISO C11)
 * \param args variable argument list for the format
 * \note Log message handlers <b>must</b> be thread-safe.
428
429
 * \warning The message context pointer, the format string parameters and the
 *          variable arguments are only valid until the callback returns.
430
 */
431
432
typedef void (*libvlc_log_cb)(void *data, int level, const libvlc_log_t *ctx,
                              const char *fmt, va_list args);
433
434

/**
435
436
437
438
439
 * Unsets the logging callback for a LibVLC instance. This is rarely needed:
 * the callback is implicitly unset when the instance is destroyed.
 * This function will wait for any pending callbacks invocation to complete
 * (causing a deadlock if called from within the callback).
 *
440
 * \param p_instance libvlc instance
441
 * \version LibVLC 2.1.0 or later
442
 */
443
LIBVLC_API void libvlc_log_unset( libvlc_instance_t * );
444
445

/**
446
447
448
 * Sets the logging callback for a LibVLC instance.
 * This function is thread-safe: it will wait for any pending callbacks
 * invocation to complete.
449
450
451
452
453
 *
 * \param cb callback function pointer
 * \param data opaque data pointer for the callback function
 *
 * \note Some log messages (especially debug) are emitted by LibVLC while
454
 * is being initialized. These messages cannot be captured with this interface.
455
 *
456
 * \warning A deadlock may occur if this function is called from the callback.
457
 *
458
 * \param p_instance libvlc instance
459
 * \version LibVLC 2.1.0 or later
460
 */
461
462
LIBVLC_API void libvlc_log_set( libvlc_instance_t *,
                                libvlc_log_cb cb, void *data );
463

464
465

/**
466
 * Sets up logging to a file.
467
 * \param p_instance libvlc instance
468
 * \param stream FILE pointer opened for writing
469
 *         (the FILE pointer must remain valid until libvlc_log_unset())
470
 * \version LibVLC 2.1.0 or later
471
 */
472
LIBVLC_API void libvlc_log_set_file( libvlc_instance_t *, FILE *stream );
473

474
/**
475
476
 * Always returns minus one.
 * This function is only provided for backward compatibility.
sam's avatar
sam committed
477
 *
478
479
 * \param p_instance ignored
 * \return always -1
480
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
481
482
LIBVLC_DEPRECATED LIBVLC_API
unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
483
484

/**
485
486
 * This function does nothing.
 * It is only provided for backward compatibility.
sam's avatar
sam committed
487
 *
488
489
 * \param p_instance ignored
 * \param level ignored
490
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
491
492
LIBVLC_DEPRECATED LIBVLC_API
void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
493
494

/**
495
496
 * This function does nothing useful.
 * It is only provided for backward compatibility.
sam's avatar
sam committed
497
 *
498
 * \param p_instance libvlc instance
499
 * \return an unique pointer or NULL on error
500
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
501
502
LIBVLC_DEPRECATED LIBVLC_API
libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
503
504

/**
505
 * Frees memory allocated by libvlc_log_open().
sam's avatar
sam committed
506
 *
507
 * \param p_log libvlc log instance or NULL
508
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
509
510
LIBVLC_DEPRECATED LIBVLC_API
void libvlc_log_close( libvlc_log_t *p_log );
511
512

/**
513
514
 * Always returns zero.
 * This function is only provided for backward compatibility.
sam's avatar
sam committed
515
 *
516
517
 * \param p_log ignored
 * \return always zero
518
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
519
520
LIBVLC_DEPRECATED LIBVLC_API
unsigned libvlc_log_count( const libvlc_log_t *p_log );
521
522

/**
523
524
 * This function does nothing.
 * It is only provided for backward compatibility.
sam's avatar
sam committed
525
 *
526
 * \param p_log ignored
527
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
528
529
LIBVLC_DEPRECATED LIBVLC_API
void libvlc_log_clear( libvlc_log_t *p_log );
530
531

/**
532
533
 * This function does nothing useful.
 * It is only provided for backward compatibility.
sam's avatar
sam committed
534
 *
535
536
 * \param p_log ignored
 * \return an unique pointer or NULL on error or if the parameter was NULL
537
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
538
539
LIBVLC_DEPRECATED LIBVLC_API
libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
540
541

/**
542
 * Frees memory allocated by libvlc_log_get_iterator().
sam's avatar
sam committed
543
 *
544
 * \param p_iter libvlc log iterator or NULL
545
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
546
547
LIBVLC_DEPRECATED LIBVLC_API
void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
548
549

/**
550
551
 * Always returns zero.
 * This function is only provided for backward compatibility.
sam's avatar
sam committed
552
 *
553
554
 * \param p_iter ignored
 * \return always zero
555
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
556
557
LIBVLC_DEPRECATED LIBVLC_API
int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
558
559

/**
560
561
 * Always returns NULL.
 * This function is only provided for backward compatibility.
sam's avatar
sam committed
562
 *
563
 * \param p_iter libvlc log iterator or NULL
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
564
 * \param p_buf ignored
565
 * \return always NULL
566
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
567
568
569
LIBVLC_DEPRECATED LIBVLC_API
libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
                                                libvlc_log_message_t *p_buf );
570
571

/** @} */
fawek's avatar
fawek committed
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589

/**
 * 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
 */
590
LIBVLC_API
fawek's avatar
fawek committed
591
592
593
594
595
596
597
598
599
600
601
602
603
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
 */
604
LIBVLC_API
fawek's avatar
fawek committed
605
606
607
608
609
610
611
612
613
614
615
616
617
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
 */
618
LIBVLC_API
fawek's avatar
fawek committed
619
620
libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );

621
/** @} */
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649

/** \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();
}

650
/** @} */
651

zorglub's avatar
zorglub committed
652
653
654
655
# ifdef __cplusplus
}
# endif

656
#endif /** @} */