f4663eb28fe15e0bf38a1d40fd8aebe5b3135587
[vlc.git] / include / vlc / libvlc.h
1 /*****************************************************************************
2  * libvlc.h:  libvlc external API
3  *****************************************************************************
4  * Copyright (C) 1998-2009 the VideoLAN team
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
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 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 General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, 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  * This is libvlc, the base library of the VLC program.
34  *
35  * @{
36  */
37
38 #ifndef VLC_LIBVLC_H
39 #define VLC_LIBVLC_H 1
40
41 #if defined (WIN32) && defined (DLL_EXPORT)
42 # define VLC_PUBLIC_API __declspec(dllexport)
43 #else
44 # define VLC_PUBLIC_API
45 #endif
46
47 #ifdef __LIBVLC__
48 /* Avoid unuseful warnings from libvlc with our deprecated APIs */
49 #   define VLC_DEPRECATED_API VLC_PUBLIC_API
50 #elif defined(__GNUC__) && \
51       (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
52 # define VLC_DEPRECATED_API VLC_PUBLIC_API __attribute__((deprecated))
53 #else
54 # define VLC_DEPRECATED_API VLC_PUBLIC_API
55 #endif
56
57 # ifdef __cplusplus
58 extern "C" {
59 # endif
60
61 #include <stdarg.h>
62 #include <vlc/libvlc_structures.h>
63
64 /*****************************************************************************
65  * Exception handling
66  *****************************************************************************/
67 /** \defgroup libvlc_exception libvlc_exception
68  * \ingroup libvlc_core
69  * LibVLC Exceptions handling
70  * @{
71  */
72
73 /**
74  * Initialize an exception structure. This can be called several times to
75  * reuse an exception structure.
76  *
77  * \param p_exception the exception to initialize
78  */
79 VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
80
81 /**
82  * Has an exception been raised?
83  *
84  * \param p_exception the exception to query
85  * \return 0 if the exception was raised, 1 otherwise
86  */
87 VLC_PUBLIC_API int
88 libvlc_exception_raised( const libvlc_exception_t *p_exception );
89
90 /**
91  * Raise an exception using a user-provided message.
92  *
93  * \param p_exception the exception to raise
94  * \param psz_format the exception message format string
95  * \param ... the format string arguments
96  */
97 VLC_PUBLIC_API void
98 libvlc_exception_raise( libvlc_exception_t *p_exception,
99                         const char *psz_format, ... );
100
101 /**
102  * Clear an exception object so it can be reused.
103  * The exception object must have be initialized.
104  *
105  * \param p_exception the exception to clear
106  */
107 VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
108
109 /**
110  * Get an exception's message.
111  *
112  * \param p_exception the exception to query
113  * \return the exception message or NULL if not applicable (exception not
114  *         raised, for example)
115  */
116 VLC_PUBLIC_API const char *
117 libvlc_exception_get_message( const libvlc_exception_t *p_exception );
118
119 /**@} */
120
121 /*****************************************************************************
122  * Error handling
123  *****************************************************************************/
124 /** \defgroup libvlc_error libvlc_error
125  * \ingroup libvlc_core
126  * LibVLC error handling
127  * @{
128  */
129
130 /**
131  * A human-readable error message for the last LibVLC error in the calling
132  * thread. The resulting string is valid until another error occurs (at least
133  * until the next LibVLC call).
134  *
135  * @warning
136  * This will be NULL if there was no error.
137  */
138 const char *libvlc_errmsg (void);
139
140 /**
141  * Clears the LibVLC error status for the current thread. This is optional.
142  * By default, the error status is automatically overriden when a new error
143  * occurs, and destroyed when the thread exits.
144  */
145 void libvlc_clearerr (void);
146
147 /**
148  * Sets the LibVLC error status and message for the current thread.
149  * Any previous error is overriden.
150  * @return a nul terminated string in any case
151  */
152 const char *libvlc_vprinterr (const char *fmt, va_list ap);
153
154 /**
155  * Sets the LibVLC error status and message for the current thread.
156  * Any previous error is overriden.
157  * @return a nul terminated string in any case
158  */
159 const char *libvlc_printerr (const char *fmt, ...);
160
161 /**@} */
162
163
164 /*****************************************************************************
165  * Core handling
166  *****************************************************************************/
167
168 /** \defgroup libvlc_core libvlc_core
169  * \ingroup libvlc
170  * LibVLC Core
171  * @{
172  */
173
174 /**
175  * Create and initialize a libvlc instance.
176  *
177  * \param argc the number of arguments
178  * \param argv command-line-type arguments. argv[0] must be the path of the
179  *        calling program.
180  * \param p_e an initialized exception pointer
181  * \return the libvlc instance
182  */
183 VLC_PUBLIC_API libvlc_instance_t *
184 libvlc_new( int , const char *const *, libvlc_exception_t *);
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 VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
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 VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
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  * \param p_exception an initialized exception pointer
208  * \return 0 on success, -1 on error.
209  */
210 VLC_PUBLIC_API
211 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name,
212                      libvlc_exception_t *p_exception );
213
214 /**
215  * Waits until an interface causes the instance to exit.
216  * You should start at least one interface first, using libvlc_add_intf().
217  *
218  * \param p_instance the instance
219  */
220 VLC_PUBLIC_API
221 void libvlc_wait( libvlc_instance_t *p_instance );
222
223 /**
224  * Retrieve libvlc version.
225  *
226  * Example: "0.9.0-git Grishenko"
227  *
228  * \return a string containing the libvlc version
229  */
230 VLC_PUBLIC_API const char * libvlc_get_version(void);
231
232 /**
233  * Retrieve libvlc compiler version.
234  *
235  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
236  *
237  * \return a string containing the libvlc compiler version
238  */
239 VLC_PUBLIC_API const char * libvlc_get_compiler(void);
240
241 /**
242  * Retrieve libvlc changeset.
243  *
244  * Example: "aa9bce0bc4"
245  *
246  * \return a string containing the libvlc changeset
247  */
248 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
249
250 struct vlc_object_t;
251
252 /**
253  * Get the internal main VLC object.
254  * Use of this function is usually a hack and should be avoided.
255  * @note
256  * You will need to link with libvlccore to make any use of the underlying VLC
257  * object. The libvlccore programming and binary interfaces are not stable.
258  * @warning
259  * Remember to release the object with vlc_object_release().
260  *
261  * \param p_instance the libvlc instance
262  * @return a VLC object of type "libvlc"
263  */
264 VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *p_instance);
265
266 /**
267  * Frees an heap allocation (char *) returned by a LibVLC API.
268  * If you know you're using the same underlying C run-time as the LibVLC
269  * implementation, then you can call ANSI C free() directly instead.
270  */
271 VLC_PUBLIC_API void libvlc_free( void *ptr );
272
273 /** @}*/
274
275 /*****************************************************************************
276  * Event handling
277  *****************************************************************************/
278
279 /** \defgroup libvlc_event libvlc_event
280  * \ingroup libvlc_core
281  * LibVLC Events
282  * @{
283  */
284
285 /**
286  * Event manager that belongs to a libvlc object, and from whom events can
287  * be received.
288  */
289
290 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
291 typedef struct libvlc_event_t libvlc_event_t;
292 typedef uint32_t libvlc_event_type_t;
293     
294 /**
295  * Callback function notification
296  * \param p_event the event triggering the callback
297  */
298
299 typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
300     
301 /**
302  * Register for an event notification.
303  *
304  * \param p_event_manager the event manager to which you want to attach to.
305  *        Generally it is obtained by vlc_my_object_event_manager() where
306  *        my_object is the object you want to listen to.
307  * \param i_event_type the desired event to which we want to listen
308  * \param f_callback the function to call when i_event_type occurs
309  * \param user_data user provided data to carry with the event
310  * \param p_e an initialized exception pointer
311  */
312 VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
313                                          libvlc_event_type_t i_event_type,
314                                          libvlc_callback_t f_callback,
315                                          void *user_data,
316                                          libvlc_exception_t *p_e );
317
318 /**
319  * Unregister an event notification.
320  *
321  * \param p_event_manager the event manager
322  * \param i_event_type the desired event to which we want to unregister
323  * \param f_callback the function to call when i_event_type occurs
324  * \param p_user_data user provided data to carry with the event
325  * \param p_e an initialized exception pointer
326  */
327 VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
328                                          libvlc_event_type_t i_event_type,
329                                          libvlc_callback_t f_callback,
330                                          void *p_user_data,
331                                          libvlc_exception_t *p_e );
332
333 /**
334  * Get an event's type name.
335  *
336  * \param i_event_type the desired event
337  */
338 VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
339
340 /** @} */
341
342 /*****************************************************************************
343  * Message log handling
344  *****************************************************************************/
345
346 /** \defgroup libvlc_log libvlc_log
347  * \ingroup libvlc_core
348  * LibVLC Message Logging
349  * @{
350  */
351
352 /**
353  * Return the VLC messaging verbosity level.
354  *
355  * \param p_instance libvlc instance
356  * \return verbosity level for messages
357  */
358 VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
359
360 /**
361  * Set the VLC messaging verbosity level.
362  *
363  * \param p_instance libvlc log instance
364  * \param level log level
365  */
366 VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
367
368 /**
369  * Open a VLC message log instance.
370  *
371  * \param p_instance libvlc instance
372  * \param p_e an initialized exception pointer
373  * \return log message instance
374  */
375 VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *);
376
377 /**
378  * Close a VLC message log instance.
379  *
380  * \param p_log libvlc log instance or NULL
381  */
382 VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );
383
384 /**
385  * Returns the number of messages in a log instance.
386  *
387  * \param p_log libvlc log instance or NULL
388  * \param p_e an initialized exception pointer
389  * \return number of log messages, 0 if p_log is NULL
390  */
391 VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
392
393 /**
394  * Clear a log instance.
395  *
396  * All messages in the log are removed. The log should be cleared on a
397  * regular basis to avoid clogging.
398  *
399  * \param p_log libvlc log instance or NULL
400  */
401 VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );
402
403 /**
404  * Allocate and returns a new iterator to messages in log.
405  *
406  * \param p_log libvlc log instance
407  * \param p_e an initialized exception pointer
408  * \return log iterator object
409  */
410 VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
411
412 /**
413  * Release a previoulsy allocated iterator.
414  *
415  * \param p_iter libvlc log iterator or NULL
416  */
417 VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
418
419 /**
420  * Return whether log iterator has more messages.
421  *
422  * \param p_iter libvlc log iterator or NULL
423  * \return true if iterator has more message objects, else false
424  */
425 VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
426
427 /**
428  * Return the next log message.
429  *
430  * The message contents must not be freed
431  *
432  * \param p_iter libvlc log iterator or NULL
433  * \param p_buffer log buffer
434  * \param p_e an initialized exception pointer
435  * \return log message object
436  */
437 VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
438                                                                libvlc_log_message_t *p_buffer,
439                                                                libvlc_exception_t *p_e );
440
441 /** @} */
442
443 # ifdef __cplusplus
444 }
445 # endif
446
447 #endif /* <vlc/libvlc.h> */