Communication inside and between applications. More...

Modules
	Message queues
	Thread save message queues.
	Lists of message queues
	Send messages to multiple message queues.
Defines
#define	BG_MSG_NONE -1
	Reserved ID for non valid message.
#define	BG_MSG_MAX_ARGS 4
	Maximum number of args.
Typedefs
typedef struct bg_msg_s	bg_msg_t
	Opaque message type, you don't want to know what's inside.
typedef int(*	bg_msg_read_callback_t )(void priv, uint8_t data, int len)
	Callback for bg_msg_read.
typedef int(*	bg_msg_write_callback_t )(void priv, const uint8_t data, int len)
	Callback for bg_msg_write.
Functions
bg_msg_t *	bg_msg_create ()
	Create a message.
void	bg_msg_destroy (bg_msg_t *msg)
	Destroy a message.
void	bg_msg_free (bg_msg_t *msg)
	Free internal memory of the message.
void	bg_msg_set_id (bg_msg_t *msg, int id)
	Set the ID of a message.
int	bg_msg_get_id (bg_msg_t *msg)
	Get the ID of a message.
void	bg_msg_set_arg_int (bg_msg_t *msg, int arg, int value)
	Set an integer argument.
int	bg_msg_get_arg_int (bg_msg_t *msg, int arg)
	Get an integer argument.
void	bg_msg_set_arg_time (bg_msg_t *msg, int arg, gavl_time_t value)
	Set a time argument.
gavl_time_t	bg_msg_get_arg_time (bg_msg_t *msg, int arg)
	Get a time argument.
void	bg_msg_set_arg_string (bg_msg_t msg, int arg, const char value)
	Set a string argument.
char *	bg_msg_get_arg_string (bg_msg_t *msg, int arg)
	Get a string argument.
void	bg_msg_set_arg_float (bg_msg_t *msg, int arg, double value)
	Set a float argument.
double	bg_msg_get_arg_float (bg_msg_t *msg, int arg)
	Get a float argument.
void	bg_msg_set_arg_color_rgb (bg_msg_t msg, int arg, const float value)
	Set an RGB color argument.
void	bg_msg_get_arg_color_rgb (bg_msg_t msg, int arg, float value)
	Get an RGB color argument.
void	bg_msg_set_arg_color_rgba (bg_msg_t msg, int arg, const float value)
	Set an RGBA color argument.
void	bg_msg_get_arg_color_rgba (bg_msg_t msg, int arg, float value)
	Get an RGBA color argument.
void	bg_msg_set_arg_position (bg_msg_t msg, int arg, const double value)
	Set a position argument.
void	bg_msg_get_arg_position (bg_msg_t msg, int arg, double value)
	Get a position argument.
void *	bg_msg_set_arg_ptr (bg_msg_t *msg, int arg, int len)
	Set a binary data argument.
void *	bg_msg_get_arg_ptr (bg_msg_t msg, int arg, int len)
	Set a binary data argument.
void	bg_msg_set_arg_ptr_nocopy (bg_msg_t msg, int arg, void ptr)
	Set a pointer argument without copying data.
void *	bg_msg_get_arg_ptr_nocopy (bg_msg_t *msg, int arg)
	Get a pointer argument without copying data.
void	bg_msg_set_arg_audio_format (bg_msg_t msg, int arg, const gavl_audio_format_t format)
	Set an audio format argument.
void	bg_msg_get_arg_audio_format (bg_msg_t msg, int arg, gavl_audio_format_t format, int *big_endian)
	Get an audio format argument.
void	bg_msg_set_arg_video_format (bg_msg_t msg, int arg, const gavl_video_format_t format)
	Set a video format argument.
void	bg_msg_get_arg_video_format (bg_msg_t msg, int arg, gavl_video_format_t format, int *big_endian)
	Get a video format argument.
void	bg_msg_set_arg_metadata (bg_msg_t msg, int arg, const bg_metadata_t m)
	Set a matadata argument.
void	bg_msg_get_arg_metadata (bg_msg_t msg, int arg, bg_metadata_t m)
	Get a matadata argument.
int	bg_msg_read (bg_msg_t ret, bg_msg_read_callback_t cb, void cb_data)
	Read a message using a callback.
int	bg_msg_write (bg_msg_t msg, bg_msg_write_callback_t cb, void cb_data)
	Write a message using a callback.
int	bg_msg_read_socket (bg_msg_t *ret, int fd, int milliseconds)
	Read a message from a socket.
int	bg_msg_write_socket (bg_msg_t *msg, int fd)
	Write a message to a socket.
int	bg_msg_write_audio_frame (bg_msg_t msg, const gavl_audio_format_t format, const gavl_audio_frame_t frame, bg_msg_write_callback_t cb, void cb_data)
	Write an audio frame.
int	bg_msg_read_audio_frame (gavl_dsp_context_t ctx, bg_msg_t msg, const gavl_audio_format_t format, gavl_audio_frame_t frame, bg_msg_read_callback_t cb, void *cb_data, int big_endian)
	Read an audio frame.
void	bg_msg_set_parameter (bg_msg_t msg, const char name, bg_parameter_type_t type, const bg_parameter_value_t *val)
	Set a parameter.
void	bg_msg_get_parameter (bg_msg_t msg, char name, bg_parameter_type_t type, bg_parameter_value_t *val)
	Get a parameter.

Detailed Description

Communication inside and between applications.

Gmerlin messages are a universal method to do communication between processes or threads. Each message consists of an integer ID and a number of arguments. Arguments can be strings, numbers or complex types like gavl_audio_format_t. For inter-thread comminucation, you can pass pointers as arguments as well.

For multithread applications, there are message queues (bg_msg_queue_t). They are thread save FIFO structures, which allow asynchronous communication between threads.

For communication via sockets, there are the ultra-simple functions bg_msg_read_socket and bg_msg_write_socket, which can be used to build network protocols (e.g. remote control of applications)

Define Documentation

#define BG_MSG_NONE -1

Reserved ID for non valid message.

#define BG_MSG_MAX_ARGS 4

Maximum number of args.

Typedef Documentation

typedef struct bg_msg_s bg_msg_t

Opaque message type, you don't want to know what's inside.

typedef int(* bg_msg_read_callback_t)(void *priv, uint8_t *data, int len)

Callback for bg_msg_read.

Parameters:

priv	The private data you passed to bg_msg_read
data	A buffer
len	Number of bytes to read

Returns:: The actual number of bytes read

typedef int(* bg_msg_write_callback_t)(void *priv, const uint8_t *data, int len)

Callback for bg_msg_write.

Parameters:

priv	The private data you passed to bg_msg_write
data	A buffer
len	Number of bytes to write

Returns:: The actual number of bytes write

Function Documentation

bg_msg_t* bg_msg_create ( )

Create a message.

Returns:: A newly allocated message

void bg_msg_destroy ( bg_msg_t * msg )

Destroy a message.

Parameters:

msg A message

void bg_msg_free ( bg_msg_t * msg )

Free internal memory of the message.

Parameters:

msg A message

Use this, if you want to reuse the message with a different ID or args

void bg_msg_set_id	(	bg_msg_t *	msg,
		int	id
	)

Set the ID of a message.

Parameters:

msg	A message
id	The ID

int bg_msg_get_id ( bg_msg_t * msg )

Get the ID of a message.

Parameters:

msg A message

Returns:: The ID

void bg_msg_set_arg_int	(	bg_msg_t *	msg,
		int	arg,
		int	value
	)

Set an integer argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

int bg_msg_get_arg_int	(	bg_msg_t *	msg,
		int	arg
	)

Get an integer argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)

Returns:: Value

void bg_msg_set_arg_time	(	bg_msg_t *	msg,
		int	arg,
		gavl_time_t	value
	)

Set a time argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

gavl_time_t bg_msg_get_arg_time	(	bg_msg_t *	msg,
		int	arg
	)

Get a time argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)

Returns:: Value

void bg_msg_set_arg_string	(	bg_msg_t *	msg,
		int	arg,
		const char *	value
	)

Set a string argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

char* bg_msg_get_arg_string	(	bg_msg_t *	msg,
		int	arg
	)

Get a string argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)

Returns:: The string

You can get the string value only once from each arg and must free() it, when you are done with it

void bg_msg_set_arg_float	(	bg_msg_t *	msg,
		int	arg,
		double	value
	)

Set a float argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

double bg_msg_get_arg_float	(	bg_msg_t *	msg,
		int	arg
	)

Get a float argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)

Returns:: Value

void bg_msg_set_arg_color_rgb	(	bg_msg_t *	msg,
		int	arg,
		const float *	value
	)

Set an RGB color argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void bg_msg_get_arg_color_rgb	(	bg_msg_t *	msg,
		int	arg,
		float *	value
	)

Get an RGB color argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void bg_msg_set_arg_color_rgba	(	bg_msg_t *	msg,
		int	arg,
		const float *	value
	)

Set an RGBA color argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void bg_msg_get_arg_color_rgba	(	bg_msg_t *	msg,
		int	arg,
		float *	value
	)

Get an RGBA color argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void bg_msg_set_arg_position	(	bg_msg_t *	msg,
		int	arg,
		const double *	value
	)

Set a position argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void bg_msg_get_arg_position	(	bg_msg_t *	msg,
		int	arg,
		double *	value
	)

Get a position argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
value	Value

void* bg_msg_set_arg_ptr	(	bg_msg_t *	msg,
		int	arg,
		int	len
	)

Set a binary data argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
len	Number of bytes requested

Returns:: A pointer to a buffer of at least len bytes, to which you can copy the data

void* bg_msg_get_arg_ptr	(	bg_msg_t *	msg,
		int	arg,
		int *	len
	)

Set a binary data argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
len	Returns the number of bytes

Returns:: A pointer to a buffer of at least len bytes, where you find the data

You can get the buffer only once from each arg and must free() it, when you are done with it

void bg_msg_set_arg_ptr_nocopy	(	bg_msg_t *	msg,
		int	arg,
		void *	ptr
	)

Set a pointer argument without copying data.

Parameters:

msg	A message
arg	Argument index (starting with 0)
ptr	A pointer

Use this only for communication inside the same address space

void* bg_msg_get_arg_ptr_nocopy	(	bg_msg_t *	msg,
		int	arg
	)

Get a pointer argument without copying data.

Parameters:

msg	A message
arg	Argument index (starting with 0)

Returns:: A pointer

Use this only for communication inside the same address space

void bg_msg_set_arg_audio_format	(	bg_msg_t *	msg,
		int	arg,
		const gavl_audio_format_t *	format
	)

Set an audio format argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
format	An audio format

void bg_msg_get_arg_audio_format	(	bg_msg_t *	msg,
		int	arg,
		gavl_audio_format_t *	format,
		int *	big_endian
	)

Get an audio format argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
format	Returns the audio format
big_endian	If non-null, returns 1 if multibyte numbers are in big endian

void bg_msg_set_arg_video_format	(	bg_msg_t *	msg,
		int	arg,
		const gavl_video_format_t *	format
	)

Set a video format argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
format	A video format

void bg_msg_get_arg_video_format	(	bg_msg_t *	msg,
		int	arg,
		gavl_video_format_t *	format,
		int *	big_endian
	)

Get a video format argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
format	Returns the video format
big_endian	If non-null, returns 1 if multibyte numbers are in big endian

void bg_msg_set_arg_metadata	(	bg_msg_t *	msg,
		int	arg,
		const bg_metadata_t *	m
	)

Set a matadata argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
m	Metadata

void bg_msg_get_arg_metadata	(	bg_msg_t *	msg,
		int	arg,
		bg_metadata_t *	m
	)

Get a matadata argument.

Parameters:

msg	A message
arg	Argument index (starting with 0)
m	Returns metadata

Don't pass uninitalized memory as metadata.

int bg_msg_read	(	bg_msg_t *	ret,
		bg_msg_read_callback_t	cb,
		void *	cb_data
	)

Read a message using a callback.

Parameters:

ret	Where the message will be copied
cb	read callback
cb_data	data to pass to the callback

Returns:: 1 on success, 0 on error

int bg_msg_write	(	bg_msg_t *	msg,
		bg_msg_write_callback_t	cb,
		void *	cb_data
	)

Write a message using a callback.

Parameters:

msg	A message
cb	write callback
cb_data	data to pass to the callback

Returns:: 1 on success, 0 on error

int bg_msg_read_socket	(	bg_msg_t *	ret,
		int	fd,
		int	milliseconds
	)

Read a message from a socket.

Parameters:

ret	Where the message will be copied
fd	A socket
milliseconds	Read timeout

Returns:: 1 on success, 0 on error

int bg_msg_write_socket	(	bg_msg_t *	msg,
		int	fd
	)

Write a message to a socket.

Parameters:

msg	Message
fd	A socket

Returns:: 1 on success, 0 on error

int bg_msg_write_audio_frame	(	bg_msg_t *	msg,
		const gavl_audio_format_t *	format,
		const gavl_audio_frame_t *	frame,
		bg_msg_write_callback_t	cb,
		void *	cb_data
	)

Write an audio frame.

Parameters:

msg	Message to use for communication
format	An audio format
frame	An audio frame
cb	Callback
cb_data	Data to pass to callback

Returns:: 1 on success, 0 on error

Note, that the format must be transferred separately

int bg_msg_read_audio_frame	(	gavl_dsp_context_t *	ctx,
		bg_msg_t *	msg,
		const gavl_audio_format_t *	format,
		gavl_audio_frame_t *	frame,
		bg_msg_read_callback_t	cb,
		void *	cb_data,
		int	big_endian
	)

Read an audio frame.

Parameters:

ctx	A gavl dsp context
msg	Message containing the frame header
format	Audio format
frame	An audio frame
cb	Callback
cb_data	Data to pass to callback

Returns:: 1 on success, 0 on error

Before you can use this function, msg must contain a valid audio frame header. The DSP context is needed to convert the endianess if necessary.

void bg_msg_set_parameter	(	bg_msg_t *	msg,
		const char *	name,
		bg_parameter_type_t	type,
		const bg_parameter_value_t *	val
	)

Set a parameter.

Parameters:

msg	A message
type	Type of the parameter
name	Name of the parameter
val	Value for the parameter

void bg_msg_get_parameter	(	bg_msg_t *	msg,
		char **	name,
		bg_parameter_type_t *	type,
		bg_parameter_value_t *	val
	)

Get a parameter.

Parameters:

msg	A message
type	Type of the parameter
name	Name of the parameter
val	Value for the parameter

Name and val must be freef if no longer used

Messages

Modules

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation