XCM attribute map API. More...

#include <xcm_attr_types.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Typedefs
typedef void(*	xcm_attr_map_foreach_cb) (const char attr_name, enum xcm_attr_type attr_type, const void attr_value, size_t attr_value_len, void *user)

Functions
struct xcm_attr_map *	xcm_attr_map_create (void)

struct xcm_attr_map *	xcm_attr_map_clone (const struct xcm_attr_map *original)

void	xcm_attr_map_add (struct xcm_attr_map attr_map, const char attr_name, enum xcm_attr_type attr_type, const void *attr_value, size_t attr_value_len)

void	xcm_attr_map_add_bool (struct xcm_attr_map attr_map, const char attr_name, bool attr_value)

void	xcm_attr_map_add_int64 (struct xcm_attr_map attr_map, const char attr_name, int64_t attr_value)

void	xcm_attr_map_add_double (struct xcm_attr_map attr_map, const char attr_name, double attr_value)

void	xcm_attr_map_add_str (struct xcm_attr_map attr_map, const char attr_name, const char *attr_value)

void	xcm_attr_map_add_bin (struct xcm_attr_map attr_map, const char attr_name, const void *attr_value, size_t attr_value_len)

void	xcm_attr_map_add_all (struct xcm_attr_map dst_map, const struct xcm_attr_map src_map)

const void *	xcm_attr_map_get (const struct xcm_attr_map attr_map, const char attr_name, enum xcm_attr_type attr_type, size_t attr_value_len)

const bool *	xcm_attr_map_get_bool (const struct xcm_attr_map attr_map, const char attr_name)

const int64_t *	xcm_attr_map_get_int64 (const struct xcm_attr_map attr_map, const char attr_name)

const double *	xcm_attr_map_get_double (const struct xcm_attr_map attr_map, const char attr_name)

const char *	xcm_attr_map_get_str (const struct xcm_attr_map attr_map, const char attr_name)

const char *	xcm_attr_map_get_bin (const struct xcm_attr_map attr_map, const char attr_name)

bool	xcm_attr_map_exists (const struct xcm_attr_map attr_map, const char attr_name)

void	xcm_attr_map_del (struct xcm_attr_map attr_map, const char attr_name)

size_t	xcm_attr_map_size (const struct xcm_attr_map *attr_map)

void	xcm_attr_map_foreach (const struct xcm_attr_map attr_map, xcm_attr_map_foreach_cb cb, void user)

bool	xcm_attr_map_equal (const struct xcm_attr_map attr_map_a, const struct xcm_attr_map attr_map_b)

void	xcm_attr_map_destroy (struct xcm_attr_map *attr_map)

Detailed Description

XCM attribute map API.

An XCM attribute map is a set of key-value pairs. The key is an attribute name in the form of a string. One key maps to at most one value. The attribute value is either a boolean, a signed 64-bit integer, a double-precision floating point value, a string, or a variable-length binary object.

Typedef Documentation

◆ xcm_attr_map_foreach_cb

typedef void(* xcm_attr_map_foreach_cb) (const char *attr_name, enum xcm_attr_type attr_type, const void *attr_value, size_t attr_value_len, void *user)

Callback function prototype used for iteration.

Function Documentation

◆ xcm_attr_map_create()

struct xcm_attr_map * xcm_attr_map_create ( void )

Create an attribute map instance.

Returns: An empty attribute map instance.

◆ xcm_attr_map_clone()

struct xcm_attr_map * xcm_attr_map_clone ( const struct xcm_attr_map * original )

Create a copy of an attribute map instance.

Parameters

[in] original The original attribute map instance, to be copied.

Returns: A deep copy of the original attribute map.

◆ xcm_attr_map_add()

void xcm_attr_map_add	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		enum xcm_attr_type	attr_type,
		const void *	attr_value,
		size_t	attr_value_len
	)

Associate a key with a value.

This function associates the attribute key attr_name to the attribute value attr_value in the attribute map attr_map. If the key attr_name already exists, its value is replaced.

Both the key and the value will be copied, and thus attr_name and attr_value will still be owned by the caller at call completion.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_type	The type of the value to be added.
[in]	attr_value	The value of the attribute to be added.
[in]	attr_value_len	The length (in bytes) of the value.

◆ xcm_attr_map_add_bool()

void xcm_attr_map_add_bool	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		bool	attr_value
	)

Associate a key with a boolean value.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_value	The boolean value of the attribute to be added.

See also: xcm_attr_map_add

◆ xcm_attr_map_add_int64()

void xcm_attr_map_add_int64	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		int64_t	attr_value
	)

Associate a key with a 64-bit signed integer value.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_value	The integer value of the attribute to be added.

See also: xcm_attr_map_add

◆ xcm_attr_map_add_double()

void xcm_attr_map_add_double	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		double	attr_value
	)

Associate a key with a double-precision floating point value.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_value	The double value of the attribute to be added.

See also: xcm_attr_map_add

◆ xcm_attr_map_add_str()

void xcm_attr_map_add_str	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		const char *	attr_value
	)

Associate a key with a string value.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_value	The string value of the attribute to be added.

See also: xcm_attr_map_add

◆ xcm_attr_map_add_bin()

void xcm_attr_map_add_bin	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		const void *	attr_value,
		size_t	attr_value_len
	)

Associate a key with a byte buffer.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be added.
[in]	attr_value	The value of the attribute to be added.

See also: xcm_attr_map_add

◆ xcm_attr_map_add_all()

void xcm_attr_map_add_all	(	struct xcm_attr_map *	dst_map,
		const struct xcm_attr_map *	src_map
	)

Copies all attributes of a map to another.

This function adds all the attributes of the source map to the target map. The source map remains unchanged.

Parameters

[in]	dst_map	The attribute map to which the attributes will be added.
[in]	src_map	The attribute map which attributes will be copied.

◆ xcm_attr_map_get()

const void * xcm_attr_map_get	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name,
		enum xcm_attr_type *	attr_type,
		size_t *	attr_value_len
	)

Retrieve the value associated with a particular key.

This function retrieves the attribute value, value type and value length of the attribute attr_name, in case it exists.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.
[out]	attr_type	A pointer to a buffer where the value type will be stored, or NULL.
[out]	attr_value_len	A pointer to a buffer where the length (in bytes) of the value will be stored, or NULL.

Returns: A pointer to the attribute value, or NULL if the attribute does not exist.

◆ xcm_attr_map_get_bool()

const bool * xcm_attr_map_get_bool	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Retrieve the boolean value associated with a particular key.

This function retrieves the boolean attribute value of the attribute attr_name, in case it exists and is of type xcm_attr_type_bool.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.

Returns: A pointer to the attribute's boolean value, or NULL if the attribute does not exist or is of a non-boolean type.

◆ xcm_attr_map_get_int64()

const int64_t * xcm_attr_map_get_int64	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Retrieve the integer value associated with a particular key.

This function retrieves the 64-bit signed integer attribute value of the attribute attr_name, in case it exists and is of type xcm_attr_type_int64.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.

Returns: A pointer to the attribute's integer value, or NULL if the attribute does not exist or is of a non-integer type.

◆ xcm_attr_map_get_double()

const double * xcm_attr_map_get_double	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Retrieve the floating point value associated with a particular key.

This function retrieves the double-precision floating point attribute value of the attribute attr_name, in case it exists and is of type xcm_attr_type_double.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.

Returns: A pointer to the attribute's double value, or NULL if the attribute does not exist or is of a non-double type.

◆ xcm_attr_map_get_str()

const char * xcm_attr_map_get_str	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Retrieve the string value associated with a particular key.

This function retrieves the NUL-terminated string attribute value of the attribute attr_name, in case it exists and is of type xcm_attr_type_str.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.

Returns: A pointer to the attribute's string, or NULL if the attribute does not exist or is of a non-string type.

◆ xcm_attr_map_get_bin()

const char * xcm_attr_map_get_bin	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Retrieve the binary value associated with a particular key.

This function retrieves the attribute value, in the form of a sequence of bytes, of the attribute attr_name, in case it exists and is of type xcm_attr_type_bin.

The value pointer returned is valid as long as the key is not removed, its value is changed, or the map is destroyed.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be retrieved.

Returns: A pointer to the attribute's value, or NULL if the attribute does not exist or is of a non-binary type.

◆ xcm_attr_map_exists()

bool xcm_attr_map_exists	(	const struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Check if an attribute named attr_name exists in the attribute map.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute.

Returns: true, in case the attribute name exists, and false otherwise.

◆ xcm_attr_map_del()

void xcm_attr_map_del	(	struct xcm_attr_map *	attr_map,
		const char *	attr_name
	)

Removes an attribute from the attribute map.

This function deletes the attribute attr_name, in case it exists.

Parameters

[in]	attr_map	The attribute map instance.
[in]	attr_name	The name of the attribute to be deleted.

◆ xcm_attr_map_size()

size_t xcm_attr_map_size ( const struct xcm_attr_map * attr_map )

Returns the number of attributes in the attribute map.

Parameters

[in] attr_map The attribute map instance.

Returns: The number of attributes in attr_map.

◆ xcm_attr_map_foreach()

void xcm_attr_map_foreach	(	const struct xcm_attr_map *	attr_map,
		xcm_attr_map_foreach_cb	cb,
		void *	user
	)

Iterates over all attributes in a map.

This function calls the supplied callback function cb for each attribute in attr_map.

The map may not be modified during iteration.

Parameters

[in]	attr_map	The attribute map instance.
[in]	cb	The callback function.
[in]	user	An opaque pointer, supplied back to the application in every `cb` call.

◆ xcm_attr_map_equal()

bool xcm_attr_map_equal	(	const struct xcm_attr_map *	attr_map_a,
		const struct xcm_attr_map *	attr_map_b
	)

Compares two attribute maps for equality (by value).

Parameters

[in]	attr_map_a	An attribute map instance.
[in]	attr_map_b	An attribute map instance.

Returns: Returns true if attr_map_a and attr_map_a are equal, false otherwise.

◆ xcm_attr_map_destroy()

void xcm_attr_map_destroy ( struct xcm_attr_map * attr_map )

Destroys an attribute map instance.

This function destroys the attribute map instance and frees all the resources associated with it.

Parameters

[in] attr_map The attribute map instance, or NULL.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ xcm_attr_map_foreach_cb

Function Documentation

◆ xcm_attr_map_create()

◆ xcm_attr_map_clone()

◆ xcm_attr_map_add()

◆ xcm_attr_map_add_bool()

◆ xcm_attr_map_add_int64()

◆ xcm_attr_map_add_double()

◆ xcm_attr_map_add_str()

◆ xcm_attr_map_add_bin()

◆ xcm_attr_map_add_all()

◆ xcm_attr_map_get()

◆ xcm_attr_map_get_bool()

◆ xcm_attr_map_get_int64()

◆ xcm_attr_map_get_double()

◆ xcm_attr_map_get_str()

◆ xcm_attr_map_get_bin()

◆ xcm_attr_map_exists()

◆ xcm_attr_map_del()

◆ xcm_attr_map_size()

◆ xcm_attr_map_foreach()

◆ xcm_attr_map_equal()

◆ xcm_attr_map_destroy()