msg_envelope.h File Reference

Messaging envelope abstraction. More...

#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
#include "eii/msgbus/msgbusret.h"
#include "eii/msgbus/hashmap.h"
#include "eii/msgbus/linkedlist.h"

Go to the source code of this file.

Classes
struct	owned_blob_t
struct	msg_envelope_blob_t
struct	msg_envelope_elem_body_t
struct	msg_envelope_t
struct	msg_envelope_serialized_part_t

Enumerations
enum	content_type_t { CT_JSON = 0, CT_BLOB = 1 }
enum	msg_envelope_data_type_t {   MSG_ENV_DT_INT = 0, MSG_ENV_DT_FLOATING = 1, MSG_ENV_DT_STRING = 2, MSG_ENV_DT_BOOLEAN = 3,   MSG_ENV_DT_BLOB = 4, MSG_ENV_DT_OBJECT = 5, MSG_ENV_DT_ARRAY = 6, MSG_ENV_DT_NONE = 7 }

Functions
msg_envelope_t *	msgbus_msg_envelope_new (content_type_t ct)
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_none ()
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_array ()
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_object ()
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_string (const char *string)
msgbus_ret_t	msgbus_msg_envelope_put_string (msg_envelope_t *obj, const char *key, const char *value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_integer (int64_t integer)
msgbus_ret_t	msgbus_msg_envelope_put_integer (msg_envelope_t *obj, const char *key, int64_t value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_floating (double floating)
msgbus_ret_t	msgbus_msg_envelope_put_float (msg_envelope_t *obj, const char *key, double value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_bool (bool boolean)
msgbus_ret_t	msgbus_msg_envelope_put_bool (msg_envelope_t *obj, const char *key, bool value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_new_blob (char *data, size_t len)
msgbus_ret_t	msgbus_msg_envelope_elem_object_put (msg_envelope_elem_body_t *obj, const char *key, msg_envelope_elem_body_t *value)
msgbus_ret_t	msgbus_msg_envelope_elem_object_put_integer (msg_envelope_elem_body_t *obj, const char *key, int64_t value)
msgbus_ret_t	msgbus_msg_envelope_elem_object_put_string (msg_envelope_elem_body_t *obj, const char *key, const char *value)
msgbus_ret_t	msgbus_msg_envelope_elem_object_put_float (msg_envelope_elem_body_t *obj, const char *key, double value)
msgbus_ret_t	msgbus_msg_envelope_elem_object_put_bool (msg_envelope_elem_body_t *obj, const char *key, bool value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_elem_object_get (msg_envelope_elem_body_t *obj, const char *key)
msgbus_ret_t	msgbus_msg_envelope_elem_object_remove (msg_envelope_elem_body_t *obj, const char *key)
msgbus_ret_t	msgbus_msg_envelope_elem_array_add (msg_envelope_elem_body_t *arr, msg_envelope_elem_body_t *value)
msgbus_ret_t	msgbus_msg_envelope_elem_array_add_integer (msg_envelope_elem_body_t *arr, int64_t value)
msgbus_ret_t	msgbus_msg_envelope_elem_array_add_string (msg_envelope_elem_body_t *arr, const char *value)
msgbus_ret_t	msgbus_msg_envelope_elem_array_add_float (msg_envelope_elem_body_t *arr, double value)
msgbus_ret_t	msgbus_msg_envelope_elem_array_add_bool (msg_envelope_elem_body_t *arr, bool value)
msg_envelope_elem_body_t *	msgbus_msg_envelope_elem_array_get_at (msg_envelope_elem_body_t *arr, int idx)
msgbus_ret_t	msgbus_msg_envelope_elem_array_remove_at (msg_envelope_elem_body_t *arr, int idx)
void	msgbus_msg_envelope_elem_destroy (msg_envelope_elem_body_t *elem)
msgbus_ret_t	msgbus_msg_envelope_put (msg_envelope_t *env, const char *key, msg_envelope_elem_body_t *data)
msgbus_ret_t	msgbus_msg_envelope_remove (msg_envelope_t *env, const char *key)
msgbus_ret_t	msgbus_msg_envelope_get (msg_envelope_t *env, const char *key, msg_envelope_elem_body_t **data)
int	msgbus_msg_envelope_serialize (msg_envelope_t *env, msg_envelope_serialized_part_t **parts)
msgbus_ret_t	msgbus_msg_envelope_deserialize (content_type_t ct, msg_envelope_serialized_part_t *parts, int num_parts, const char *name, msg_envelope_t **env)
msgbus_ret_t	msgbus_msg_envelope_serialize_parts_new (int num_parts, msg_envelope_serialized_part_t **parts)
void	msgbus_msg_envelope_serialize_destroy (msg_envelope_serialized_part_t *parts, int num_parts)
void	msgbus_msg_envelope_print (msg_envelope_t *msg, bool pretty_print, bool print_blobs)
void	msgbus_msg_envelope_destroy (msg_envelope_t *msg)
owned_blob_t *	owned_blob_new (void *ptr, void(*free_fn)(void *), const char *data, size_t len)
owned_blob_t *	owned_blob_copy (owned_blob_t *to_copy)
void	owned_blob_destroy (owned_blob_t *shared)

Detailed Description

Messaging envelope abstraction.

Enumeration Type Documentation

content_type_t

enum content_type_t

Content types

msg_envelope_data_type_t

enum msg_envelope_data_type_t

Message envelope value data types.

Function Documentation

msgbus_msg_envelope_deserialize()

msgbus_ret_t msgbus_msg_envelope_deserialize	(	content_type_t	ct,
		msg_envelope_serialized_part_t *	parts,
		int	num_parts,
		const char *	name,
		msg_envelope_t **	env
	)

Deserialize the given data into a msg_envelope_t.

If the content type is set to CT_BLOB, then this method assumes that there will only be one serialized message part.

Additionally, if the content type is CT_JSON, then this method assumes that there will be either one or two message parts. The first part MUST always be a JSON string. If a second part is present it MUST be a binary blob of data.

Parameters

[in]	ct	- Message content type
[in]	parts	- Serialized parts to deserailize
[in]	num_parts	- Number of message parts
[in]	name	- Topic name
[out]	env	- Output message envelope

Returns

msgbus_ret_t

msgbus_msg_envelope_destroy()

void msgbus_msg_envelope_destroy

(

msg_envelope_t *

msg

)

Delete and clean up a message envelope structure.

Parameters

msg	- Message envelope to delete

msgbus_msg_envelope_elem_array_add()

msgbus_ret_t msgbus_msg_envelope_elem_array_add	(	msg_envelope_elem_body_t *	arr,
		msg_envelope_elem_body_t *	value
	)

Add item to the msg envelope array element.

Parameters

arr	- Array to add the element to
value	- Element to add

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_array_add_bool()

msgbus_ret_t msgbus_msg_envelope_elem_array_add_bool	(	msg_envelope_elem_body_t *	arr,
		bool	value
	)

Add boolean to the msg envelope array element.

Parameters

arr	- Array to add the element to
value	- Element to add

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_array_add_float()

msgbus_ret_t msgbus_msg_envelope_elem_array_add_float	(	msg_envelope_elem_body_t *	arr,
		double	value
	)

Add float to the msg envelope array element.

Parameters

arr	- Array to add the element to
value	- Element to add

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_array_add_integer()

msgbus_ret_t msgbus_msg_envelope_elem_array_add_integer	(	msg_envelope_elem_body_t *	arr,
		int64_t	value
	)

Add integer to the msg envelope array element.

Parameters

arr	- Array to add the element to
value	- integer to add

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_array_add_string()

msgbus_ret_t msgbus_msg_envelope_elem_array_add_string	(	msg_envelope_elem_body_t *	arr,
		const char *	value
	)

Add string to the msg envelope array element.

Parameters

arr	- Array to add the element to
value	- Element to add

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_array_get_at()

msg_envelope_elem_body_t* msgbus_msg_envelope_elem_array_get_at	(	msg_envelope_elem_body_t *	arr,
		int	idx
	)

Get item in the msg envelope array element.

Parameters

arr	- Array to remove the element from
idx	- Index of the item to get

Returns

msg_envelope_elem_body_t, or NULL if an error occurs

msgbus_msg_envelope_elem_array_remove_at()

msgbus_ret_t msgbus_msg_envelope_elem_array_remove_at	(	msg_envelope_elem_body_t *	arr,
		int	idx
	)

Remove item to the msg envelope array element.

Parameters

arr	- Array to remove the element from
value	- Element to remove

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_destroy()

void msgbus_msg_envelope_elem_destroy

(

msg_envelope_elem_body_t *

elem

)

Helper function to destroy a message envelope element.

Parameters

elem	- Element to destroy

msgbus_msg_envelope_elem_object_get()

msg_envelope_elem_body_t* msgbus_msg_envelope_elem_object_get	(	msg_envelope_elem_body_t *	obj,
		const char *	key
	)

Get value from a message envelope nested object.

Parameters

obj	- Message envelope object element to retrieve value from
key	- Key of the value to retrieve

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_elem_object_put()

msgbus_ret_t msgbus_msg_envelope_elem_object_put	(	msg_envelope_elem_body_t *	obj,
		const char *	key,
		msg_envelope_elem_body_t *	value
	)

Put a new (key, value) pair into a message envelope nested object.

Parameters

obj	- Message envelope object element to add the (key, value) pair to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_object_put_bool()

msgbus_ret_t msgbus_msg_envelope_elem_object_put_bool	(	msg_envelope_elem_body_t *	obj,
		const char *	key,
		bool	value
	)

Put a new bool into a message envelope nested object.

Parameters

obj	- Message envelope object element to add the bool to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_object_put_float()

msgbus_ret_t msgbus_msg_envelope_elem_object_put_float	(	msg_envelope_elem_body_t *	obj,
		const char *	key,
		double	value
	)

Put a new float into a message envelope nested object.

Parameters

obj	- Message envelope object element to add the float to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_object_put_integer()

msgbus_ret_t msgbus_msg_envelope_elem_object_put_integer	(	msg_envelope_elem_body_t *	obj,
		const char *	key,
		int64_t	value
	)

Put a new integer into a message envelope nested object.

Parameters

obj	- Message envelope object element to add the integer to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_object_put_string()

msgbus_ret_t msgbus_msg_envelope_elem_object_put_string	(	msg_envelope_elem_body_t *	obj,
		const char *	key,
		const char *	value
	)

Put a new string into a message envelope nested object.

Parameters

obj	- Message envelope object element to add the string to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_elem_object_remove()

msgbus_ret_t msgbus_msg_envelope_elem_object_remove	(	msg_envelope_elem_body_t *	obj,
		const char *	key
	)

Remove (key, value) pair from the message envelope nested object.

Parameters

obj	- Message envelope object element to remove element from
key	- Key to remove

Returns

msgbus_ret_t

msgbus_msg_envelope_get()

msgbus_ret_t msgbus_msg_envelope_get	(	msg_envelope_t *	env,
		const char *	key,
		msg_envelope_elem_body_t **	data
	)

Get the value for the given key in the message bus.

Note

{If the content type is CT_BLOB, then use "BLOB" as the key to retrieve the blob data.}

Parameters

[in]	env	- Message envelope
[in]	key	- Key for the element to find
[out]	data	- Data for the key

Returns

msgbus_ret_t

msgbus_msg_envelope_new()

msg_envelope_t* msgbus_msg_envelope_new

(

content_type_t

ct

)

Create a new msg_envelope_t to be sent over the message bus.

Parameters

ct	- Content type

Returns

msg_envelope_t, or NULL if an error occurs

msgbus_msg_envelope_new_array()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_array

(

)

Create a new array element to be added to a message envelope.

Returns

msg_envelope_elem_body_t, or NULL if errors occur

msgbus_msg_envelope_new_blob()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_blob	(	char *	data,
		size_t	len
	)

Helper function for creating a new message envelope element containing a data blob.

Note

The enevelope element takes ownership of releasing the data.

Parameters

blob	- Blob data to be placed in the envelope element
len	- Size of the data blob

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_new_bool()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_bool

(

bool

boolean

)

Helper function for creating a new message envelope element containing a boolean value.

Parameters

boolean

- Boolean value to be placed in the envelope element

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_new_floating()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_floating

(

double

floating

)

Helper function for creating a new message envelope element containing a floating point value.

Parameters

floating

- Floating point value to be placed in the envelope element

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_new_integer()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_integer

(

int64_t

integer

)

Helper function for creating a new message envelope element containing an integer value.

Parameters

integer

- Integer value to be placed in the envelope element

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_new_none()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_none

(

)

Create a new empty msg envelope element.

Returns

msg_envelope_elem_body_t, or NULL if errors occur

msgbus_msg_envelope_new_object()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_object

(

)

Create a new nested object to be added to a message envelope, array, or other object.

Returns

msg_envelope_elem_body_t, or NULL if errors occur

msgbus_msg_envelope_new_string()

msg_envelope_elem_body_t* msgbus_msg_envelope_new_string

(

const char *

string

)

Helper function for creating a new message envelope element containing a string value.

Parameters

string

- String value to be placed in the envelope element

Returns

msg_envelope_body_t, or NULL if errors occur

msgbus_msg_envelope_print()

void msgbus_msg_envelope_print	(	msg_envelope_t *	msg,
		bool	pretty_print,
		bool	print_blobs
	)

Helper method to log the contents of a message envlope.

Note

This method has performance impact. Use sparingly and ideally for debug purposes only.

If told to print blobs, keep in mind that this can be very bad output at times (binary is not pretty).

This will print to stderr.

Parameters

msg	- msg_envelope_t* to print
pretty_print	- Print JSON data unflattend
print_blobs	- If blobs are present in the message, print them

msgbus_msg_envelope_put()

msgbus_ret_t msgbus_msg_envelope_put	(	msg_envelope_t *	env,
		const char *	key,
		msg_envelope_elem_body_t *	data
	)

Add (key, value) pair to the message envelope.

Note

{If the message envelope is set to be a CT_BLOB, then it will act differently than a message set to a different content type. For a blob the data can only be set once for the message and the key value will be ignored and the key BLOB will be used. Additionally, the value body must be a blob as well.}

Parameters

env	- Message envelope
key	- Key for the value
data	- Value to be added

Returns

msgbus_ret_t

msgbus_msg_envelope_put_bool()

msgbus_ret_t msgbus_msg_envelope_put_bool	(	msg_envelope_t *	obj,
		const char *	key,
		bool	value
	)

Put a new bool value into a message envelope object.

Parameters

obj	- Message envelope element to add the bool value to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_put_float()

msgbus_ret_t msgbus_msg_envelope_put_float	(	msg_envelope_t *	obj,
		const char *	key,
		double	value
	)

Put a new floating value into a message envelope object.

Parameters

obj	- Message envelope element to add the float value to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_put_integer()

msgbus_ret_t msgbus_msg_envelope_put_integer	(	msg_envelope_t *	obj,
		const char *	key,
		int64_t	value
	)

Put a new integer into a message envelope object.

Parameters

obj	- Message envelope element to add the integer to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_put_string()

msgbus_ret_t msgbus_msg_envelope_put_string	(	msg_envelope_t *	obj,
		const char *	key,
		const char *	value
	)

Put a new string into a message envelope object.

Parameters

obj	- Message envelope element to add the string to
key	- Key for the value
value	- Value associated to the key

Returns

msgbus_ret_t

msgbus_msg_envelope_remove()

msgbus_ret_t msgbus_msg_envelope_remove	(	msg_envelope_t *	env,
		const char *	key
	)

Remove the (key, value) pair with the given key.

Parameters

env	- Message envelope
key	- Key to remove

Returns

msgbus_ret_t

msgbus_msg_envelope_serialize()

int msgbus_msg_envelope_serialize	(	msg_envelope_t *	env,
		msg_envelope_serialized_part_t **	parts
	)

Serialize the data in the envelope into the given message parts buffer based on the content type given when msgbus_msg_envelope_new() was called.

Parameters

[in]	env	- Message envelope
[out]	parts	- Serialized parts

Returns

Number of serialized message parts

msgbus_msg_envelope_serialize_destroy()

void msgbus_msg_envelope_serialize_destroy	(	msg_envelope_serialized_part_t *	parts,
		int	num_parts
	)

Destroy the serialized parts of a message

Parameters

parts	- Serialized parts
num_parts	- Number of serialized parts

Returns

msgbus_ret_t

msgbus_msg_envelope_serialize_parts_new()

msgbus_ret_t msgbus_msg_envelope_serialize_parts_new	(	int	num_parts,
		msg_envelope_serialized_part_t **	parts
	)

Create a new list of serialized message parts.

Parameters

[in]	num_parts	- Number of serialized message parts
[out]	parts	- Serialzied parts

Returns

msgbus_ret_t

owned_blob_copy()

owned_blob_t* owned_blob_copy

(

owned_blob_t *

to_copy

)

Copy a shared blob, except assume the underlying data is NOT owned by the copy of the blob.

owned_blob_destroy()

void owned_blob_destroy

(

owned_blob_t *

shared

)

Helper for destroying owned blob pointer.

owned_blob_new()

owned_blob_t* owned_blob_new	(	void *	ptr,
		void(*)(void *)	free_fn,
		const char *	data,
		size_t	len
	)

Helper for initializing owned blob pointer.

Note

Assumes data is owned