1/*****************************************************************************
2 * libvlc.h: libvlc external API
3 *****************************************************************************
4 * Copyright (C) 1998-2009 VLC authors and VideoLAN
5 * $Id: b12d900469fa6438c41421f2ac7697b93ffc8a35 $
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 it
12 * under the terms of the GNU Lesser General Public License as published by
13 * the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * along with this program; if not, write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 *****************************************************************************/
25
26/**
27 * \defgroup libvlc LibVLC
28 * LibVLC is the external programming interface of the VLC media player.
29 * It is used to embed VLC into other applications or frameworks.
30 * @{
31 * \file
32 * LibVLC core external API
33 */
34
35#ifndef VLC_LIBVLC_H
36#define VLC_LIBVLC_H 1
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#endif
45
46#ifdef __LIBVLC__
47/* Avoid unhelpful warnings from libvlc with our deprecated APIs */
48# define LIBVLC_DEPRECATED
49#elif defined(__GNUC__) && \
50 (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
51# define LIBVLC_DEPRECATED __attribute__((deprecated))
52#else
53# define LIBVLC_DEPRECATED
54#endif
55
56#include <stdio.h>
57#include <stdarg.h>
58#include <stdint.h>
59
60# ifdef __cplusplus
61extern "C" {
62# endif
63
64/** \defgroup libvlc_core LibVLC core
65 * \ingroup libvlc
66 * Before it can do anything useful, LibVLC must be initialized.
67 * You can create one (or more) instance(s) of LibVLC in a given process,
68 * with libvlc_new() and destroy them with libvlc_release().
69 *
70 * \version Unless otherwise stated, these functions are available
71 * from LibVLC versions numbered 1.1.0 or more.
72 * Earlier versions (0.9.x and 1.0.x) are <b>not</b> compatible.
73 * @{
74 */
75
76/** This structure is opaque. It represents a libvlc instance */
77typedef struct libvlc_instance_t libvlc_instance_t;
78
79typedef int64_t libvlc_time_t;
80
81/** \defgroup libvlc_error LibVLC error handling
82 * @{
83 */
84
85/**
86 * A human-readable error message for the last LibVLC error in the calling
87 * thread. The resulting string is valid until another error occurs (at least
88 * until the next LibVLC call).
89 *
90 * @warning
91 * This will be NULL if there was no error.
92 */
93LIBVLC_API const char *libvlc_errmsg (void);
94
95/**
96 * Clears the LibVLC error status for the current thread. This is optional.
97 * By default, the error status is automatically overridden when a new error
98 * occurs, and destroyed when the thread exits.
99 */
100LIBVLC_API void libvlc_clearerr (void);
101
102/**
103 * Sets the LibVLC error status and message for the current thread.
104 * Any previous error is overridden.
105 * \param fmt the format string
106 * \param ap the arguments
107 * \return a nul terminated string in any case
108 */
109LIBVLC_API const char *libvlc_vprinterr (const char *fmt, va_list ap);
110
111/**
112 * Sets the LibVLC error status and message for the current thread.
113 * Any previous error is overridden.
114 * \param fmt the format string
115 * \param args the arguments
116 * \return a nul terminated string in any case
117 */
118LIBVLC_API const char *libvlc_printerr (const char *fmt, ...);
119
120/**@} */
121
122/**
123 * Create and initialize a libvlc instance.
124 * This functions accept a list of "command line" arguments similar to the
125 * main(). These arguments affect the LibVLC instance default configuration.
126 *
127 * \note
128 * LibVLC may create threads. Therefore, any thread-unsafe process
129 * initialization must be performed before calling libvlc_new(). In particular
130 * and where applicable:
131 * - setlocale() and textdomain(),
132 * - setenv(), unsetenv() and putenv(),
133 * - with the X11 display system, XInitThreads()
134 * (see also libvlc_media_player_set_xwindow()) and
135 * - on Microsoft Windows, SetErrorMode().
136 * - sigprocmask() shall never be invoked; pthread_sigmask() can be used.
137 *
138 * On POSIX systems, the SIGCHLD signal <b>must not</b> be ignored, i.e. the
139 * signal handler must set to SIG_DFL or a function pointer, not SIG_IGN.
140 * Also while LibVLC is active, the wait() function shall not be called, and
141 * any call to waitpid() shall use a strictly positive value for the first
142 * parameter (i.e. the PID). Failure to follow those rules may lead to a
143 * deadlock or a busy loop.
144 * Also on POSIX systems, it is recommended that the SIGPIPE signal be blocked,
145 * even if it is not, in principles, necessary, e.g.:
146 * @code
147 sigset_t set;
148
149 signal(SIGCHLD, SIG_DFL);
150 sigemptyset(&set);
151 sigaddset(&set, SIGPIPE);
152 pthread_sigmask(SIG_BLOCK, &set, NULL);
153 * @endcode
154 *
155 * On Microsoft Windows Vista/2008, the process error mode
156 * SEM_FAILCRITICALERRORS flag <b>must</b> be set before using LibVLC.
157 * On later versions, that is optional and unnecessary.
158 * Also on Microsoft Windows (Vista and any later version), setting the default
159 * DLL directories to SYSTEM32 exclusively is strongly recommended for
160 * security reasons:
161 * @code
162 SetErrorMode(SEM_FAILCRITICALERRORS);
163 SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_SYSTEM32);
164 * @endcode
165 *
166 * \version
167 * Arguments are meant to be passed from the command line to LibVLC, just like
168 * VLC media player does. The list of valid arguments depends on the LibVLC
169 * version, the operating system and platform, and set of available LibVLC
170 * plugins. Invalid or unsupported arguments will cause the function to fail
171 * (i.e. return NULL). Also, some arguments may alter the behaviour or
172 * otherwise interfere with other LibVLC functions.
173 *
174 * \warning
175 * There is absolutely no warranty or promise of forward, backward and
176 * cross-platform compatibility with regards to libvlc_new() arguments.
177 * We recommend that you do not use them, other than when debugging.
178 *
179 * \param argc the number of arguments (should be 0)
180 * \param argv list of arguments (should be NULL)
181 * \return the libvlc instance or NULL in case of error
182 */
183LIBVLC_API libvlc_instance_t *
184libvlc_new( int argc , const char *const *argv );
185
186/**
187 * Decrement the reference count of a libvlc instance, and destroy it
188 * if it reaches zero.
189 *
190 * \param p_instance the instance to destroy
191 */
192LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
193
194/**
195 * Increments the reference count of a libvlc instance.
196 * The initial reference count is 1 after libvlc_new() returns.
197 *
198 * \param p_instance the instance to reference
199 */
200LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
201
202/**
203 * Try to start a user interface for the libvlc instance.
204 *
205 * \param p_instance the instance
206 * \param name interface name, or NULL for default
207 * \return 0 on success, -1 on error.
208 */
209LIBVLC_API
210int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
211
212/**
213 * Registers a callback for the LibVLC exit event. This is mostly useful if
214 * the VLC playlist and/or at least one interface are started with
215 * libvlc_playlist_play() or libvlc_add_intf() respectively.
216 * Typically, this function will wake up your application main loop (from
217 * another thread).
218 *
219 * \note This function should be called before the playlist or interface are
220 * started. Otherwise, there is a small race condition: the exit event could
221 * be raised before the handler is registered.
222 *
223 * \param p_instance LibVLC instance
224 * \param cb callback to invoke when LibVLC wants to exit,
225 * or NULL to disable the exit handler (as by default)
226 * \param opaque data pointer for the callback
227 * \warning This function and libvlc_wait() cannot be used at the same time.
228 */
229LIBVLC_API
230void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
231 void (*cb) (void *), void *opaque );
232
233/**
234 * Sets the application name. LibVLC passes this as the user agent string
235 * when a protocol requires it.
236 *
237 * \param p_instance LibVLC instance
238 * \param name human-readable application name, e.g. "FooBar player 1.2.3"
239 * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
240 * \version LibVLC 1.1.1 or later
241 */
242LIBVLC_API
243void libvlc_set_user_agent( libvlc_instance_t *p_instance,
244 const char *name, const char *http );
245
246/**
247 * Sets some meta-information about the application.
248 * See also libvlc_set_user_agent().
249 *
250 * \param p_instance LibVLC instance
251 * \param id Java-style application identifier, e.g. "com.acme.foobar"
252 * \param version application version numbers, e.g. "1.2.3"
253 * \param icon application icon name, e.g. "foobar"
254 * \version LibVLC 2.1.0 or later.
255 */
256LIBVLC_API
257void libvlc_set_app_id( libvlc_instance_t *p_instance, const char *id,
258 const char *version, const char *icon );
259
260/**
261 * Retrieve libvlc version.
262 *
263 * Example: "1.1.0-git The Luggage"
264 *
265 * \return a string containing the libvlc version
266 */
267LIBVLC_API const char * libvlc_get_version(void);
268
269/**
270 * Retrieve libvlc compiler version.
271 *
272 * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
273 *
274 * \return a string containing the libvlc compiler version
275 */
276LIBVLC_API const char * libvlc_get_compiler(void);
277
278/**
279 * Retrieve libvlc changeset.
280 *
281 * Example: "aa9bce0bc4"
282 *
283 * \return a string containing the libvlc changeset
284 */
285LIBVLC_API const char * libvlc_get_changeset(void);
286
287/**
288 * Frees an heap allocation returned by a LibVLC function.
289 * If you know you're using the same underlying C run-time as the LibVLC
290 * implementation, then you can call ANSI C free() directly instead.
291 *
292 * \param ptr the pointer
293 */
294LIBVLC_API void libvlc_free( void *ptr );
295
296/** \defgroup libvlc_event LibVLC asynchronous events
297 * LibVLC emits asynchronous events.
298 *
299 * Several LibVLC objects (such @ref libvlc_instance_t as
300 * @ref libvlc_media_player_t) generate events asynchronously. Each of them
301 * provides @ref libvlc_event_manager_t event manager. You can subscribe to
302 * events with libvlc_event_attach() and unsubscribe with
303 * libvlc_event_detach().
304 * @{
305 */
306
307/**
308 * Event manager that belongs to a libvlc object, and from whom events can
309 * be received.
310 */
311typedef struct libvlc_event_manager_t libvlc_event_manager_t;
312
313struct libvlc_event_t;
314
315/**
316 * Type of a LibVLC event.
317 */
318typedef int libvlc_event_type_t;
319
320/**
321 * Callback function notification
322 * \param p_event the event triggering the callback
323 */
324typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *p_event, void *p_data );
325
326/**
327 * Register for an event notification.
328 *
329 * \param p_event_manager the event manager to which you want to attach to.
330 * Generally it is obtained by vlc_my_object_event_manager() where
331 * my_object is the object you want to listen to.
332 * \param i_event_type the desired event to which we want to listen
333 * \param f_callback the function to call when i_event_type occurs
334 * \param user_data user provided data to carry with the event
335 * \return 0 on success, ENOMEM on error
336 */
337LIBVLC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
338 libvlc_event_type_t i_event_type,
339 libvlc_callback_t f_callback,
340 void *user_data );
341
342/**
343 * Unregister an event notification.
344 *
345 * \param p_event_manager the event manager
346 * \param i_event_type the desired event to which we want to unregister
347 * \param f_callback the function to call when i_event_type occurs
348 * \param p_user_data user provided data to carry with the event
349 */
350LIBVLC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
351 libvlc_event_type_t i_event_type,
352 libvlc_callback_t f_callback,
353 void *p_user_data );
354
355/**
356 * Get an event's type name.
357 *
358 * \param event_type the desired event
359 */
360LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
361
362/** @} */
363
364/** \defgroup libvlc_log LibVLC logging
365 * libvlc_log_* functions provide access to the LibVLC messages log.
366 * This is used for logging and debugging.
367 * @{
368 */
369
370/**
371 * Logging messages level.
372 * \note Future LibVLC versions may define new levels.
373 */
374enum libvlc_log_level
375{
376 LIBVLC_DEBUG=0, /**< Debug message */
377 LIBVLC_NOTICE=2, /**< Important informational message */
378 LIBVLC_WARNING=3, /**< Warning (potential error) message */
379 LIBVLC_ERROR=4 /**< Error message */
380};
381
382typedef struct vlc_log_t libvlc_log_t;
383
384/**
385 * Gets log message debug infos.
386 *
387 * This function retrieves self-debug information about a log message:
388 * - the name of the VLC module emitting the message,
389 * - the name of the source code module (i.e. file) and
390 * - the line number within the source code module.
391 *
392 * The returned module name and file name will be NULL if unknown.
393 * The returned line number will similarly be zero if unknown.
394 *
395 * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
396 * \param module module name storage (or NULL) [OUT]
397 * \param file source code file name storage (or NULL) [OUT]
398 * \param line source code file line number storage (or NULL) [OUT]
399 * \warning The returned module name and source code file name, if non-NULL,
400 * are only valid until the logging callback returns.
401 *
402 * \version LibVLC 2.1.0 or later
403 */
404LIBVLC_API void libvlc_log_get_context(const libvlc_log_t *ctx,
405 const char **module, const char **file, unsigned *line);
406
407/**
408 * Gets log message info.
409 *
410 * This function retrieves meta-information about a log message:
411 * - the type name of the VLC object emitting the message,
412 * - the object header if any, and
413 * - a temporaly-unique object identifier.
414 *
415 * This information is mainly meant for <b>manual</b> troubleshooting.
416 *
417 * The returned type name may be "generic" if unknown, but it cannot be NULL.
418 * The returned header will be NULL if unset; in current versions, the header
419 * is used to distinguish for VLM inputs.
420 * The returned object ID will be zero if the message is not associated with
421 * any VLC object.
422 *
423 * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
424 * \param name object name storage (or NULL) [OUT]
425 * \param header object header (or NULL) [OUT]
426 * \param line source code file line number storage (or NULL) [OUT]
427 * \warning The returned module name and source code file name, if non-NULL,
428 * are only valid until the logging callback returns.
429 *
430 * \version LibVLC 2.1.0 or later
431 */
432LIBVLC_API void libvlc_log_get_object(const libvlc_log_t *ctx,
433 const char **name, const char **header, uintptr_t *id);
434
435/**
436 * Callback prototype for LibVLC log message handler.
437 *
438 * \param data data pointer as given to libvlc_log_set()
439 * \param level message level (@ref libvlc_log_level)
440 * \param ctx message context (meta-information about the message)
441 * \param fmt printf() format string (as defined by ISO C11)
442 * \param args variable argument list for the format
443 * \note Log message handlers <b>must</b> be thread-safe.
444 * \warning The message context pointer, the format string parameters and the
445 * variable arguments are only valid until the callback returns.
446 */
447typedef void (*libvlc_log_cb)(void *data, int level, const libvlc_log_t *ctx,
448 const char *fmt, va_list args);
449
450/**
451 * Unsets the logging callback.
452 *
453 * This function deregisters the logging callback for a LibVLC instance.
454 * This is rarely needed as the callback is implicitly unset when the instance
455 * is destroyed.
456 *
457 * \note This function will wait for any pending callbacks invocation to
458 * complete (causing a deadlock if called from within the callback).
459 *
460 * \param p_instance libvlc instance
461 * \version LibVLC 2.1.0 or later
462 */
463LIBVLC_API void libvlc_log_unset( libvlc_instance_t *p_instance );
464
465/**
466 * Sets the logging callback for a LibVLC instance.
467 *
468 * This function is thread-safe: it will wait for any pending callbacks
469 * invocation to complete.
470 *
471 * \param cb callback function pointer
472 * \param data opaque data pointer for the callback function
473 *
474 * \note Some log messages (especially debug) are emitted by LibVLC while
475 * is being initialized. These messages cannot be captured with this interface.
476 *
477 * \warning A deadlock may occur if this function is called from the callback.
478 *
479 * \param p_instance libvlc instance
480 * \version LibVLC 2.1.0 or later
481 */
482LIBVLC_API void libvlc_log_set( libvlc_instance_t *p_instance,
483 libvlc_log_cb cb, void *data );
484
485
486/**
487 * Sets up logging to a file.
488 * \param p_instance libvlc instance
489 * \param stream FILE pointer opened for writing
490 * (the FILE pointer must remain valid until libvlc_log_unset())
491 * \version LibVLC 2.1.0 or later
492 */
493LIBVLC_API void libvlc_log_set_file( libvlc_instance_t *p_instance, FILE *stream );
494
495/** @} */
496
497/**
498 * Description of a module.
499 */
500typedef struct libvlc_module_description_t
501{
502 char *psz_name;
503 char *psz_shortname;
504 char *psz_longname;
505 char *psz_help;
506 struct libvlc_module_description_t *p_next;
507} libvlc_module_description_t;
508
509/**
510 * Release a list of module descriptions.
511 *
512 * \param p_list the list to be released
513 */
514LIBVLC_API
515void libvlc_module_description_list_release( libvlc_module_description_t *p_list );
516
517/**
518 * Returns a list of audio filters that are available.
519 *
520 * \param p_instance libvlc instance
521 *
522 * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
523 * In case of an error, NULL is returned.
524 *
525 * \see libvlc_module_description_t
526 * \see libvlc_module_description_list_release
527 */
528LIBVLC_API
529libvlc_module_description_t *libvlc_audio_filter_list_get( libvlc_instance_t *p_instance );
530
531/**
532 * Returns a list of video filters that are available.
533 *
534 * \param p_instance libvlc instance
535 *
536 * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
537 * In case of an error, NULL is returned.
538 *
539 * \see libvlc_module_description_t
540 * \see libvlc_module_description_list_release
541 */
542LIBVLC_API
543libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );
544
545/** @} */
546
547/** \defgroup libvlc_clock LibVLC time
548 * These functions provide access to the LibVLC time/clock.
549 * @{
550 */
551
552/**
553 * Return the current time as defined by LibVLC. The unit is the microsecond.
554 * Time increases monotonically (regardless of time zone changes and RTC
555 * adjustements).
556 * The origin is arbitrary but consistent across the whole system
557 * (e.g. the system uptim, the time since the system was booted).
558 * \note On systems that support it, the POSIX monotonic clock is used.
559 */
560LIBVLC_API
561int64_t libvlc_clock(void);
562
563/**
564 * Return the delay (in microseconds) until a certain timestamp.
565 * \param pts timestamp
566 * \return negative if timestamp is in the past,
567 * positive if it is in the future
568 */
569static inline int64_t libvlc_delay(int64_t pts)
570{
571 return pts - libvlc_clock();
572}
573
574/** @} */
575
576# ifdef __cplusplus
577}
578# endif
579
580#endif /** @} */
581

source code of include/vlc/libvlc.h