*/
/**
- * \defgroup libvlc libvlc
- * This is libvlc, the base library of the VLC program.
- *
+ * \defgroup libvlc LibVLC
+ * LibVLC is the external programming interface of the VLC media player.
+ * It is used to embed VLC into other applications or frameworks.
* @{
*/
#include <stdarg.h>
#include <vlc/libvlc_structures.h>
-/*****************************************************************************
- * Exception handling
- *****************************************************************************/
-/** \defgroup libvlc_exception libvlc_exception
- * \ingroup libvlc_core
- * LibVLC Exceptions handling
- * @{
- */
-
-/**
- * Initialize an exception structure. This can be called several times to
- * reuse an exception structure.
- *
- * \param p_exception the exception to initialize
- */
-VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
-
-/**
- * Has an exception been raised?
- *
- * \param p_exception the exception to query
- * \return 0 if the exception was raised, 1 otherwise
- */
-VLC_PUBLIC_API int
-libvlc_exception_raised( const libvlc_exception_t *p_exception );
-
-/**
- * Raise an exception.
- *
- * \param p_exception the exception to raise
- */
-VLC_PUBLIC_API void
-libvlc_exception_raise( libvlc_exception_t *p_exception );
-
-/**
- * Clear an exception object so it can be reused.
- * The exception object must have be initialized.
+/** \defgroup libvlc_core LibVLC core
+ * \ingroup libvlc
+ * Before it can do anything useful, LibVLC must be initialized.
+ * You can create one (or more) instance(s) of LibVLC in a given process,
+ * with libvlc_new() and destroy them with libvlc_release().
*
- * \param p_exception the exception to clear
+ * \version Unless otherwise stated, these functions are available
+ * from LibVLC versions numbered 1.1.0 or more.
+ * Earlier versions (0.9.x and 1.0.x) are <b>not</b> compatible.
+ * @{
*/
-VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
-/**@} */
-
-/*****************************************************************************
- * Error handling
- *****************************************************************************/
-/** \defgroup libvlc_error libvlc_error
- * \ingroup libvlc_core
- * LibVLC error handling
+/** \defgroup libvlc_error LibVLC error handling
* @{
*/
/**
* Sets the LibVLC error status and message for the current thread.
* Any previous error is overriden.
- * @return a nul terminated string in any case
+ * \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
+ * \return a nul terminated string in any case
*/
const char *libvlc_printerr (const char *fmt, ...);
/**@} */
-
-/*****************************************************************************
- * Core handling
- *****************************************************************************/
-
-/** \defgroup libvlc_core libvlc_core
- * \ingroup libvlc
- * LibVLC Core
- * @{
- */
-
/**
* Create and initialize a libvlc instance.
*
* \return the libvlc instance or NULL in case of error
*/
VLC_PUBLIC_API libvlc_instance_t *
-libvlc_new( int , const char *const * );
+libvlc_new( int argc , const char *const *argv );
/**
* Decrement the reference count of a libvlc instance, and destroy it
*
* \param p_instance the instance to destroy
*/
-VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
+VLC_PUBLIC_API void libvlc_release( libvlc_instance_t *p_instance );
/**
* Increments the reference count of a libvlc instance.
*
* \param p_instance the instance to reference
*/
-VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
+VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t *p_instance );
/**
* Try to start a user interface for the libvlc instance.
VLC_PUBLIC_API
int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name );
+/**
+ * Registers a callback for the LibVLC exit event. This is mostly useful if
+ * you have started at least one interface with libvlc_add_intf().
+ * Typically, this function will wake up your application main loop (from
+ * another thread).
+ *
+ * \param p_instance LibVLC instance
+ * \param cb callback to invoke when LibVLC wants to exit
+ * \param opaque data pointer for the callback
+ * \warning This function and libvlc_wait() cannot be used at the same time.
+ * Use either or none of them but not both.
+ */
+VLC_PUBLIC_API
+void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
+ void (*cb) (void *), void *opaque );
+
/**
* Waits until an interface causes the instance to exit.
* You should start at least one interface first, using libvlc_add_intf().
VLC_PUBLIC_API
void libvlc_wait( libvlc_instance_t *p_instance );
+/**
+ * Sets the application name. LibVLC passes this as the user agent string
+ * when a protocol requires it.
+ *
+ * \param p_instance LibVLC instance
+ * \param name human-readable application name, e.g. "FooBar player 1.2.3"
+ * \param http HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
+ * \version LibVLC 1.1.1 or later
+ */
+VLC_PUBLIC_API
+void libvlc_set_user_agent( libvlc_instance_t *p_instance,
+ const char *name, const char *http );
+
/**
* Retrieve libvlc version.
*
- * Example: "0.9.0-git Grishenko"
+ * Example: "1.1.0-git The Luggage"
*
* \return a string containing the libvlc version
*/
*/
VLC_PUBLIC_API const char * libvlc_get_changeset(void);
-struct vlc_object_t;
-/**
- * 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.
+/** \defgroup libvlc_event LibVLC asynchronous events
+ * LibVLC emits asynchronous events.
*
- * \param ptr the pointer
- */
-VLC_PUBLIC_API void libvlc_free( void *ptr );
-
-/** @}*/
-
-/*****************************************************************************
- * Event handling
- *****************************************************************************/
-
-/** \defgroup libvlc_event libvlc_event
- * \ingroup libvlc_core
- * LibVLC Events
+ * Several LibVLC objects (such @ref libvlc_instance_t as
+ * @ref libvlc_media_player_t) generate events asynchronously. Each of them
+ * provides @ref libvlc_event_manager_t event manager. You can subscribe to
+ * events with libvlc_event_attach() and unsubscribe with
+ * libvlc_event_detach().
* @{
*/
* Event manager that belongs to a libvlc object, and from whom events can
* be received.
*/
-
typedef struct libvlc_event_manager_t libvlc_event_manager_t;
-typedef struct libvlc_event_t libvlc_event_t;
-typedef uint32_t libvlc_event_type_t;
-
+
+struct libvlc_event_t;
+
+/**
+ * Type of a LibVLC event.
+ */
+typedef int libvlc_event_type_t;
+
/**
* Callback function notification
* \param p_event the event triggering the callback
*/
-
-typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
+typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
/**
* Register for an event notification.
/**
* Get an event's type name.
*
- * \param i_event_type the desired event
+ * \param event_type the desired event
*/
VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
/** @} */
-/*****************************************************************************
- * Message log handling
- *****************************************************************************/
-
-/** \defgroup libvlc_log libvlc_log
- * \ingroup libvlc_core
- * LibVLC Message Logging
+/** \defgroup libvlc_log LibVLC logging
+ * libvlc_log_* functions provide access to the LibVLC messages log.
+ * This is used for debugging or by advanced users.
* @{
*/
* \param p_instance libvlc instance
* \return log message instance or NULL on error
*/
-VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *);
+VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
/**
* Close a VLC message log instance.
* \param p_log libvlc log instance
* \return log iterator object or NULL on error
*/
-VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t * );
+VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
/**
* Release a previoulsy allocated iterator.
libvlc_log_message_t *p_buffer );
/** @} */
+/** @} */
+/** @} */
# ifdef __cplusplus
}
# endif
#endif /* <vlc/libvlc.h> */
-
-/** @} */
projects / vlc / blobdiff