A memory description (memdesc) allows code to know how to handle it in runtime, such as decode/parse from some other representation (text/json), or serialize/encode. More...

Data Structures
struct	sol_memdesc
	Data type to describe a memory region. More...

struct	sol_memdesc_ops
	override operations to be used in this memory description. More...

struct	sol_memdesc_ops_array
	Operations specific to SOL_MEMDESC_TYPE_ARRAY. More...

struct	sol_memdesc_ops_enumeration
	Operations specific to SOL_MEMDESC_TYPE_ENUMERATION. More...

struct	sol_memdesc_serialize_options
	Options on how to serialize a memory given its description. More...

struct	sol_memdesc_structure_member
	Description of a structure member. More...

Macros
#define	_SOL_MEMDESC_CHECK(desc) ((desc) && _SOL_MEMDESC_CHECK_API_VERSION(desc) && (desc)->type != SOL_MEMDESC_TYPE_UNKNOWN)
	Helper to check for a valid struct sol_memdesc. More...

#define	_SOL_MEMDESC_CHECK_API_VERSION(desc) ((desc)->api_version == SOL_MEMDESC_API_VERSION_COMPILED)
	Helper to check api-version if needed. More...

#define	_SOL_MEMDESC_CHECK_STRUCTURE(structure_desc) (_SOL_MEMDESC_CHECK(structure_desc) && (structure_desc)->structure_members && _SOL_MEMDESC_CHECK(&((structure_desc)->structure_members->base)))
	Helper to check for a valid struct sol_memdesc of type SOL_MEMDESC_TYPE_STRUCTURE. More...

#define	_SOL_MEMDESC_CHECK_STRUCTURE_MEMBER(structure_desc, member_desc)
	Helper to check for a valid struct sol_memdesc of type SOL_MEMDESC_TYPE_STRUCTURE and if member is within structure boundaries. More...

#define	SOL_MEMDESC_DESCRIPTION
	This is selected at compile time to allow reducing binary size if this cpp symbol is undefined. More...

#define	SOL_MEMDESC_FOREACH_ARRAY_ELEMENT_IN_RANGE(desc, memory, start_idx, end_idx, itr_idx, element)
	Macro to loop of array elements in a given range. More...

#define	SOL_MEMDESC_FOREACH_STRUCTURE_MEMBER(structure_desc, member_desc)
	Macro to loop over all structure members. More...

#define	SOL_MEMDESC_FOREACH_STRUCTURE_MEMBER_MEMORY(structure_desc, member_desc, structure_memory, member_memory)
	Macro to loop over all structure members and associated memory. More...

#define	SOL_MEMDESC_SET_DESCRIPTION(...)
	Helper to set the description member of struct sol_memdesc if that is available (conditional to SOL_MEMDESC_SET_DESCRIPTION). More...

Typedefs
typedef struct sol_memdesc	sol_memdesc
	Data type to describe a memory region. More...

typedef struct sol_memdesc_ops	sol_memdesc_ops
	override operations to be used in this memory description. More...

typedef struct sol_memdesc_ops_array	sol_memdesc_ops_array
	Operations specific to SOL_MEMDESC_TYPE_ARRAY. More...

typedef struct sol_memdesc_ops_enumeration	sol_memdesc_ops_enumeration
	Operations specific to SOL_MEMDESC_TYPE_ENUMERATION. More...

typedef struct sol_memdesc_serialize_options	sol_memdesc_serialize_options
	Options on how to serialize a memory given its description. More...

typedef struct sol_memdesc_structure_member	sol_memdesc_structure_member
	Description of a structure member. More...

Enumerations
enum	sol_memdesc_type { SOL_MEMDESC_TYPE_UNKNOWN = 0, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_ULONG, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_ARRAY }
	Designates the type of the memory description. More...

Functions
static int	sol_memdesc_append_array_element (const struct sol_memdesc array_desc, void memory, const void *ptr_content)
	Append the array element. More...

int	sol_memdesc_compare (const struct sol_memdesc desc, const void a_memory, const void *b_memory)
	compare two memories using the given description. More...

int	sol_memdesc_copy (const struct sol_memdesc desc, const void src_memory, void *dst_memory)
	copy the memory using the given description. More...

int	sol_memdesc_enumeration_from_str (const struct sol_memdesc enumeration, void ptr_return, const struct sol_str_slice str)
	convert enumeration value from string. More...

const char *	sol_memdesc_enumeration_to_str (const struct sol_memdesc enumeration, const void memory)
	convert enumeration value to string. More...

static const struct sol_memdesc_structure_member *	sol_memdesc_find_structure_member (const struct sol_memdesc *structure_desc, struct sol_str_slice name)
	Find structure member given its name. More...

static void	sol_memdesc_free (const struct sol_memdesc desc, void memory)
	Free the contents and the memory. More...

int	sol_memdesc_free_content (const struct sol_memdesc desc, void memory)
	free the contents (internal memory) of a member. More...

void *	sol_memdesc_get_array_element (const struct sol_memdesc array_desc, const void memory, size_t idx)
	Get the array element. More...

ssize_t	sol_memdesc_get_array_length (const struct sol_memdesc array_desc, const void memory)
	Get the length of an array. More...

static int64_t	sol_memdesc_get_as_int64 (const struct sol_memdesc desc, const void memory)
	Helper to fetch the memory as the largest supported signed integer. More...

static uint64_t	sol_memdesc_get_as_uint64 (const struct sol_memdesc desc, const void memory)
	Helper to fetch the memory as the largest supported unsigned integer. More...

static uint16_t	sol_memdesc_get_size (const struct sol_memdesc *desc)
	get the size in bytes of the memory description. More...

static void *	sol_memdesc_get_structure_member_memory (const struct sol_memdesc structure_desc, const struct sol_memdesc_structure_member member_desc, const void *structure_memory)
	get the pointer to the struct member memory description inside the given container. More...

int	sol_memdesc_init_defaults (const struct sol_memdesc desc, void memory)
	initialize the memory. More...

static bool	sol_memdesc_is_signed_integer (const struct sol_memdesc *desc)
	Helper to check if type is signed integer-compatible. More...

static bool	sol_memdesc_is_unsigned_integer (const struct sol_memdesc *desc)
	Helper to check if type is unsigned integer-compatible. More...

static void *	sol_memdesc_new_with_defaults (const struct sol_memdesc *desc)
	Allocate the memory required by this description and initialize it. More...

int	sol_memdesc_resize_array (const struct sol_memdesc array_desc, void memory, size_t length)
	Resize the length of an array. More...

int	sol_memdesc_serialize (const struct sol_memdesc desc, const void memory, struct sol_buffer buffer, const struct sol_memdesc_serialize_options opts, struct sol_buffer *prefix)
	Serialize a memory to a buffer using a description. More...

static int64_t	sol_memdesc_set_as_int64 (const struct sol_memdesc desc, void memory, int64_t value)
	Helper to set the memory as the largest supported signed integer. More...

static int	sol_memdesc_set_as_uint64 (const struct sol_memdesc desc, void memory, uint64_t value)
	Helper to set the memory as the largest supported unsigned integer. More...

int	sol_memdesc_set_content (const struct sol_memdesc desc, void memory, const void *ptr_content)
	set the content of this memory. More...

enum sol_memdesc_type	sol_memdesc_type_from_str (const char *str)
	Converts a Memdesc Type from string to sol_memdesc_type. More...

const char *	sol_memdesc_type_to_str (enum sol_memdesc_type type)
	Converts a sol_memdesc_type to a string. More...

Variables
const uint16_t	SOL_MEMDESC_API_VERSION_COMPILED
	the SOL_MEMDESC_API_VERSION this soletta build used. More...

const struct sol_memdesc_ops	SOL_MEMDESC_OPS_PTR_VECTOR
	operations to handle struct sol_ptr_vector. More...

const struct sol_memdesc_ops	SOL_MEMDESC_OPS_VECTOR
	operations to handle struct sol_vector. More...

const struct sol_memdesc_serialize_options	SOL_MEMDESC_SERIALIZE_OPTIONS_DEFAULT
	the default struct sol_memdesc_serialize_options. More...

Detailed Description

A memory description (memdesc) allows code to know how to handle it in runtime, such as decode/parse from some other representation (text/json), or serialize/encode.

It will, as well, offer special handling such as memory being duplicated and freed for strings, or defined per-description with struct sol_memdesc::ops.

Macro Definition Documentation

#define _SOL_MEMDESC_CHECK ( desc ) ((desc) && _SOL_MEMDESC_CHECK_API_VERSION(desc) && (desc)->type != SOL_MEMDESC_TYPE_UNKNOWN)

Helper to check for a valid struct sol_memdesc.

#define _SOL_MEMDESC_CHECK_API_VERSION ( desc ) ((desc)->api_version == SOL_MEMDESC_API_VERSION_COMPILED)

Helper to check api-version if needed.

#define _SOL_MEMDESC_CHECK_STRUCTURE ( structure_desc ) (_SOL_MEMDESC_CHECK(structure_desc) && (structure_desc)->structure_members && _SOL_MEMDESC_CHECK(&((structure_desc)->structure_members->base)))

Helper to check for a valid struct sol_memdesc of type SOL_MEMDESC_TYPE_STRUCTURE.

#define _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER	(	structure_desc,
		member_desc
	)

Value:

(_SOL_MEMDESC_CHECK(&(member_desc)->base) && \

((member_desc)->offset + sol_memdesc_get_size(&(member_desc)->base) <= sol_memdesc_get_size((structure_desc))))

sol_memdesc_get_size

static uint16_t sol_memdesc_get_size(const struct sol_memdesc *desc)

get the size in bytes of the memory description.

Definition: sol-memdesc.h:697

_SOL_MEMDESC_CHECK

#define _SOL_MEMDESC_CHECK(desc)

Helper to check for a valid struct sol_memdesc.

Definition: sol-memdesc.h:1041

Helper to check for a valid struct sol_memdesc of type SOL_MEMDESC_TYPE_STRUCTURE and if member is within structure boundaries.

Parameters

structure_desc	the memory description of type SOL_MEMDESC_TYPE_STRUCTURE
member_desc	the struct sol_memdesc_structure_member to check.

#define SOL_MEMDESC_DESCRIPTION

This is selected at compile time to allow reducing binary size if this cpp symbol is undefined.

#define SOL_MEMDESC_FOREACH_ARRAY_ELEMENT_IN_RANGE	(	desc,
		memory,
		start_idx,
		end_idx,
		itr_idx,
		element
	)

Value:

for (itr_idx = start_idx, \
        element = (itr_idx < end_idx) ? sol_memdesc_get_array_element((desc), (memory), itr_idx) : NULL; \
        itr_idx < end_idx && element; \
        itr_idx++, \
        element = (itr_idx < end_idx) ? sol_memdesc_get_array_element((desc), (memory), itr_idx) : NULL)

Macro to loop of array elements in a given range.

Parameters

desc	the memory description of type SOL_MEMDESC_TYPE_ARRAY.
memory	the memory holding the array.
start_idx	the starting index (inclusive).
end_idx	the ending index (non-inclusive, up to it).
itr_idx	where to store the current iteration index.
element	where to store the element or NULL on last iteration.

#define SOL_MEMDESC_FOREACH_STRUCTURE_MEMBER	(	structure_desc,
		member_desc
	)

Value:

for (member_desc = (_SOL_MEMDESC_CHECK_STRUCTURE((structure_desc)) && _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), (structure_desc)->structure_members)) ? (structure_desc)->structure_members : NULL; \
        _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), member_desc); \
        member_desc = _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), member_desc + 1) ? member_desc + 1 : NULL)

Macro to loop over all structure members.

Parameters

structure_desc	the memory description of type SOL_MEMDESC_TYPE_STRUCTURE
member_desc	where to store the struct sol_memdesc_structure_member. NULL when iteration ends.

Referenced by sol_memdesc_find_structure_member().

#define SOL_MEMDESC_FOREACH_STRUCTURE_MEMBER_MEMORY	(	structure_desc,
		member_desc,
		structure_memory,
		member_memory
	)

Value:

for (member_desc = (_SOL_MEMDESC_CHECK_STRUCTURE((structure_desc)) && _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), (structure_desc)->structure_members)) ? (structure_desc)->structure_members : NULL, \
        member_memory = member_desc ? sol_memdesc_get_structure_member_memory((structure_desc), member_desc, (structure_memory)) : NULL; \
        _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), member_desc) && member_memory; \
        member_desc = _SOL_MEMDESC_CHECK_STRUCTURE_MEMBER((structure_desc), member_desc + 1) ? member_desc + 1 : NULL, \
        member_memory = member_desc ? sol_memdesc_get_structure_member_memory((structure_desc), member_desc, (structure_memory)) : NULL)

Macro to loop over all structure members and associated memory.

Parameters

structure_desc	the memory description of type SOL_MEMDESC_TYPE_STRUCTURE
member_desc	where to store the struct sol_memdesc_structure_member. NULL when iteration ends.
structure_memory	the memory of the container structure.
member_memory	where to store the element memory.

#define SOL_MEMDESC_SET_DESCRIPTION ( ... )

Helper to set the description member of struct sol_memdesc if that is available (conditional to SOL_MEMDESC_SET_DESCRIPTION).

It takes C statements and conditionally uses or eliminates them.

Typedef Documentation

typedef struct sol_memdesc sol_memdesc

Data type to describe a memory region.

typedef struct sol_memdesc_ops sol_memdesc_ops

override operations to be used in this memory description.

By default the operations will be done in a fixed way unless overriden by an ops structure, this may be used to correlate members in a structure, such as struct sol_vector where length is a member and the contents is another, with element_size being specified in yet-another. Then things like "copy" will not be a simple copy of each member.

To map struct sol_vector, use SOL_MEMDESC_OPS_VECTOR. to map struct sol_ptr_vector use SOL_MEMDESC_OPS_PTR_VECTOR.

typedef struct sol_memdesc_ops_array sol_memdesc_ops_array

Operations specific to SOL_MEMDESC_TYPE_ARRAY.

This provides array-specific operations to use when dealing with a memory description.

See Also: struct sol_memdesc_ops; struct sol_memdesc

typedef struct sol_memdesc_ops_enumeration sol_memdesc_ops_enumeration

Operations specific to SOL_MEMDESC_TYPE_ENUMERATION.

This provides enumeration-specific operations to use when dealing with a memory description.

See Also: struct sol_memdesc_ops; struct sol_memdesc

typedef struct sol_memdesc_serialize_options sol_memdesc_serialize_options

Options on how to serialize a memory given its description.

typedef struct sol_memdesc_structure_member sol_memdesc_structure_member

Description of a structure member.

This description extends the base description and adds name, offset and some flags.

See Also: struct sol_memdesc

Enumeration Type Documentation

enum sol_memdesc_type

Designates the type of the memory description.

Enumerator
SOL_MEMDESC_TYPE_UNKNOWN	not to be used.
SOL_MEMDESC_TYPE_UINT8	uint8_t equivalent (one unsigned byte). Initial content is specified in struct sol_memdesc::defcontent::u8.
SOL_MEMDESC_TYPE_UINT16	uint16_t equivalent (two unsigned bytes). Initial content is specified in struct sol_memdesc::defcontent::u16.
SOL_MEMDESC_TYPE_UINT32	uint32_t equivalent (four unsigned bytes). Initial content is specified in struct sol_memdesc::defcontent::u32.
SOL_MEMDESC_TYPE_UINT64	uint64_t equivalent (four unsigned bytes). Initial content is specified in struct sol_memdesc::defcontent::u64.
SOL_MEMDESC_TYPE_ULONG	unsigned long equivalent. Initial content is specified in struct sol_memdesc::defcontent::ul.
SOL_MEMDESC_TYPE_SIZE	size_t equivalent (four or eight unsigned bytes, depends on platform). Initial content is specified in struct sol_memdesc::defcontent::sz.
SOL_MEMDESC_TYPE_INT8	int8_t equivalent (one signed byte). Initial content is specified in struct sol_memdesc::defcontent::i8.
SOL_MEMDESC_TYPE_INT16	int16_t equivalent (two signed bytes). Initial content is specified in struct sol_memdesc::defcontent::i16.
SOL_MEMDESC_TYPE_INT32	int32_t equivalent (four signed bytes). Initial content is specified in struct sol_memdesc::defcontent::i32.
SOL_MEMDESC_TYPE_INT64	int64_t equivalent (eight signed bytes). Initial content is specified in struct sol_memdesc::defcontent::i64.
SOL_MEMDESC_TYPE_LONG	signed long equivalent. Initial content is specified in struct sol_memdesc::defcontent::l.
SOL_MEMDESC_TYPE_SSIZE	ssize_t equivalent (four or eight signed bytes, depends on platform). Initial content is specified in struct sol_memdesc::defcontent::ssz.
SOL_MEMDESC_TYPE_BOOL	boolean equivalent. Initial content is specified in struct sol_memdesc::defcontent::b.
SOL_MEMDESC_TYPE_DOUBLE	double precision floating point equivalent. Initial content is specified in struct sol_memdesc::defcontent::d.
SOL_MEMDESC_TYPE_STRING	null-terminated C-string (`char*`). Initial content is specified in struct sol_memdesc::defcontent::s. It may be null. By default, strings are duplicated and freed as required. See Also SOL_MEMDESC_TYPE_CONST_STRING
SOL_MEMDESC_TYPE_CONST_STRING	null-terminated C-string (`const` char*). Initial content is specified in struct sol_memdesc::defcontent::s. It may be null. By default, strings are NOT duplicated neither freed. See Also SOL_MEMDESC_TYPE_STRING
SOL_MEMDESC_TYPE_ENUMERATION	enumeration Enumerations assign an integer to some symbol, then we offer a translation table in struct sol_memdesc::enumeration_mapping using struct sol_str_table_int64. If that is not enough, then provide your own struct sol_memdesc::ops::enumeration::from_str and struct sol_memdesc::ops::enumeration::to_str, these will receive the actual pointer to memory and thus can work with any precision. Since enumerations don' t have an implicit size, one must define struct sol_memdesc::size, which is limited to 64-bits (8 bytes). By default the value is based on struct sol_memdesc::defcontent::e (64-bit signed integer). One can change the behavior by setting a custom struct sol_memdesc::ops::init_defaults.
SOL_MEMDESC_TYPE_PTR	generic pointer (void *). If struct sol_memdesc::pointed_item is non-NULL, it will be managed as such (malloc/free). Note that the initial value is still defined as a pointer to the actual contents in struct sol_memdesc::defcontent::p. If that is non-NULL, then the pointer is allocated and that one will use defaults specified in struct sol_memdesc::pointed_item::defcontent, then values from struct sol_memdesc::defcontent::p is applied on top. By default the value is based on struct sol_memdesc::defcontent::p. See Also SOL_MEMDESC_TYPE_STRUCTURE
SOL_MEMDESC_TYPE_STRUCTURE	structure with internal members. This is a recursive type with children described in struct sol_memdesc::structure_members, an array that is null-terminated (all element members are zeroed). During initialization, each member will be considered according to its initial value. Then, if struct sol_memdesc::defcontent::p is non-NULL, it will be applied on top.
SOL_MEMDESC_TYPE_ARRAY	an array with internal members. This is a pointer to an array of items that are defined in struct sol_memdesc::array_item. It will not be touched, you should manage it yourself with struct sol_memdesc::ops. To map a struct sol_vector, use .size=sizeof(struct sol_vector), And provide a .array_item with the description on what is to be in the element, like a structure or a pointer to one, this way sol_memdesc_init_defaults() will set struct sol_vector::elem_size to size of array item. Then you must provide the following struct sol_memdesc::ops: `init_defaults:` set `elem_size` from `sol_memdesc_get_size`(desc->array_item). `array.get_length:` return `len`. `array.get_element:` proxy return of sol_vector_get(). `array.resize:` if shrinking, remember to call `sol_memdesc_free_content`(desc->array_item, it) for every item that will be removed, then call sol_vector_del_range(). If growing, call sol_vector_append_n() and initialze items with `sol_memdesc_init_defaults`(desc->array_item, it). See Also SOL_MEMDESC_OPS_VECTOR and SOL_MEMDESC_OPS_PTR_VECTOR.

Function Documentation

static int sol_memdesc_append_array_element	(	const struct sol_memdesc *	array_desc,
		void *	memory,
		const void *	ptr_content
	)

inlinestatic

Append the array element.

This function must be applied to SOL_MEMDESC_TYPE_ARRAY and will call struct sol_memdesc::ops::array::get_element, struct sol_memdesc::ops::array::get_length and struct sol_memdesc::ops::array::resize to resize the array and add one item at the end. Then sol_memdesc_set_content() is called at the new element.

Parameters

array_desc	the memory description of type SOL_MEMDESC_TYPE_ARRAY.
memory	the memory holding the array.
ptr_content	a pointer to the given content, dependent on the type of array_item. If a SOL_MEMDESC_TYPE_BOOL, then it must be a pointer to a bool.

Returns: On error, negative errno is returned. 0 on success

See Also: sol_memdesc_get_array_length(); sol_memdesc_get_array_element(); sol_memdesc_resize_array(); sol_memdesc_set_content()

References sol_memdesc::array_item, sol_memdesc_get_array_element(), sol_memdesc_get_array_length(), sol_memdesc_resize_array(), and sol_memdesc_set_content().

int sol_memdesc_compare	(	const struct sol_memdesc *	desc,
		const void *	a_memory,
		const void *	b_memory
	)

compare two memories using the given description.

This function will compare a_memory to b_memory using the given description, with that members that need special treatment will have it, like strings will be strcmp(). Operations may be overriden per-memdesc as defined in struct sol_memdesc::ops.

Note: SOL_MEMDESC_TYPE_PTR can only compare to NULL or same pointer unless struct sol_memdesc::pointed_item is provided, then the value of the pointed item is compared by recursively calling sol_memdesc_compare() on the pointed memories. NULL is always considered to be smaller than any value. This behavior can be changed with struct sol_memdesc::ops::compare.

Parameters

desc	the memory description.
a_memory	the first memory to compare.
b_memory	the second memory to compare.

Returns: On error, 0 and errno is set to non-zero. On success (errno == 0), 0 means equal, <0 means a_memory is smaller, >0 means b_memory is smaller.

int sol_memdesc_copy	(	const struct sol_memdesc *	desc,
		const void *	src_memory,
		void *	dst_memory
	)

copy the memory using the given description.

This function will copy src_memory to dst_memory using the given description, with that members that need special treatment will have it, like strings will be duplicated.

Parameters

desc	the memory description.
src_memory	the source/origin memory.
dst_memory	the destination/target memory.

Returns: 0 on success, negative errno on failure.

See Also: sol_memdesc_set_content()

int sol_memdesc_enumeration_from_str	(	const struct sol_memdesc *	enumeration,
		void *	ptr_return,
		const struct sol_str_slice	str
	)

convert enumeration value from string.

The return is stored in ptr_return, which must be the size stated in struct sol_memdesc::size as returned by sol_memdesc_get_size().

The string is given in the form of a slice so it doesn't need to be null-terminated.

Parameters

enumeration	the memory description of the enumeration of type SOL_MEMDESC_TYPE_ENUMERATION.
str	the slice with the string to convert, doesn't need to be null-terminated.
ptr_return	where to store the converted value. Must be a pointer to a memory of size sol_memdesc_get_size().

Returns: On error, negative errno is returned. 0 on success.

const char* sol_memdesc_enumeration_to_str	(	const struct sol_memdesc *	enumeration,
		const void *	memory
	)

convert enumeration value to string.

Parameters

enumeration	the memory description of the enumeration of type SOL_MEMDESC_TYPE_ENUMERATION.
memory	the memory of the enumeration.

Returns: On error, NULL should be returned and errno set. On success non-NULL is returned.

static const struct sol_memdesc_structure_member* sol_memdesc_find_structure_member	(	const struct sol_memdesc *	structure_desc,
		struct sol_str_slice	name
	)

static

Find structure member given its name.

The name is taken as a slice since sometimes it's not available as a null-terminated strings (such as loading from other protocols such as JSON).

Parameters

structure_desc	a description of type SOL_MEMDESC_TYPE_STRUCTURE.
name	the name to look for.

Returns: pointer on success or NULL on errors (with errno set).

See Also: sol_str_slice_from_str(); SOL_STR_SLICE_STR(); SOL_STR_SLICE_LITERAL()

References sol_str_slice::len, sol_memdesc_structure_member::name, SOL_MEMDESC_FOREACH_STRUCTURE_MEMBER, and sol_str_slice_str_eq().

static void sol_memdesc_free	(	const struct sol_memdesc *	desc,
		void *	memory
	)

inlinestatic

Free the contents and the memory.

Parameters

desc	the memory description.
memory	the memory to free the contents and the memory itself.

See Also: sol_memdesc_free_content()

References sol_memdesc_free_content().

Referenced by sol_memdesc_new_with_defaults().

int sol_memdesc_free_content	(	const struct sol_memdesc *	desc,
		void *	memory
	)

free the contents (internal memory) of a member.

This function will take care of special handling needed for each member, like strings that must be freed.

Parameters

desc	the memory description.
memory	the memory to free the internal contents.

Returns: 0 on success, negative errno on failure.

See Also: sol_memdesc_free()

Referenced by sol_memdesc_free().

void* sol_memdesc_get_array_element	(	const struct sol_memdesc *	array_desc,
		const void *	memory,
		size_t	idx
	)

Get the array element.

This function must be applied to SOL_MEMDESC_TYPE_ARRAY and will call struct sol_memdesc::ops::array::get_element.

Note: for speed purposes, this function will not guarantee out-of-bounds checking, please ensure the index is less than sol_memdesc_get_array_length() before calling it.

Parameters

array_desc	the memory description of type SOL_MEMDESC_TYPE_ARRAY.
memory	the memory holding the array.
idx	the index of the element inside the array.

Returns: On error NULL is returned and errno is set. On success the memory of the item is returned.

See Also: sol_memdesc_get_array_length()

Referenced by sol_memdesc_append_array_element().

ssize_t sol_memdesc_get_array_length	(	const struct sol_memdesc *	array_desc,
		const void *	memory
	)

Get the length of an array.

This function must be applied to SOL_MEMDESC_TYPE_ARRAY and will call struct sol_memdesc::ops::array::get_length.

The returned value is about the number of items according to struct sol_memdesc::array_item.

Parameters

array_desc	the memory description of type SOL_MEMDESC_TYPE_ARRAY.
memory	the memory holding the array.

Returns: On error, negative errno is returned. Zero or more for success.

Referenced by sol_memdesc_append_array_element().

static int64_t sol_memdesc_get_as_int64	(	const struct sol_memdesc *	desc,
		const void *	memory
	)

inlinestatic

Helper to fetch the memory as the largest supported signed integer.

Parameters

desc	the memory description.
memory	the memory to get content.

Returns: the number as int64_t. On errors, errno is set to non-zero.

See Also: sol_memdesc_is_signed_integer().

References sol_memdesc::api_version, sol_memdesc::defcontent, sol_memdesc::e, sol_memdesc_structure_member::offset, sol_memdesc::size, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, and sol_memdesc::type.

static uint64_t sol_memdesc_get_as_uint64	(	const struct sol_memdesc *	desc,
		const void *	memory
	)

inlinestatic

Helper to fetch the memory as the largest supported unsigned integer.

Parameters

desc	the memory description.
memory	the memory to get content.

Returns: the number as uint64_t. On errors, errno is set to non-zero.

See Also: sol_memdesc_is_unsigned_integer().

References sol_memdesc::api_version, sol_memdesc::defcontent, sol_memdesc::e, sol_memdesc_structure_member::offset, sol_memdesc::size, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, and sol_memdesc::type.

static uint16_t sol_memdesc_get_size ( const struct sol_memdesc * desc )

inlinestatic

get the size in bytes of the memory description.

This will use the intrinsic size of each type and for SOL_MEMDESC_TYPE_STRUCTURE and SOL_MEMDESC_TYPE_ARRAY it will use the explicit one at struct sol_memdesc::size.

Parameters

desc	the memory description.

Returns: 0 on errors (and errno is set to EINVAL) or the size in bytes.

References sol_memdesc::api_version, sol_memdesc::size, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, and sol_memdesc::type.

Referenced by sol_memdesc_get_structure_member_memory(), and sol_memdesc_new_with_defaults().

static void* sol_memdesc_get_structure_member_memory	(	const struct sol_memdesc *	structure_desc,
		const struct sol_memdesc_structure_member *	member_desc,
		const void *	structure_memory
	)

inlinestatic

get the pointer to the struct member memory description inside the given container.

This will use the struct sol_memdesc::offset to find the offset inside the container.

Parameters

structure_desc	the memory description of the structure.
member_desc	the memory description of the structure member.
structure_memory	the memory of the container (the pointer to the start of the structure that holds the member).

Returns: NULL on errors or the pointer inside structure_memory on success.

References sol_memdesc::api_version, sol_memdesc_structure_member::base, sol_memdesc_structure_member::offset, and sol_memdesc_get_size().

int sol_memdesc_init_defaults	(	const struct sol_memdesc *	desc,
		void *	memory
	)

initialize the memory.

This will use the default content specified in struct sol_memdesc::defcontent according to the type spefified in struct sol_memdesc::type.

Parameters

desc	the memory description.
memory	the memory to initialize.

Returns: 0 on success, negative errno on failure.

See Also: sol_memdesc_new_with_defaults()

Referenced by sol_memdesc_new_with_defaults().

static bool sol_memdesc_is_signed_integer ( const struct sol_memdesc * desc )

inlinestatic

Helper to check if type is signed integer-compatible.

Parameters

desc	the memory description.

Returns: true if it is signed integer (int8_t, int16_t, int32_t, int64_t, long, ssize_t or enumeration).

References sol_memdesc::api_version, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, and sol_memdesc::type.

static bool sol_memdesc_is_unsigned_integer ( const struct sol_memdesc * desc )

inlinestatic

Helper to check if type is unsigned integer-compatible.

Parameters

desc	the memory description.

Returns: true if it is unsigned integer (uint8_t, uint16_t, uint32_t, uint64_t, unsigned long or size_t).

References sol_memdesc::api_version, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, and sol_memdesc::type.

static void* sol_memdesc_new_with_defaults ( const struct sol_memdesc * desc )

inlinestatic

Allocate the memory required by this description and initialize it.

This will allocate offset + size bytes, then fill these bytes with the content defined in struct sol_memdesc::defcontent.

Parameters

desc	the memory description.

Returns: NULL on error, newly allocated memory on success. Free using sol_memdesc_free().

See Also: sol_memdesc_free()

References sol_memdesc_free(), sol_memdesc_get_size(), and sol_memdesc_init_defaults().

int sol_memdesc_resize_array	(	const struct sol_memdesc *	array_desc,
		void *	memory,
		size_t	length
	)

Resize the length of an array.

This function must be applied to SOL_MEMDESC_TYPE_ARRAY and will call struct sol_memdesc::ops::array::resize.

Parameters

array_desc	the memory description of type SOL_MEMDESC_TYPE_ARRAY.
memory	the memory holding the array.
length	the new length.

Returns: On error, negative errno is returned. 0 on success.

Referenced by sol_memdesc_append_array_element().

int sol_memdesc_serialize	(	const struct sol_memdesc *	desc,
		const void *	memory,
		struct sol_buffer *	buffer,
		const struct sol_memdesc_serialize_options *	opts,
		struct sol_buffer *	prefix
	)

Serialize a memory to a buffer using a description.

If no options are provided, then it will serialize in a C-like pattern, however if struct member names are not valid C symbols, it will not be a valid C.

Parameters

desc	the memory description.
memory	the memory to serialize.
buffer	where to serialize the memory. Must be pre-initialized, contents will be appended.
opts	if provided will modify how to serialize the memory.
prefix	some prefix to be added to lines, it will be modified during iteration to contain new indent strings. May be null so a local buffer is automatically created and destroyed.

Returns: 0 on success, negative errno otherwise.

static int64_t sol_memdesc_set_as_int64	(	const struct sol_memdesc *	desc,
		void *	memory,
		int64_t	value
	)

inlinestatic

Helper to set the memory as the largest supported signed integer.

Parameters

desc	the memory description.
memory	the memory to set content.
value	the number as int64_t.

Returns: 0 on success, negative errno on errors.

See Also: sol_memdesc_is_signed().

References sol_memdesc::api_version, sol_memdesc::defcontent, sol_memdesc::e, sol_memdesc_structure_member::offset, sol_memdesc::size, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, SSIZE_MAX, and sol_memdesc::type.

static int sol_memdesc_set_as_uint64	(	const struct sol_memdesc *	desc,
		void *	memory,
		uint64_t	value
	)

inlinestatic

Helper to set the memory as the largest supported unsigned integer.

Parameters

desc	the memory description.
memory	the memory to set content.
value	the number as uint64_t.

Returns: 0 on success, negative errno on errors.

See Also: sol_memdesc_is_unsigned().

References sol_memdesc::api_version, sol_memdesc::defcontent, sol_memdesc::e, sol_memdesc_structure_member::offset, sol_memdesc::size, SOL_MEMDESC_TYPE_ARRAY, SOL_MEMDESC_TYPE_BOOL, SOL_MEMDESC_TYPE_CONST_STRING, SOL_MEMDESC_TYPE_DOUBLE, SOL_MEMDESC_TYPE_ENUMERATION, SOL_MEMDESC_TYPE_INT16, SOL_MEMDESC_TYPE_INT32, SOL_MEMDESC_TYPE_INT64, SOL_MEMDESC_TYPE_INT8, SOL_MEMDESC_TYPE_LONG, SOL_MEMDESC_TYPE_PTR, SOL_MEMDESC_TYPE_SIZE, SOL_MEMDESC_TYPE_SSIZE, SOL_MEMDESC_TYPE_STRING, SOL_MEMDESC_TYPE_STRUCTURE, SOL_MEMDESC_TYPE_UINT16, SOL_MEMDESC_TYPE_UINT32, SOL_MEMDESC_TYPE_UINT64, SOL_MEMDESC_TYPE_UINT8, SOL_MEMDESC_TYPE_ULONG, SSIZE_MAX, and sol_memdesc::type.

int sol_memdesc_set_content	(	const struct sol_memdesc *	desc,
		void *	memory,
		const void *	ptr_content
	)

set the content of this memory.

This function take care to set the content, disposing of the previous content if any and duplicating the new one as required, like for strings.

Parameters

desc	the memory description.
memory	the memory to set content.
ptr_content	a pointer to the given content, dependent on the type. If a SOL_MEMDESC_TYPE_BOOL, then it must be a pointer to a bool.

Returns: 0 on success, negative errno on failure.

Referenced by sol_memdesc_append_array_element().

enum sol_memdesc_type sol_memdesc_type_from_str ( const char * str )

Converts a Memdesc Type from string to sol_memdesc_type.

Parameters

str	the string representing a valid type.

Returns: the type or SOL_MEMDESC_TYPE_UNKNOWN if invalid.

const char* sol_memdesc_type_to_str ( enum sol_memdesc_type type )

Converts a sol_memdesc_type to a string.

Parameters

type	the type to be converted.

Returns: the string or NULL, if the type is invalid.

Variable Documentation

const uint16_t SOL_MEMDESC_API_VERSION_COMPILED

the SOL_MEMDESC_API_VERSION this soletta build used.

This symbol is defined by soletta to match SOL_MEMDESC_API_VERSION, but unlike that macro this symbol will be relative to soletta build and is used in our macros and static-inline functions that must check for valid handles.

const struct sol_memdesc_ops SOL_MEMDESC_OPS_PTR_VECTOR

operations to handle struct sol_ptr_vector.

If one wants to use SOL_MEMDESC_TYPE_ARRAY with a struct sol_ptr_vector, then use this operations to initialize, get length, get element and resize the array.

const struct sol_memdesc_ops SOL_MEMDESC_OPS_VECTOR

operations to handle struct sol_vector.

If one wants to use SOL_MEMDESC_TYPE_ARRAY with a struct sol_vector, then use this operations to initialize, get length, get element and resize the array.

const struct sol_memdesc_serialize_options SOL_MEMDESC_SERIALIZE_OPTIONS_DEFAULT

the default struct sol_memdesc_serialize_options.

This symbol defines the original serialize options used by Soletta, it can be used to get default slices as well as serialization functions.

For instance, if you want to customize the serialization of a given structure member but not others, then you can override struct sol_memdesc_serialize_options::serialize_structure_member and call SOL_MEMDESC_SERIALIZE_OPTIONS::serialize_structure_member whenever to use the standard output.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation