gmerlin
Modules | Macros | Typedefs | Functions
Messages

Communication inside and between applications. More...

Modules

 Message queues
 Thread save message queues.
 
 Lists of message queues
 Send messages to multiple message queues.
 

Macros

#define BG_MSG_NONE   -1
 Reserved ID for non valid message. More...
 
#define BG_MSG_MAX_ARGS   4
 Maximum number of args. More...
 

Typedefs

typedef struct bg_msg_s bg_msg_t
 Opaque message type, you don't want to know what's inside. More...
 
typedef int(* bg_msg_read_callback_t )(void *priv, uint8_t *data, int len)
 Callback for bg_msg_read. More...
 
typedef int(* bg_msg_write_callback_t )(void *priv, const uint8_t *data, int len)
 Callback for bg_msg_write. More...
 

Functions

bg_msg_tbg_msg_create ()
 Create a message. More...
 
void bg_msg_destroy (bg_msg_t *msg)
 Destroy a message. More...
 
void bg_msg_free (bg_msg_t *msg)
 Free internal memory of the message. More...
 
void bg_msg_set_id (bg_msg_t *msg, int id)
 Set the ID of a message. More...
 
int bg_msg_get_id (bg_msg_t *msg)
 Get the ID of a message. More...
 
void bg_msg_set_arg_int (bg_msg_t *msg, int arg, int value)
 Set an integer argument. More...
 
int bg_msg_get_arg_int (bg_msg_t *msg, int arg)
 Get an integer argument. More...
 
void bg_msg_set_arg_time (bg_msg_t *msg, int arg, gavl_time_t value)
 Set a time argument. More...
 
gavl_time_t bg_msg_get_arg_time (bg_msg_t *msg, int arg)
 Get a time argument. More...
 
void bg_msg_set_arg_string (bg_msg_t *msg, int arg, const char *value)
 Set a string argument. More...
 
char * bg_msg_get_arg_string (bg_msg_t *msg, int arg)
 Get a string argument. More...
 
void bg_msg_set_arg_float (bg_msg_t *msg, int arg, double value)
 Set a float argument. More...
 
double bg_msg_get_arg_float (bg_msg_t *msg, int arg)
 Get a float argument. More...
 
void bg_msg_set_arg_color_rgb (bg_msg_t *msg, int arg, const float *value)
 Set an RGB color argument. More...
 
void bg_msg_get_arg_color_rgb (bg_msg_t *msg, int arg, float *value)
 Get an RGB color argument. More...
 
void bg_msg_set_arg_color_rgba (bg_msg_t *msg, int arg, const float *value)
 Set an RGBA color argument. More...
 
void bg_msg_get_arg_color_rgba (bg_msg_t *msg, int arg, float *value)
 Get an RGBA color argument. More...
 
void bg_msg_set_arg_position (bg_msg_t *msg, int arg, const double *value)
 Set a position argument. More...
 
void bg_msg_get_arg_position (bg_msg_t *msg, int arg, double *value)
 Get a position argument. More...
 
void * bg_msg_set_arg_ptr (bg_msg_t *msg, int arg, int len)
 Set a binary data argument. More...
 
void * bg_msg_get_arg_ptr (bg_msg_t *msg, int arg, int *len)
 Set a binary data argument. More...
 
void bg_msg_set_arg_ptr_nocopy (bg_msg_t *msg, int arg, void *ptr)
 Set a pointer argument without copying data. More...
 
void * bg_msg_get_arg_ptr_nocopy (bg_msg_t *msg, int arg)
 Get a pointer argument without copying data. More...
 
void bg_msg_set_arg_audio_format (bg_msg_t *msg, int arg, const gavl_audio_format_t *format)
 Set an audio format argument. More...
 
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. More...
 
void bg_msg_set_arg_video_format (bg_msg_t *msg, int arg, const gavl_video_format_t *format)
 Set a video format argument. More...
 
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. More...
 
void bg_msg_set_arg_metadata (bg_msg_t *msg, int arg, const gavl_metadata_t *m)
 Set a matadata argument. More...
 
void bg_msg_get_arg_metadata (bg_msg_t *msg, int arg, gavl_metadata_t *m)
 Get a matadata argument. More...
 
int bg_msg_read (bg_msg_t *ret, bg_msg_read_callback_t cb, void *cb_data)
 Read a message using a callback. More...
 
int bg_msg_write (bg_msg_t *msg, bg_msg_write_callback_t cb, void *cb_data)
 Write a message using a callback. More...
 
int bg_msg_read_socket (bg_msg_t *ret, int fd, int milliseconds)
 Read a message from a socket. More...
 
int bg_msg_write_socket (bg_msg_t *msg, int fd)
 Write a message to a socket. More...
 
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. More...
 
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. More...
 
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. More...
 
void bg_msg_get_parameter (bg_msg_t *msg, char **name, bg_parameter_type_t *type, bg_parameter_value_t *val)
 Get a parameter. More...
 

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)

Macro Definition 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
privThe private data you passed to bg_msg_read
dataA buffer
lenNumber 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
privThe private data you passed to bg_msg_write
dataA buffer
lenNumber 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
msgA message
void bg_msg_free ( bg_msg_t msg)

Free internal memory of the message.

Parameters
msgA 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
msgA message
idThe ID
int bg_msg_get_id ( bg_msg_t msg)

Get the ID of a message.

Parameters
msgA message
Returns
The ID
void bg_msg_set_arg_int ( bg_msg_t msg,
int  arg,
int  value 
)

Set an integer argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
int bg_msg_get_arg_int ( bg_msg_t msg,
int  arg 
)

Get an integer argument.

Parameters
msgA message
argArgument 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
msgA message
argArgument index (starting with 0)
valueValue
gavl_time_t bg_msg_get_arg_time ( bg_msg_t msg,
int  arg 
)

Get a time argument.

Parameters
msgA message
argArgument 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
msgA message
argArgument index (starting with 0)
valueValue
char* bg_msg_get_arg_string ( bg_msg_t msg,
int  arg 
)

Get a string argument.

Parameters
msgA message
argArgument 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
msgA message
argArgument index (starting with 0)
valueValue
double bg_msg_get_arg_float ( bg_msg_t msg,
int  arg 
)

Get a float argument.

Parameters
msgA message
argArgument 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
msgA message
argArgument index (starting with 0)
valueValue
void bg_msg_get_arg_color_rgb ( bg_msg_t msg,
int  arg,
float *  value 
)

Get an RGB color argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
void bg_msg_set_arg_color_rgba ( bg_msg_t msg,
int  arg,
const float *  value 
)

Set an RGBA color argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
void bg_msg_get_arg_color_rgba ( bg_msg_t msg,
int  arg,
float *  value 
)

Get an RGBA color argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
void bg_msg_set_arg_position ( bg_msg_t msg,
int  arg,
const double *  value 
)

Set a position argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
void bg_msg_get_arg_position ( bg_msg_t msg,
int  arg,
double *  value 
)

Get a position argument.

Parameters
msgA message
argArgument index (starting with 0)
valueValue
void* bg_msg_set_arg_ptr ( bg_msg_t msg,
int  arg,
int  len 
)

Set a binary data argument.

Parameters
msgA message
argArgument index (starting with 0)
lenNumber 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
msgA message
argArgument index (starting with 0)
lenReturns 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
msgA message
argArgument index (starting with 0)
ptrA 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
msgA message
argArgument 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
msgA message
argArgument index (starting with 0)
formatAn 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
msgA message
argArgument index (starting with 0)
formatReturns the audio format
big_endianIf 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
msgA message
argArgument index (starting with 0)
formatA 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
msgA message
argArgument index (starting with 0)
formatReturns the video format
big_endianIf non-null, returns 1 if multibyte numbers are in big endian
void bg_msg_set_arg_metadata ( bg_msg_t msg,
int  arg,
const gavl_metadata_t *  m 
)

Set a matadata argument.

Parameters
msgA message
argArgument index (starting with 0)
mMetadata
void bg_msg_get_arg_metadata ( bg_msg_t msg,
int  arg,
gavl_metadata_t *  m 
)

Get a matadata argument.

Parameters
msgA message
argArgument index (starting with 0)
mReturns 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
retWhere the message will be copied
cbread callback
cb_datadata 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
msgA message
cbwrite callback
cb_datadata 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
retWhere the message will be copied
fdA socket
millisecondsRead 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
msgMessage
fdA 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
msgMessage to use for communication
formatAn audio format
frameAn audio frame
cbCallback
cb_dataData 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
ctxA gavl dsp context
msgMessage containing the frame header
formatAudio format
frameAn audio frame
cbCallback
cb_dataData to pass to callback
big_endian1 if data should be sent in big endian format
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
msgA message
typeType of the parameter
nameName of the parameter
valValue 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
msgA message
typeType of the parameter
nameName of the parameter
valValue for the parameter

Name and val must be freef if no longer used