4f27ad9f4cd0a801ad171159534372637fb3c844
[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 <vlc/libvlc_structures.h>
62
63 /*****************************************************************************
64  * Exception handling
65  *****************************************************************************/
66 /** \defgroup libvlc_exception libvlc_exception
67  * \ingroup libvlc_core
68  * LibVLC Exceptions handling
69  * @{
70  */
71
72 /**
73  * Initialize an exception structure. This can be called several times to
74  * reuse an exception structure.
75  *
76  * \param p_exception the exception to initialize
77  */
78 VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
79
80 /**
81  * Has an exception been raised?
82  *
83  * \param p_exception the exception to query
84  * \return 0 if the exception was raised, 1 otherwise
85  */
86 VLC_PUBLIC_API int
87 libvlc_exception_raised( const libvlc_exception_t *p_exception );
88
89 /**
90  * Raise an exception using a user-provided message.
91  *
92  * \param p_exception the exception to raise
93  * \param psz_format the exception message format string
94  * \param ... the format string arguments
95  */
96 VLC_PUBLIC_API void
97 libvlc_exception_raise( libvlc_exception_t *p_exception,
98                         const char *psz_format, ... );
99
100 /**
101  * Clear an exception object so it can be reused.
102  * The exception object must have be initialized.
103  *
104  * \param p_exception the exception to clear
105  */
106 VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
107
108 /**
109  * Get an exception's message.
110  *
111  * \param p_exception the exception to query
112  * \return the exception message or NULL if not applicable (exception not
113  *         raised, for example)
114  */
115 VLC_PUBLIC_API const char *
116 libvlc_exception_get_message( const libvlc_exception_t *p_exception );
117
118 /**@} */
119
120 /*****************************************************************************
121  * Core handling
122  *****************************************************************************/
123
124 /** \defgroup libvlc_core libvlc_core
125  * \ingroup libvlc
126  * LibVLC Core
127  * @{
128  */
129
130 /**
131  * Create and initialize a libvlc instance.
132  *
133  * \param argc the number of arguments
134  * \param argv command-line-type arguments. argv[0] must be the path of the
135  *        calling program.
136  * \param p_e an initialized exception pointer
137  * \return the libvlc instance
138  */
139 VLC_PUBLIC_API libvlc_instance_t *
140 libvlc_new( int , const char *const *, libvlc_exception_t *);
141
142 /**
143  * Decrement the reference count of a libvlc instance, and destroy it
144  * if it reaches zero.
145  *
146  * \param p_instance the instance to destroy
147  */
148 VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
149
150 /**
151  * Increments the reference count of a libvlc instance.
152  * The initial reference count is 1 after libvlc_new() returns.
153  *
154  * \param p_instance the instance to reference
155  */
156 VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
157
158 /**
159  * Try to start a user interface for the libvlc instance.
160  *
161  * \param p_instance the instance
162  * \param name interface name, or NULL for default
163  * \param p_exception an initialized exception pointer
164  * \return 0 on success, -1 on error.
165  */
166 VLC_PUBLIC_API
167 int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name,
168                      libvlc_exception_t *p_exception );
169
170 /**
171  * Waits until an interface causes the instance to exit.
172  * You should start at least one interface first, using libvlc_add_intf().
173  *
174  * \param p_instance the instance
175  */
176 VLC_PUBLIC_API
177 void libvlc_wait( libvlc_instance_t *p_instance );
178
179 /**
180  * Retrieve libvlc version.
181  *
182  * Example: "0.9.0-git Grishenko"
183  *
184  * \return a string containing the libvlc version
185  */
186 VLC_PUBLIC_API const char * libvlc_get_version(void);
187
188 /**
189  * Retrieve libvlc compiler version.
190  *
191  * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
192  *
193  * \return a string containing the libvlc compiler version
194  */
195 VLC_PUBLIC_API const char * libvlc_get_compiler(void);
196
197 /**
198  * Retrieve libvlc changeset.
199  *
200  * Example: "aa9bce0bc4"
201  *
202  * \return a string containing the libvlc changeset
203  */
204 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
205
206 struct vlc_object_t;
207
208 /**
209  * Get the internal main VLC object.
210  * Use of this function is usually a hack and should be avoided.
211  * @note
212  * You will need to link with libvlccore to make any use of the underlying VLC
213  * object. The libvlccore programming and binary interfaces are not stable.
214  * @warning
215  * Remember to release the object with vlc_object_release().
216  *
217  * \param p_instance the libvlc instance
218  * @return a VLC object of type "libvlc"
219  */
220 VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *p_instance);
221
222 /**
223  * Frees an heap allocation (char *) returned by a LibVLC API.
224  * If you know you're using the same underlying C run-time as the LibVLC
225  * implementation, then you can call ANSI C free() directly instead.
226  */
227 VLC_PUBLIC_API void libvlc_free( void *ptr );
228
229 /** @}*/
230
231 /*****************************************************************************
232  * Event handling
233  *****************************************************************************/
234
235 /** \defgroup libvlc_event libvlc_event
236  * \ingroup libvlc_core
237  * LibVLC Events
238  * @{
239  */
240
241 /**
242  * Event manager that belongs to a libvlc object, and from whom events can
243  * be received.
244  */
245
246 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
247 typedef struct libvlc_event_t libvlc_event_t;
248 typedef uint32_t libvlc_event_type_t;
249     
250 /**
251  * Callback function notification
252  * \param p_event the event triggering the callback
253  */
254
255 typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
256     
257 /**
258  * Register for an event notification.
259  *
260  * \param p_event_manager the event manager to which you want to attach to.
261  *        Generally it is obtained by vlc_my_object_event_manager() where
262  *        my_object is the object you want to listen to.
263  * \param i_event_type the desired event to which we want to listen
264  * \param f_callback the function to call when i_event_type occurs
265  * \param user_data user provided data to carry with the event
266  * \param p_e an initialized exception pointer
267  */
268 VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
269                                          libvlc_event_type_t i_event_type,
270                                          libvlc_callback_t f_callback,
271                                          void *user_data,
272                                          libvlc_exception_t *p_e );
273
274 /**
275  * Unregister an event notification.
276  *
277  * \param p_event_manager the event manager
278  * \param i_event_type the desired event to which we want to unregister
279  * \param f_callback the function to call when i_event_type occurs
280  * \param p_user_data user provided data to carry with the event
281  * \param p_e an initialized exception pointer
282  */
283 VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
284                                          libvlc_event_type_t i_event_type,
285                                          libvlc_callback_t f_callback,
286                                          void *p_user_data,
287                                          libvlc_exception_t *p_e );
288
289 /**
290  * Get an event's type name.
291  *
292  * \param i_event_type the desired event
293  */
294 VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
295
296 /** @} */
297
298 /*****************************************************************************
299  * Message log handling
300  *****************************************************************************/
301
302 /** \defgroup libvlc_log libvlc_log
303  * \ingroup libvlc_core
304  * LibVLC Message Logging
305  * @{
306  */
307
308 /**
309  * Return the VLC messaging verbosity level.
310  *
311  * \param p_instance libvlc instance
312  * \return verbosity level for messages
313  */
314 VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
315
316 /**
317  * Set the VLC messaging verbosity level.
318  *
319  * \param p_instance libvlc log instance
320  * \param level log level
321  */
322 VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
323
324 /**
325  * Open a VLC message log instance.
326  *
327  * \param p_instance libvlc instance
328  * \param p_e an initialized exception pointer
329  * \return log message instance
330  */
331 VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *);
332
333 /**
334  * Close a VLC message log instance.
335  *
336  * \param p_log libvlc log instance or NULL
337  */
338 VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );
339
340 /**
341  * Returns the number of messages in a log instance.
342  *
343  * \param p_log libvlc log instance or NULL
344  * \param p_e an initialized exception pointer
345  * \return number of log messages, 0 if p_log is NULL
346  */
347 VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
348
349 /**
350  * Clear a log instance.
351  *
352  * All messages in the log are removed. The log should be cleared on a
353  * regular basis to avoid clogging.
354  *
355  * \param p_log libvlc log instance or NULL
356  */
357 VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );
358
359 /**
360  * Allocate and returns a new iterator to messages in log.
361  *
362  * \param p_log libvlc log instance
363  * \param p_e an initialized exception pointer
364  * \return log iterator object
365  */
366 VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
367
368 /**
369  * Release a previoulsy allocated iterator.
370  *
371  * \param p_iter libvlc log iterator or NULL
372  */
373 VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
374
375 /**
376  * Return whether log iterator has more messages.
377  *
378  * \param p_iter libvlc log iterator or NULL
379  * \return true if iterator has more message objects, else false
380  */
381 VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
382
383 /**
384  * Return the next log message.
385  *
386  * The message contents must not be freed
387  *
388  * \param p_iter libvlc log iterator or NULL
389  * \param p_buffer log buffer
390  * \param p_e an initialized exception pointer
391  * \return log message object
392  */
393 VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
394                                                                libvlc_log_message_t *p_buffer,
395                                                                libvlc_exception_t *p_e );
396
397 /** @} */
398
399 # ifdef __cplusplus
400 }
401 # endif
402
403 #endif /* <vlc/libvlc.h> */