LibVLC logging

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