libvlc.h 12.6 KB
Newer Older
1
/*****************************************************************************
2
 * libvlc.h:  libvlc external API
3
 *****************************************************************************
4
 * Copyright (C) 1998-2009 the VideoLAN team
Pierre's avatar
Pierre committed
5
 * $Id$
6
 *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
7
 * Authors: Clément Stenac <zorglub@videolan.org>
8
 *          Jean-Paul Saman <jpsaman@videolan.org>
9
 *          Pierre d'Herbemont <pdherbemont@videolan.org>
10 11 12 13 14 15 16 17 18 19 20 21 22
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
Antoine Cellerier's avatar
Antoine Cellerier committed
23
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 25
 *****************************************************************************/

26 27 28 29 30
/**
 * \file
 * This file defines libvlc external API
 */

31
/**
32
 * \defgroup libvlc libvlc
33 34 35 36 37
 * This is libvlc, the base library of the VLC program.
 *
 * @{
 */

38 39
#ifndef VLC_LIBVLC_H
#define VLC_LIBVLC_H 1
40

41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
#if defined (WIN32) && defined (DLL_EXPORT)
# define VLC_PUBLIC_API __declspec(dllexport)
#else
# define VLC_PUBLIC_API
#endif

#ifdef __LIBVLC__
/* Avoid unuseful warnings from libvlc with our deprecated APIs */
#   define VLC_DEPRECATED_API VLC_PUBLIC_API
#elif defined(__GNUC__) && \
      (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
# define VLC_DEPRECATED_API VLC_PUBLIC_API __attribute__((deprecated))
#else
# define VLC_DEPRECATED_API VLC_PUBLIC_API
#endif
56 57 58 59 60

# ifdef __cplusplus
extern "C" {
# endif

61
#include <stdarg.h>
62 63
#include <vlc/libvlc_structures.h>

64 65 66
/*****************************************************************************
 * Exception handling
 *****************************************************************************/
67
/** \defgroup libvlc_exception libvlc_exception
68
 * \ingroup libvlc_core
69 70 71 72 73
 * LibVLC Exceptions handling
 * @{
 */

/**
Sam Hocevar's avatar
Sam Hocevar committed
74 75 76
 * Initialize an exception structure. This can be called several times to
 * reuse an exception structure.
 *
77 78
 * \param p_exception the exception to initialize
 */
79
VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
80 81

/**
Sam Hocevar's avatar
Sam Hocevar committed
82 83
 * Has an exception been raised?
 *
84
 * \param p_exception the exception to query
Sam Hocevar's avatar
Sam Hocevar committed
85
 * \return 0 if the exception was raised, 1 otherwise
86
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
87 88
VLC_PUBLIC_API int
libvlc_exception_raised( const libvlc_exception_t *p_exception );
89 90

/**
91
 * Raise an exception.
Sam Hocevar's avatar
Sam Hocevar committed
92
 *
93 94
 * \param p_exception the exception to raise
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
95
VLC_PUBLIC_API void
96
libvlc_exception_raise( libvlc_exception_t *p_exception );
97

98 99
/**
 * Clear an exception object so it can be reused.
Sam Hocevar's avatar
Sam Hocevar committed
100 101
 * The exception object must have be initialized.
 *
102 103
 * \param p_exception the exception to clear
 */
104
VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
105

Clément Stenac's avatar
Clément Stenac committed
106
/**@} */
107

108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
/*****************************************************************************
 * Error handling
 *****************************************************************************/
/** \defgroup libvlc_error libvlc_error
 * \ingroup libvlc_core
 * LibVLC error handling
 * @{
 */

/**
 * A human-readable error message for the last LibVLC error in the calling
 * thread. The resulting string is valid until another error occurs (at least
 * until the next LibVLC call).
 *
 * @warning
 * This will be NULL if there was no error.
 */
125
VLC_PUBLIC_API const char *libvlc_errmsg (void);
126 127 128 129 130 131

/**
 * Clears the LibVLC error status for the current thread. This is optional.
 * By default, the error status is automatically overriden when a new error
 * occurs, and destroyed when the thread exits.
 */
132
VLC_PUBLIC_API void libvlc_clearerr (void);
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150

/**
 * Sets the LibVLC error status and message for the current thread.
 * Any previous error is overriden.
 * @return a nul terminated string in any case
 */
const char *libvlc_vprinterr (const char *fmt, va_list ap);

/**
 * Sets the LibVLC error status and message for the current thread.
 * Any previous error is overriden.
 * @return a nul terminated string in any case
 */
const char *libvlc_printerr (const char *fmt, ...);

/**@} */


151 152 153 154
/*****************************************************************************
 * Core handling
 *****************************************************************************/

155
/** \defgroup libvlc_core libvlc_core
156 157 158 159 160 161
 * \ingroup libvlc
 * LibVLC Core
 * @{
 */

/**
Sam Hocevar's avatar
Sam Hocevar committed
162 163
 * Create and initialize a libvlc instance.
 *
164
 * \param argc the number of arguments
Sam Hocevar's avatar
Sam Hocevar committed
165 166 167 168
 * \param argv command-line-type arguments. argv[0] must be the path of the
 *        calling program.
 * \param p_e an initialized exception pointer
 * \return the libvlc instance
169
 */
170 171
VLC_PUBLIC_API libvlc_instance_t *
libvlc_new( int , const char *const *, libvlc_exception_t *);
172 173

/**
Sam Hocevar's avatar
Sam Hocevar committed
174
 * Decrement the reference count of a libvlc instance, and destroy it
175
 * if it reaches zero.
Sam Hocevar's avatar
Sam Hocevar committed
176
 *
177 178
 * \param p_instance the instance to destroy
 */
179
VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
180 181 182

/**
 * Increments the reference count of a libvlc instance.
Sam Hocevar's avatar
Sam Hocevar committed
183 184 185
 * The initial reference count is 1 after libvlc_new() returns.
 *
 * \param p_instance the instance to reference
186 187
 */
VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
188

189
/**
190
 * Try to start a user interface for the libvlc instance.
191 192 193 194
 *
 * \param p_instance the instance
 * \param name interface name, or NULL for default
 * \param p_exception an initialized exception pointer
195
 * \return 0 on success, -1 on error.
196 197
 */
VLC_PUBLIC_API
198 199
int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name,
                     libvlc_exception_t *p_exception );
200

201 202 203 204 205 206 207 208 209
/**
 * Waits until an interface causes the instance to exit.
 * You should start at least one interface first, using libvlc_add_intf().
 *
 * \param p_instance the instance
 */
VLC_PUBLIC_API
void libvlc_wait( libvlc_instance_t *p_instance );

210 211 212 213 214 215 216
/**
 * Retrieve libvlc version.
 *
 * Example: "0.9.0-git Grishenko"
 *
 * \return a string containing the libvlc version
 */
217
VLC_PUBLIC_API const char * libvlc_get_version(void);
218 219 220 221 222 223 224 225

/**
 * Retrieve libvlc compiler version.
 *
 * Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)"
 *
 * \return a string containing the libvlc compiler version
 */
226
VLC_PUBLIC_API const char * libvlc_get_compiler(void);
227 228 229 230 231 232 233 234

/**
 * Retrieve libvlc changeset.
 *
 * Example: "aa9bce0bc4"
 *
 * \return a string containing the libvlc changeset
 */
235
VLC_PUBLIC_API const char * libvlc_get_changeset(void);
236

237 238 239
struct vlc_object_t;

/**
240 241 242 243 244 245 246
 * Get the internal main VLC object.
 * Use of this function is usually a hack and should be avoided.
 * @note
 * You will need to link with libvlccore to make any use of the underlying VLC
 * object. The libvlccore programming and binary interfaces are not stable.
 * @warning
 * Remember to release the object with vlc_object_release().
247 248
 *
 * \param p_instance the libvlc instance
249
 * @return a VLC object of type "libvlc"
250
 */
251
VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *p_instance);
252

253 254 255 256
/**
 * Frees an heap allocation (char *) returned by a LibVLC API.
 * If you know you're using the same underlying C run-time as the LibVLC
 * implementation, then you can call ANSI C free() directly instead.
257 258
 *
 * \param ptr the pointer
259 260 261
 */
VLC_PUBLIC_API void libvlc_free( void *ptr );

262 263
/** @}*/

264
/*****************************************************************************
265
 * Event handling
266 267
 *****************************************************************************/

268 269 270
/** \defgroup libvlc_event libvlc_event
 * \ingroup libvlc_core
 * LibVLC Events
271 272 273
 * @{
 */

274
/**
275 276
 * Event manager that belongs to a libvlc object, and from whom events can
 * be received.
277 278
 */

279 280
typedef struct libvlc_event_manager_t libvlc_event_manager_t;
typedef struct libvlc_event_t libvlc_event_t;
281
typedef uint32_t libvlc_event_type_t;
282
    
283
/**
284 285
 * Callback function notification
 * \param p_event the event triggering the callback
286 287
 */

288 289
typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
    
290
/**
291
 * Register for an event notification.
292
 *
293 294 295 296 297 298
 * \param p_event_manager the event manager to which you want to attach to.
 *        Generally it is obtained by vlc_my_object_event_manager() where
 *        my_object is the object you want to listen to.
 * \param i_event_type the desired event to which we want to listen
 * \param f_callback the function to call when i_event_type occurs
 * \param user_data user provided data to carry with the event
299 300
 * \param p_e an initialized exception pointer
 */
301 302 303 304 305
VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
                                         libvlc_event_type_t i_event_type,
                                         libvlc_callback_t f_callback,
                                         void *user_data,
                                         libvlc_exception_t *p_e );
306 307

/**
308
 * Unregister an event notification.
309
 *
310 311 312 313
 * \param p_event_manager the event manager
 * \param i_event_type the desired event to which we want to unregister
 * \param f_callback the function to call when i_event_type occurs
 * \param p_user_data user provided data to carry with the event
314 315
 * \param p_e an initialized exception pointer
 */
316 317 318 319 320
VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager,
                                         libvlc_event_type_t i_event_type,
                                         libvlc_callback_t f_callback,
                                         void *p_user_data,
                                         libvlc_exception_t *p_e );
321 322

/**
323
 * Get an event's type name.
324
 *
325
 * \param i_event_type the desired event
326
 */
327
VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
328 329 330

/** @} */

331 332 333 334
/*****************************************************************************
 * Message log handling
 *****************************************************************************/

335
/** \defgroup libvlc_log libvlc_log
336
 * \ingroup libvlc_core
337 338 339 340 341
 * LibVLC Message Logging
 * @{
 */

/**
Sam Hocevar's avatar
Sam Hocevar committed
342 343
 * Return the VLC messaging verbosity level.
 *
344
 * \param p_instance libvlc instance
345
 * \return verbosity level for messages
346
 */
347
VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
348 349

/**
Sam Hocevar's avatar
Sam Hocevar committed
350 351
 * Set the VLC messaging verbosity level.
 *
352 353
 * \param p_instance libvlc log instance
 * \param level log level
354
 */
355
VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
356 357

/**
Sam Hocevar's avatar
Sam Hocevar committed
358 359
 * Open a VLC message log instance.
 *
360
 * \param p_instance libvlc instance
361
 * \param p_e an initialized exception pointer
362
 * \return log message instance
363
 */
364
VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *);
365 366

/**
Sam Hocevar's avatar
Sam Hocevar committed
367 368
 * Close a VLC message log instance.
 *
369
 * \param p_log libvlc log instance or NULL
370
 */
371
VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );
372 373

/**
Sam Hocevar's avatar
Sam Hocevar committed
374 375
 * Returns the number of messages in a log instance.
 *
376 377
 * \param p_log libvlc log instance or NULL
 * \return number of log messages, 0 if p_log is NULL
378
 */
379
VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
380 381

/**
Sam Hocevar's avatar
Sam Hocevar committed
382 383 384 385 386
 * Clear a log instance.
 *
 * All messages in the log are removed. The log should be cleared on a
 * regular basis to avoid clogging.
 *
387
 * \param p_log libvlc log instance or NULL
388
 */
389
VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );
390 391

/**
Sam Hocevar's avatar
Sam Hocevar committed
392 393
 * Allocate and returns a new iterator to messages in log.
 *
394
 * \param p_log libvlc log instance
395
 * \param p_e an initialized exception pointer
396
 * \return log iterator object
397
 */
398
VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *);
399 400

/**
Sam Hocevar's avatar
Sam Hocevar committed
401 402
 * Release a previoulsy allocated iterator.
 *
403
 * \param p_iter libvlc log iterator or NULL
404
 */
405
VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
406 407

/**
Sam Hocevar's avatar
Sam Hocevar committed
408 409
 * Return whether log iterator has more messages.
 *
410
 * \param p_iter libvlc log iterator or NULL
411
 * \return true if iterator has more message objects, else false
412
 */
413
VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
414 415

/**
Sam Hocevar's avatar
Sam Hocevar committed
416 417 418 419
 * Return the next log message.
 *
 * The message contents must not be freed
 *
420
 * \param p_iter libvlc log iterator or NULL
421 422
 * \param p_buffer log buffer
 * \param p_e an initialized exception pointer
423
 * \return log message object
424
 */
425
VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
426
                                                               libvlc_log_message_t *p_buffer,
427
                                                               libvlc_exception_t *p_e );
428 429 430

/** @} */

431 432 433 434
# ifdef __cplusplus
}
# endif

Clément Stenac's avatar
Clément Stenac committed
435
#endif /* <vlc/libvlc.h> */