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