LibVLC logging [LibVLC core]

libvlc_log_* functions provide access to the LibVLC messages log. More...

Collaboration diagram for LibVLC logging:

Data Structures
struct	libvlc_log_subscriber
	Data structure for a LibVLC logging callbacks. More...
Typedefs
typedef void(*	libvlc_log_cb )(void *data, int level, const char *fmt, va_list args)
	Callback prototype for LibVLC log message handler.
typedef struct libvlc_log_subscriber	libvlc_log_subscriber_t
	Data structure for a LibVLC logging callbacks.
Enumerations
enum	libvlc_log_level { LIBVLC_DEBUG = 0, LIBVLC_NOTICE = 2, LIBVLC_WARNING = 3, LIBVLC_ERROR = 4 }
	Logging messages level. More...
Functions
void	libvlc_log_subscribe (libvlc_log_subscriber_t *sub, libvlc_log_cb cb, void *data)
	Registers a logging callback to LibVLC.
void	libvlc_log_subscribe_file (libvlc_log_subscriber_t *sub, FILE *stream)
	Registers a logging callback to a file.
void	libvlc_log_unsubscribe (libvlc_log_subscriber_t *sub)
	Deregisters a logging callback from LibVLC.
unsigned	libvlc_get_log_verbosity (const libvlc_instance_t *p_instance)
	Always returns minus one.
void	libvlc_set_log_verbosity (libvlc_instance_t *p_instance, unsigned level)
	This function does nothing.
libvlc_log_t *	libvlc_log_open (libvlc_instance_t *p_instance)
	This function does nothing useful.
void	libvlc_log_close (libvlc_log_t *p_log)
	Frees memory allocated by libvlc_log_open().
unsigned	libvlc_log_count (const libvlc_log_t *p_log)
	Always returns zero.
void	libvlc_log_clear (libvlc_log_t *p_log)
	This function does nothing.
libvlc_log_iterator_t *	libvlc_log_get_iterator (const libvlc_log_t *p_log)
	This function does nothing useful.
void	libvlc_log_iterator_free (libvlc_log_iterator_t *p_iter)
	Frees memory allocated by libvlc_log_get_iterator().
int	libvlc_log_iterator_has_next (const libvlc_log_iterator_t *p_iter)
	Always returns zero.
libvlc_log_message_t *	libvlc_log_iterator_next (libvlc_log_iterator_t *p_iter, libvlc_log_message_t *p_buf)
	Always returns NULL.
typedef struct libvlc_log_t	libvlc_log_t
	This structure is opaque.
typedef struct libvlc_log_iterator_t	libvlc_log_iterator_t
	This structure is opaque.
typedef struct libvlc_log_message_t	libvlc_log_message_t

---

Detailed Description

libvlc_log_* functions provide access to the LibVLC messages log.

This is used for logging and debugging.

---

Typedef Documentation

typedef void(* libvlc_log_cb)(void *data, int level, const char *fmt, va_list args)

Callback prototype for LibVLC log message handler.

Parameters:

	data	data pointer as given to libvlc_log_subscribe()
	level	message level (enum libvlc_log_level)
	fmt	printf() format string (as defined by ISO C11)
	args	variable argument list for the format

Note:

Log message handlers must be thread-safe.

typedef struct libvlc_log_iterator_t libvlc_log_iterator_t

This structure is opaque.

It represents a libvlc log iterator

typedef struct libvlc_log_message_t libvlc_log_message_t

typedef struct libvlc_log_subscriber libvlc_log_subscriber_t

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.)

typedef struct libvlc_log_t libvlc_log_t

This structure is opaque.

It represents a libvlc log instance

---

Enumeration Type Documentation

enum libvlc_log_level

Logging messages level.

Note:

Future LibVLC versions may define new levels.

Enumerator:

LIBVLC_DEBUG	Debug message.
LIBVLC_NOTICE	Important informational message.
LIBVLC_WARNING	Warning (potential error) message.
LIBVLC_ERROR	Error message.

---

Function Documentation

unsigned libvlc_get_log_verbosity

(

const libvlc_instance_t *

p_instance

)

Always returns minus one.

This function is only provided for backward compatibility.

Parameters:

p_instance

ignored

Returns:

always -1

void libvlc_log_clear

(

libvlc_log_t *

p_log

)

This function does nothing.

It is only provided for backward compatibility.

Parameters:

p_log

ignored

void libvlc_log_close

(

libvlc_log_t *

p_log

)

Frees memory allocated by libvlc_log_open().

Parameters:

p_log

libvlc log instance or NULL

unsigned libvlc_log_count

(

const libvlc_log_t *

p_log

)

Always returns zero.

This function is only provided for backward compatibility.

Parameters:

p_log

ignored

Returns:

always zero

libvlc_log_iterator_t* libvlc_log_get_iterator

(

const libvlc_log_t *

p_log

)

This function does nothing useful.

It is only provided for backward compatibility.

Parameters:

p_log

ignored

Returns:

an unique pointer or NULL on error or if the parameter was NULL

void libvlc_log_iterator_free

(

libvlc_log_iterator_t *

p_iter

)

Frees memory allocated by libvlc_log_get_iterator().

Parameters:

p_iter

libvlc log iterator or NULL

int libvlc_log_iterator_has_next

(

const libvlc_log_iterator_t *

p_iter

)

Always returns zero.

This function is only provided for backward compatibility.

Parameters:

p_iter

ignored

Returns:

always zero

libvlc_log_message_t* libvlc_log_iterator_next	(	libvlc_log_iterator_t *	p_iter,
		libvlc_log_message_t *	p_buf
	)

Always returns NULL.

This function is only provided for backward compatibility.

Parameters:

	p_iter	libvlc log iterator or NULL
	p_buf	ignored

Returns:

always NULL

libvlc_log_t* libvlc_log_open

(

libvlc_instance_t *

p_instance

)

This function does nothing useful.

It is only provided for backward compatibility.

Parameters:

p_instance

libvlc instance

Returns:

an unique pointer or NULL on error

void libvlc_log_subscribe	(	libvlc_log_subscriber_t *	sub,
		libvlc_log_cb	cb,
		void *	data
	)

Registers a logging callback to LibVLC.

This function is thread-safe.

Parameters:

	sub	uninitialized subscriber structure
	cb	callback function pointer
	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.

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.

Do not call this function from within a logging callback. It would trigger a dead lock.

Version:

LibVLC 2.1.0 or later

void libvlc_log_subscribe_file	(	libvlc_log_subscriber_t *	sub,
		FILE *	stream
	)

Registers a logging callback to a file.

Parameters:

stream

FILE pointer opened for writing (the FILE pointer must remain valid until libvlc_log_unsubscribe())

Version:

LibVLC 2.1.0 or later

void libvlc_log_unsubscribe

(

libvlc_log_subscriber_t *

sub

)

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.

Parameters:

sub

initialized subscriber structure

Version:

LibVLC 2.1.0 or later

void libvlc_set_log_verbosity	(	libvlc_instance_t *	p_instance,
		unsigned	level
	)

This function does nothing.

It is only provided for backward compatibility.

Parameters:

	p_instance	ignored
	level	ignored