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
61 extern "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 */
77 typedef struct libvlc_instance_t libvlc_instance_t;
78 
79 typedef 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  */
93 LIBVLC_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  */
100 LIBVLC_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  */
109 LIBVLC_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  */
118 LIBVLC_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  */
183 LIBVLC_API libvlc_instance_t *
184 libvlc_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  */
192 LIBVLC_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  */
200 LIBVLC_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  */
209 LIBVLC_API
210 int 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  */
229 LIBVLC_API
230 void 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  */
242 LIBVLC_API
243 void 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  */
256 LIBVLC_API
257 void 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  */
267 LIBVLC_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  */
276 LIBVLC_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  */
285 LIBVLC_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  */
294 LIBVLC_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  */
311 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
312 
313 struct libvlc_event_t;
314 
315 /**
316  * Type of a LibVLC event.
317  */
318 typedef int libvlc_event_type_t;
319 
320 /**
321  * Callback function notification
322  * \param p_event the event triggering the callback
323  */
324 typedef 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  */
337 LIBVLC_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  */
350 LIBVLC_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  */
360 LIBVLC_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  */
374 enum 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 
382 typedef 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  */
404 LIBVLC_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  */
432 LIBVLC_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  */
447 typedef 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  */
463 LIBVLC_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  */
482 LIBVLC_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  */
493 LIBVLC_API void libvlc_log_set_file( libvlc_instance_t *p_instance, FILE *stream );
494 
495 /** @} */
496 
497 /**
498  * Description of a module.
499  */
500 typedef 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  */
514 LIBVLC_API
515 void 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  */
528 LIBVLC_API
529 libvlc_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  */
542 LIBVLC_API
543 libvlc_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  */
560 LIBVLC_API
561 int64_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  */
libvlc_delay(int64_t pts)569 static 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