LGPL
[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  * \file
28  * This file defines libvlc external API
29  */
30
31 /**
32  * \defgroup libvlc LibVLC
33  * LibVLC is the external programming interface of the VLC media player.
34  * It is used to embed VLC into other applications or frameworks.
35  * @{
36  */
37
38 #ifndef VLC_LIBVLC_H
39 #define VLC_LIBVLC_H 1
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 #endif
48
49 #ifdef __LIBVLC__
50 /* Avoid unuseful warnings from libvlc with our deprecated APIs */
51 #   define LIBVLC_DEPRECATED LIBVLC_API
52 #elif defined(__GNUC__) && \
53       (__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
58
59 # ifdef __cplusplus
60 extern "C" {
61 # endif
62
63 #include <stdarg.h>
64 #include <vlc/libvlc_structures.h>
65
66 /** \defgroup libvlc_core LibVLC core
67  * \ingroup libvlc
68  * Before it can do anything useful, LibVLC must be initialized.
69  * You can create one (or more) instance(s) of LibVLC in a given process,
70  * with libvlc_new() and destroy them with libvlc_release().
71  *
72  * \version Unless otherwise stated, these functions are available
73  * from LibVLC versions numbered 1.1.0 or more.
74  * 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  * A human-readable error message for the last LibVLC error in the calling
84  * thread. The resulting string is valid until another error occurs (at least
85  * until the next LibVLC call).
86  *
87  * @warning
88  * This will be NULL if there was no error.
89  */
90 LIBVLC_API const char *libvlc_errmsg (void);
91
92 /**
93  * Clears the LibVLC error status for the current thread. This is optional.
94  * By default, the error status is automatically overridden when a new error
95  * occurs, and destroyed when the thread exits.
96  */
97 LIBVLC_API void libvlc_clearerr (void);
98
99 /**
100  * Sets the LibVLC error status and message for the current thread.
101  * Any previous error is overridden.
102  * \return a nul terminated string in any case
103  */
104 const char *libvlc_vprinterr (const char *fmt, va_list ap);
105
106 /**
107  * Sets the LibVLC error status and message for the current thread.
108  * Any previous error is overridden.
109  * \return a nul terminated string in any case
110  */
111 const char *libvlc_printerr (const char *fmt, ...);
112
113 /**@} */
114
115 /**
116  * Create and initialize a libvlc instance.
117  * This functions accept a list of "command line" arguments similar to the
118  * main(). These arguments affect the LibVLC instance default configuration.
119  *
120  * \version
121  * Arguments are meant to be passed from the command line to LibVLC, just like
122  * VLC media player does. The list of valid arguments depends on the LibVLC
123  * version, the operating system and platform, and set of available LibVLC
124  * plugins. Invalid or unsupported arguments will cause the function to fail
125  * (i.e. return NULL). Also, some arguments may alter the behaviour or
126  * otherwise interfere with other LibVLC functions.
127  *
128  * \warning
129  * There is absolutely no warranty or promise of forward, backward and
130  * cross-platform compatibility with regards to libvlc_new() arguments.
131  * We recommend that you do not use them, other than when debugging.
132  *
133  * \param argc the number of arguments (should be 0)
134  * \param argv list of arguments (should be NULL)
135  * \return the libvlc instance or NULL in case of error
136  */
137 LIBVLC_API libvlc_instance_t *
138 libvlc_new( int argc , const char *const *argv );
139
140 /**
141  * Decrement the reference count of a libvlc instance, and destroy it
142  * if it reaches zero.
143  *
144  * \param p_instance the instance to destroy
145  */
146 LIBVLC_API void libvlc_release( libvlc_instance_t *p_instance );
147
148 /**
149  * Increments the reference count of a libvlc instance.
150  * The initial reference count is 1 after libvlc_new() returns.
151  *
152  * \param p_instance the instance to reference
153  */
154 LIBVLC_API void libvlc_retain( libvlc_instance_t *p_instance );
155
156 /**
157  * Try to start a user interface for the libvlc instance.
158  *
159  * \param p_instance the instance
160  * \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  * Registers a callback for the LibVLC exit event. This is mostly useful if
168  * you have started at least one interface with libvlc_add_intf().
169  * Typically, this function will wake up your application main loop (from
170  * another thread).
171  *
172  * \param p_instance LibVLC instance
173  * \param cb callback to invoke when LibVLC wants to exit
174  * \param opaque data pointer for the callback
175  * \warning This function and libvlc_wait() cannot be used at the same time.
176  * Use either or none of them but not both.
177  */
178 LIBVLC_API
179 void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
180                               void (*cb) (void *), void *opaque );
181
182 /**
183  * Waits until an interface causes the instance to exit.
184  * You should start at least one interface first, using libvlc_add_intf().
185  *
186  * \param p_instance the instance
187  */
188 LIBVLC_API
189 void libvlc_wait( libvlc_instance_t *p_instance );
190
191 /**
192  * Sets the application name. LibVLC passes this as the user agent string
193  * when a protocol requires it.
194  *
195  * \param p_instance LibVLC instance
196  * \param name human-readable application name, e.g. "FooBar player 1.2.3"
197  * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
198  * \version LibVLC 1.1.1 or later
199  */
200 LIBVLC_API
201 void libvlc_set_user_agent( libvlc_instance_t *p_instance,
202                             const char *name, const char *http );
203
204 /**
205  * Retrieve libvlc version.
206  *
207  * Example: "1.1.0-git The Luggage"
208  *
209  * \return a string containing the libvlc version
210  */
211 LIBVLC_API const char * libvlc_get_version(void);
212
213 /**
214  * Retrieve libvlc compiler version.
215  *
216  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
217  *
218  * \return a string containing the libvlc compiler version
219  */
220 LIBVLC_API const char * libvlc_get_compiler(void);
221
222 /**
223  * Retrieve libvlc changeset.
224  *
225  * Example: "aa9bce0bc4"
226  *
227  * \return a string containing the libvlc changeset
228  */
229 LIBVLC_API const char * libvlc_get_changeset(void);
230
231 /**
232  * Frees an heap allocation returned by a LibVLC function.
233  * If you know you're using the same underlying C run-time as the LibVLC
234  * implementation, then you can call ANSI C free() directly instead.
235  *
236  * \param ptr the pointer
237  */
238 LIBVLC_API void libvlc_free( void *ptr );
239
240 /** \defgroup libvlc_event LibVLC asynchronous events
241  * LibVLC emits asynchronous events.
242  *
243  * Several LibVLC objects (such @ref libvlc_instance_t as
244  * @ref libvlc_media_player_t) generate events asynchronously. Each of them
245  * provides @ref libvlc_event_manager_t event manager. You can subscribe to
246  * events with libvlc_event_attach() and unsubscribe with
247  * libvlc_event_detach().
248  * @{
249  */
250
251 /**
252  * Event manager that belongs to a libvlc object, and from whom events can
253  * be received.
254  */
255 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
256
257 struct libvlc_event_t;
258
259 /**
260  * Type of a LibVLC event.
261  */
262 typedef int libvlc_event_type_t;
263
264 /**
265  * Callback function notification
266  * \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  * \param p_event_manager the event manager to which you want to attach to.
274  *        Generally it is obtained by vlc_my_object_event_manager() where
275  *        my_object is the object you want to listen to.
276  * \param i_event_type the desired event to which we want to listen
277  * \param f_callback the function to call when i_event_type occurs
278  * \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                                         libvlc_event_type_t i_event_type,
283                                         libvlc_callback_t f_callback,
284                                         void *user_data );
285
286 /**
287  * Unregister an event notification.
288  *
289  * \param p_event_manager the event manager
290  * \param i_event_type the desired event to which we want to unregister
291  * \param f_callback the function to call when i_event_type occurs
292  * \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                                          libvlc_event_type_t i_event_type,
296                                          libvlc_callback_t f_callback,
297                                          void *p_user_data );
298
299 /**
300  * Get an event's type name.
301  *
302  * \param event_type the desired event
303  */
304 LIBVLC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
305
306 /** @} */
307
308 /** \defgroup libvlc_log LibVLC logging
309  * libvlc_log_* functions provide access to the LibVLC messages log.
310  * This is used for debugging or by advanced users.
311  * @{
312  */
313
314 /**
315  * Always returns minus one.
316  * This function is only provided for backward compatibility.
317  *
318  * \param p_instance ignored
319  * \return always -1
320  */
321 LIBVLC_DEPRECATED
322 LIBVLC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
323
324 /**
325  * This function does nothing.
326  * It is only provided for backward compatibility.
327  *
328  * \param p_instance ignored
329  * \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  * This function does nothing useful.
336  * It is only provided for backward compatibility.
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().
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  * Always returns zero.
354  * This function is only provided for backward compatibility.
355  *
356  * \param p_log ignored
357  * \return always zero
358  */
359 LIBVLC_DEPRECATED
360 LIBVLC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
361
362 /**
363  * This function does nothing.
364  * It is only provided for backward compatibility.
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  * This function does nothing useful.
373  * It is only provided for backward compatibility.
374  *
375  * \param p_log ignored
376  * \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().
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  * Always returns zero.
391  * This function is only provided for backward compatibility.
392  *
393  * \param p_iter ignored
394  * \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  * Always returns NULL.
401  * This function is only provided for backward compatibility.
402  *
403  * \param p_iter libvlc log iterator or NULL
404  * \param p_buffer ignored
405  * \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  * Description of a module.
415  */
416 typedef struct libvlc_module_description_t
417 {
418     char *psz_name;
419     char *psz_shortname;
420     char *psz_longname;
421     char *psz_help;
422     struct libvlc_module_description_t *p_next;
423 } libvlc_module_description_t;
424
425 /**
426  * Release a list of module descriptions.
427  *
428  * \param p_list the list to be released
429  */
430 LIBVLC_API
431 void libvlc_module_description_list_release( libvlc_module_description_t *p_list );
432
433 /**
434  * Returns a list of audio filters that are available.
435  *
436  * \param p_instance libvlc instance
437  *
438  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
439  *         In case of an error, NULL is returned.
440  *
441  * \see libvlc_module_description_t
442  * \see libvlc_module_description_list_release
443  */
444 LIBVLC_API
445 libvlc_module_description_t *libvlc_audio_filter_list_get( libvlc_instance_t *p_instance );
446
447 /**
448  * Returns a list of video filters that are available.
449  *
450  * \param p_instance libvlc instance
451  *
452  * \return a list of module descriptions. It should be freed with libvlc_module_description_list_release().
453  *         In case of an error, NULL is returned.
454  *
455  * \see libvlc_module_description_t
456  * \see libvlc_module_description_list_release
457  */
458 LIBVLC_API
459 libvlc_module_description_t *libvlc_video_filter_list_get( libvlc_instance_t *p_instance );
460
461 /** @} */
462
463 /** \defgroup libvlc_clock LibVLC time
464  * These functions provide access to the LibVLC time/clock.
465  * @{
466  */
467
468 /**
469  * Return the current time as defined by LibVLC. The unit is the microsecond.
470  * Time increases monotonically (regardless of time zone changes and RTC
471  * adjustements).
472  * The origin is arbitrary but consistent across the whole system
473  * (e.g. the system uptim, the time since the system was booted).
474  * \note On systems that support it, the POSIX monotonic clock is used.
475  */
476 LIBVLC_API
477 int64_t libvlc_clock(void);
478
479 /**
480  * Return the delay (in microseconds) until a certain timestamp.
481  * \param pts timestamp
482  * \return negative if timestamp is in the past,
483  * positive if it is in the future
484  */
485 static inline int64_t libvlc_delay(int64_t pts)
486 {
487     return pts - libvlc_clock();
488 }
489
490 /** @} */
491
492 # ifdef __cplusplus
493 }
494 # endif
495
496 #endif /* <vlc/libvlc.h> */