X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc.h;h=36b263feef32c270754f3b06ff778ecaeb363666;hb=0e3e62f3582ab6ee45462dc7b39fabab935a5e68;hp=51bb78f4c2f55a3520b207caa0730891347a7a4e;hpb=61f0547b72d3ba80039f09064249d89fa8f2b0f7;p=vlc diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h index 51bb78f4c2..36b263feef 100644 --- a/include/vlc/libvlc.h +++ b/include/vlc/libvlc.h @@ -29,9 +29,9 @@ */ /** - * \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. * @{ */ @@ -61,12 +61,19 @@ extern "C" { #include #include -/***************************************************************************** - * Error handling - *****************************************************************************/ -/** \defgroup libvlc_error libvlc_error - * \ingroup libvlc_core - * LibVLC error handling +/** \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(). + * + * \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 not compatible. + * @{ + */ + +/** \defgroup libvlc_error LibVLC error handling * @{ */ @@ -90,30 +97,19 @@ VLC_PUBLIC_API void libvlc_clearerr (void); /** * 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. * @@ -150,6 +146,22 @@ VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t *p_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(). @@ -159,10 +171,23 @@ int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name ); 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 */ @@ -186,17 +211,15 @@ VLC_PUBLIC_API const char * libvlc_get_compiler(void); */ VLC_PUBLIC_API const char * libvlc_get_changeset(void); -struct vlc_object_t; - -/** @}*/ - -/***************************************************************************** - * Event handling - *****************************************************************************/ -/** \defgroup libvlc_event libvlc_event - * \ingroup libvlc_core - * LibVLC Events +/** \defgroup libvlc_event LibVLC asynchronous events + * LibVLC emits asynchronous 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(). * @{ */ @@ -204,17 +227,20 @@ struct vlc_object_t; * 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. @@ -254,13 +280,9 @@ VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_ty /** @} */ -/***************************************************************************** - * 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. * @{ */ @@ -349,11 +371,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat libvlc_log_message_t *p_buffer ); /** @} */ +/** @} */ +/** @} */ # ifdef __cplusplus } # endif #endif /* */ - -/** @} */