X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc.h;h=6de7328bf5ec039a8546f8289eec6bb729f82642;hb=2114b4ec0bc95a135963c34cd8c6188e786691ae;hp=bed66eaa7a18cc564c30e65383a322f09e9ca9c3;hpb=a6bb43df184076e378d7c0bcf8b1df06db2ee7eb;p=vlc diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h index bed66eaa7a..6de7328bf5 100644 --- a/include/vlc/libvlc.h +++ b/include/vlc/libvlc.h @@ -58,6 +58,7 @@ extern "C" { # endif +#include #include /***************************************************************************** @@ -87,15 +88,12 @@ VLC_PUBLIC_API int libvlc_exception_raised( const libvlc_exception_t *p_exception ); /** - * Raise an exception using a user-provided message. + * Raise an exception. * * \param p_exception the exception to raise - * \param psz_format the exception message format string - * \param ... the format string arguments */ VLC_PUBLIC_API void -libvlc_exception_raise( libvlc_exception_t *p_exception, - const char *psz_format, ... ); +libvlc_exception_raise( libvlc_exception_t *p_exception ); /** * Clear an exception object so it can be reused. @@ -105,18 +103,51 @@ libvlc_exception_raise( libvlc_exception_t *p_exception, */ VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * ); +/**@} */ + +/***************************************************************************** + * Error handling + *****************************************************************************/ +/** \defgroup libvlc_error libvlc_error + * \ingroup libvlc_core + * LibVLC error handling + * @{ + */ + /** - * Get an exception's message. + * 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). * - * \param p_exception the exception to query - * \return the exception message or NULL if not applicable (exception not - * raised, for example) + * @warning + * This will be NULL if there was no error. + */ +VLC_PUBLIC_API const char *libvlc_errmsg (void); + +/** + * 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. + */ +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 */ -VLC_PUBLIC_API const char * -libvlc_exception_get_message( const libvlc_exception_t *p_exception ); +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, ...); /**@} */ + /***************************************************************************** * Core handling *****************************************************************************/ @@ -139,16 +170,6 @@ libvlc_exception_get_message( const libvlc_exception_t *p_exception ); VLC_PUBLIC_API libvlc_instance_t * libvlc_new( int , const char *const *, libvlc_exception_t *); -/** - * Return a libvlc instance identifier for legacy APIs. Use of this - * function is discouraged, you should convert your program to use the - * new API. - * - * \param p_instance the instance - * \return the instance identifier - */ -VLC_PUBLIC_API int libvlc_get_vlc_id( libvlc_instance_t *p_instance ); - /** * Decrement the reference count of a libvlc instance, and destroy it * if it reaches zero. @@ -170,11 +191,10 @@ VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * ); * * \param p_instance the instance * \param name interface name, or NULL for default - * \param p_exception an initialized exception pointer + * \return 0 on success, -1 on error. */ VLC_PUBLIC_API -void libvlc_add_intf( libvlc_instance_t *p_instance, const char *name, - libvlc_exception_t *p_exception ); +int libvlc_add_intf( libvlc_instance_t *p_instance, const char *name ); /** * Waits until an interface causes the instance to exit. @@ -215,20 +235,25 @@ VLC_PUBLIC_API const char * libvlc_get_changeset(void); struct vlc_object_t; /** - * Return the libvlc internal object, the main object that all other depend on. - * Any of of this function should be considered an ugly hack and avoided at all - * cost. E.g. you need to expose some functionality that is not provided by the - * libvlc API directly with libvlccore. - * Remember to release the object with vlc_object_release( obj* ) + * 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(). * * \param p_instance the libvlc instance + * @return a VLC object of type "libvlc" */ -VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *); +VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *p_instance); /** * 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. + * + * \param ptr the pointer */ VLC_PUBLIC_API void libvlc_free( void *ptr ); @@ -251,7 +276,7 @@ VLC_PUBLIC_API void libvlc_free( void *ptr ); typedef struct libvlc_event_manager_t libvlc_event_manager_t; typedef struct libvlc_event_t libvlc_event_t; -typedef enum libvlc_event_type_t libvlc_event_type_t; +typedef uint32_t libvlc_event_type_t; /** * Callback function notification @@ -269,13 +294,12 @@ typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * ); * \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 - * \param p_e an initialized exception pointer + * \return 0 on success, ENOMEM on error */ -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 ); +VLC_PUBLIC_API int 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 ); /** * Unregister an event notification. @@ -284,13 +308,11 @@ VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_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 - * \param p_e an initialized exception pointer */ 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 ); + void *p_user_data ); /** * Get an event's type name. @@ -315,21 +337,17 @@ VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_ty * Return the VLC messaging verbosity level. * * \param p_instance libvlc instance - * \param p_e an initialized exception pointer * \return verbosity level for messages */ -VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance ); /** * Set the VLC messaging verbosity level. * * \param p_instance libvlc log instance * \param level log level - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level ); /** * Open a VLC message log instance. @@ -343,19 +361,17 @@ VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_except /** * Close a VLC message log instance. * - * \param p_log libvlc log instance - * \param p_e an initialized exception pointer + * \param p_log libvlc log instance or NULL */ -VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log ); /** * Returns the number of messages in a log instance. * - * \param p_log libvlc log instance - * \param p_e an initialized exception pointer - * \return number of log messages + * \param p_log libvlc log instance or NULL + * \return number of log messages, 0 if p_log is NULL */ -VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *, libvlc_exception_t *); +VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log ); /** * Clear a log instance. @@ -363,10 +379,9 @@ VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *, libvlc_exception * All messages in the log are removed. The log should be cleared on a * regular basis to avoid clogging. * - * \param p_log libvlc log instance - * \param p_e an initialized exception pointer + * \param p_log libvlc log instance or NULL */ -VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log ); /** * Allocate and returns a new iterator to messages in log. @@ -380,26 +395,24 @@ VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_ /** * Release a previoulsy allocated iterator. * - * \param p_iter libvlc log iterator - * \param p_e an initialized exception pointer + * \param p_iter libvlc log iterator or NULL */ -VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e ); +VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter ); /** * Return whether log iterator has more messages. * - * \param p_iter libvlc log iterator - * \param p_e an initialized exception pointer + * \param p_iter libvlc log iterator or NULL * \return true if iterator has more message objects, else false */ -VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e ); +VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter ); /** * Return the next log message. * * The message contents must not be freed * - * \param p_iter libvlc log iterator + * \param p_iter libvlc log iterator or NULL * \param p_buffer log buffer * \param p_e an initialized exception pointer * \return log message object @@ -415,3 +428,5 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat # endif #endif /* */ + +/** @} */