#ifndef VLC_LIBVLC_H
#define VLC_LIBVLC_H 1
-#if defined (WIN32) && defined (DLL_EXPORT)
+#if defined (_WIN32) && defined (DLL_EXPORT)
# define LIBVLC_API __declspec(dllexport)
#elif defined (__GNUC__) && (__GNUC__ >= 4)
# define LIBVLC_API __attribute__((visibility("default")))
/**
* Sets the LibVLC error status and message for the current thread.
* Any previous error is overridden.
+ * \param fmt the format string
+ * \param ap the arguments
* \return a nul terminated string in any case
*/
LIBVLC_API 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 overridden.
+ * \param fmt the format string
+ * \param args the arguments
* \return a nul terminated string in any case
*/
LIBVLC_API const char *libvlc_printerr (const char *fmt, ...);
/**
* Registers a callback for the LibVLC exit event. This is mostly useful if
- * you have started at least one interface with libvlc_add_intf().
+ * the VLC playlist and/or at least one interface are started with
+ * libvlc_playlist_play() or libvlc_add_intf() respectively.
* Typically, this function will wake up your application main loop (from
* another thread).
*
+ * \note This function should be called before the playlist or interface are
+ * started. Otherwise, there is a small race condition: the exit event could
+ * be raised before the handler is registered.
+ *
* \param p_instance LibVLC instance
- * \param cb callback to invoke when LibVLC wants to exit
+ * \param cb callback to invoke when LibVLC wants to exit,
+ * or NULL to disable the exit handler (as by default)
* \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.
*/
LIBVLC_API
void libvlc_set_exit_handler( libvlc_instance_t *p_instance,
* You should start at least one interface first, using libvlc_add_intf().
*
* \param p_instance the instance
+ * \warning This function wastes one thread doing basically nothing.
+ * libvlc_set_exit_handler() should be used instead.
*/
-LIBVLC_API
+LIBVLC_DEPRECATED LIBVLC_API
void libvlc_wait( libvlc_instance_t *p_instance );
/**
void libvlc_set_user_agent( libvlc_instance_t *p_instance,
const char *name, const char *http );
+/**
+ * Sets some meta-information about the application.
+ * See also libvlc_set_user_agent().
+ *
+ * \param p_instance LibVLC instance
+ * \param id Java-style application identifier, e.g. "com.acme.foobar"
+ * \param version application version numbers, e.g. "1.2.3"
+ * \param icon application icon name, e.g. "foobar"
+ * \version LibVLC 2.1.0 or later.
+ */
+LIBVLC_API
+void libvlc_set_app_id( libvlc_instance_t *p_instance, const char *id,
+ const char *version, const char *icon );
+
/**
* Retrieve libvlc version.
*
*/
enum libvlc_log_level
{
- LIBVLC_DEBUG=0 /**< Debug message */,
- LIBVLC_NOTICE=2 /**< Important informational message */,
- LIBVLC_WARNING=3 /**< Warning (potential error) message */,
- LIBVLC_ERROR=4 /**< Error message */,
+ LIBVLC_DEBUG=0, /**< Debug message */
+ LIBVLC_NOTICE=2, /**< Important informational message */
+ LIBVLC_WARNING=3, /**< Warning (potential error) message */
+ LIBVLC_ERROR=4 /**< Error message */
};
+typedef struct vlc_log_t libvlc_log_t;
+
+/**
+ * Gets debugging information about a log message: the name of the VLC module
+ * emitting the message and the message location within the source code.
+ *
+ * The returned module name and file name will be NULL if unknown.
+ * The returned line number will similarly be zero if unknown.
+ *
+ * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
+ * \param module module name storage (or NULL) [OUT]
+ * \param file source code file name storage (or NULL) [OUT]
+ * \param line source code file line number storage (or NULL) [OUT]
+ * \warning The returned module name and source code file name, if non-NULL,
+ * are only valid until the logging callback returns.
+ *
+ * \version LibVLC 2.1.0 or later
+ */
+LIBVLC_API void libvlc_log_get_context(const libvlc_log_t *ctx,
+ const char **module, const char **file, unsigned *line);
+
+/**
+ * Gets VLC object information about a log message: the type name of the VLC
+ * object emitting the message, the object header if any and a temporaly-unique
+ * object identifier. This information is mainly meant for <b>manual</b>
+ * troubleshooting.
+ *
+ * The returned type name may be "generic" if unknown, but it cannot be NULL.
+ * The returned header will be NULL if unset; in current versions, the header
+ * is used to distinguish for VLM inputs.
+ * The returned object ID will be zero if the message is not associated with
+ * any VLC object.
+ *
+ * \param ctx message context (as passed to the @ref libvlc_log_cb callback)
+ * \param name object name storage (or NULL) [OUT]
+ * \param header object header (or NULL) [OUT]
+ * \param line source code file line number storage (or NULL) [OUT]
+ * \warning The returned module name and source code file name, if non-NULL,
+ * are only valid until the logging callback returns.
+ *
+ * \version LibVLC 2.1.0 or later
+ */
+LIBVLC_API void libvlc_log_get_object(const libvlc_log_t *ctx,
+ const char **name, const char **header, uintptr_t *id);
+
/**
* Callback prototype for LibVLC log message handler.
- * \param data data pointer as given to libvlc_log_subscribe()
+ * \param data data pointer as given to libvlc_log_set()
* \param level message level (@ref enum libvlc_log_level)
+ * \param ctx message context (meta-information about the message)
* \param fmt printf() format string (as defined by ISO C11)
* \param args variable argument list for the format
* \note Log message handlers <b>must</b> be thread-safe.
+ * \warning The message context pointer, the format string parameters and the
+ * variable arguments are only valid until the callback returns.
*/
-typedef void (*libvlc_log_cb)(void *data, int level, const char *fmt,
- va_list args);
+typedef void (*libvlc_log_cb)(void *data, int level, const libvlc_log_t *ctx,
+ const char *fmt, va_list args);
/**
- * Data structure for a LibVLC logging callbacks.
- * \note This structure contains exactly 4 pointers and will never change.
- * Nevertheless, it should not be accessed directly outside of LibVLC.
- * (In fact, doing so would fail the thread memory model.)
+ * Unsets the logging callback for a LibVLC instance. This is rarely needed:
+ * the callback is implicitly unset when the instance is destroyed.
+ * This function will wait for any pending callbacks invocation to complete
+ * (causing a deadlock if called from within the callback).
+ *
+ * \param p_instance libvlc instance
+ * \version LibVLC 2.1.0 or later
*/
-typedef struct libvlc_log_subscriber
-{
- struct libvlc_log_subscriber *prev, *next;
- libvlc_log_cb func;
- void *opaque;
-} libvlc_log_subscriber_t;
+LIBVLC_API void libvlc_log_unset( libvlc_instance_t * );
/**
- * Registers a logging callback to LibVLC.
- * This function is thread-safe.
+ * Sets the logging callback for a LibVLC instance.
+ * This function is thread-safe: it will wait for any pending callbacks
+ * invocation to complete.
*
- * \param sub uninitialized subscriber structure
* \param cb callback function pointer
* \param data opaque data pointer for the callback function
*
* \note Some log messages (especially debug) are emitted by LibVLC while
- * initializing, before any LibVLC instance even exists.
- * Thus this function does not require a LibVLC instance parameter.
+ * is being initialized. These messages cannot be captured with this interface.
*
- * \warning As a consequence of not depending on a LibVLC instance,
- * all logging callbacks are shared by all LibVLC instances within the
- * process / address space. This also enables log messages to be emitted
- * by LibVLC components that are not specific to any given LibVLC instance.
+ * \warning A deadlock may occur if this function is called from the callback.
*
- * \warning Do not call this function from within a logging callback.
- * It would trigger a dead lock.
+ * \param p_instance libvlc instance
+ * \version LibVLC 2.1.0 or later
*/
-LIBVLC_API void libvlc_log_subscribe( libvlc_log_subscriber_t *sub,
- libvlc_log_cb cb, void *data );
-
+LIBVLC_API void libvlc_log_set( libvlc_instance_t *,
+ libvlc_log_cb cb, void *data );
-/**
- * Registers a logging callback to a file.
- * @param stream FILE pointer opened for writing
- * (the FILE pointer must remain valid until libvlc_log_unsubscribe())
- */
-LIBVLC_API void libvlc_log_subscribe_file( libvlc_log_subscriber_t *sub,
- FILE *stream );
/**
- * Deregisters a logging callback from LibVLC.
- * This function is thread-safe.
- *
- * \note After (and only after) libvlc_log_unsubscribe() has returned,
- * LibVLC warrants that there are no more pending calls of the subscription
- * callback function.
- *
- * \warning Do not call this function from within a logging callback.
- * It would trigger a dead lock.
- *
- * \param sub initialized subscriber structure
+ * Sets up logging to a file.
+ * \param p_instance libvlc instance
+ * \param stream FILE pointer opened for writing
+ * (the FILE pointer must remain valid until libvlc_log_unset())
+ * \version LibVLC 2.1.0 or later
*/
-LIBVLC_API void libvlc_log_unsubscribe( libvlc_log_subscriber_t *sub );
+LIBVLC_API void libvlc_log_set_file( libvlc_instance_t *, FILE *stream );
/**
* Always returns minus one.
* \param p_instance ignored
* \return always -1
*/
-LIBVLC_DEPRECATED
-LIBVLC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
+LIBVLC_DEPRECATED LIBVLC_API
+unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
/**
* This function does nothing.
* \param p_instance ignored
* \param level ignored
*/
-LIBVLC_DEPRECATED
-LIBVLC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
/**
* This function does nothing useful.
* \param p_instance libvlc instance
* \return an unique pointer or NULL on error
*/
-LIBVLC_DEPRECATED
-LIBVLC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
+LIBVLC_DEPRECATED LIBVLC_API
+libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
/**
* Frees memory allocated by libvlc_log_open().
*
* \param p_log libvlc log instance or NULL
*/
-LIBVLC_DEPRECATED
-LIBVLC_API void libvlc_log_close( libvlc_log_t *p_log );
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_log_close( libvlc_log_t *p_log );
/**
* Always returns zero.
* \param p_log ignored
* \return always zero
*/
-LIBVLC_DEPRECATED
-LIBVLC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );
+LIBVLC_DEPRECATED LIBVLC_API
+unsigned libvlc_log_count( const libvlc_log_t *p_log );
/**
* This function does nothing.
*
* \param p_log ignored
*/
-LIBVLC_DEPRECATED
-LIBVLC_API void libvlc_log_clear( libvlc_log_t *p_log );
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_log_clear( libvlc_log_t *p_log );
/**
* This function does nothing useful.
* \param p_log ignored
* \return an unique pointer or NULL on error or if the parameter was NULL
*/
-LIBVLC_DEPRECATED
-LIBVLC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
+LIBVLC_DEPRECATED LIBVLC_API
+libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
/**
* Frees memory allocated by libvlc_log_get_iterator().
*
* \param p_iter libvlc log iterator or NULL
*/
-LIBVLC_DEPRECATED
-LIBVLC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
/**
* Always returns zero.
* \param p_iter ignored
* \return always zero
*/
-LIBVLC_DEPRECATED
-LIBVLC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
+LIBVLC_DEPRECATED LIBVLC_API
+int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
/**
* Always returns NULL.
* This function is only provided for backward compatibility.
*
* \param p_iter libvlc log iterator or NULL
- * \param p_buffer ignored
+ * \param p_buf ignored
* \return always NULL
*/
-LIBVLC_DEPRECATED
-LIBVLC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
- libvlc_log_message_t *p_buffer );
+LIBVLC_DEPRECATED LIBVLC_API
+libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
+ libvlc_log_message_t *p_buf );
/** @} */
projects / vlc / blobdiff