The C parameter server: rclc's API over the executor's store. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "rclc/types.h"
#include <rosidl_runtime_c/primitives_sequence.h>
#include <rosidl_runtime_c/string.h>

Include dependency graph for rclc_parameter.h:

Go to the source code of this file.

Data Structures
struct	rcl_interfaces__msg__Parameter

struct	rcl_interfaces__msg__ParameterValue

struct	rclc_parameter_options_t

struct	rclc_parameter_server_t

Macros
#define	NROS__RCLC_ARRAY(NAME, T)

#define	RCL_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_

#define	RCL_INTERFACES__MSG__DETAIL__PARAMETER_VALUE__STRUCT_H_

#define	RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES 6

#define	RCLC_PARAMETER_DISABLED_ON_CALLBACK 40004

#define	RCLC_PARAMETER_MODIFICATION_REJECTED 4001

#define	RCLC_PARAMETER_TYPE_MISMATCH 4002

Typedefs
typedef rcl_interfaces__msg__Parameter	Parameter

typedef rcl_interfaces__msg__ParameterValue	ParameterValue

typedef bool(*	rclc_parameter_callback_t) (const Parameter old_param, const Parameter new_param, void *context)

Enumerations
enum	rclc_parameter_type_t { RCLC_PARAMETER_NOT_SET = 0 , RCLC_PARAMETER_BOOL = 1 , RCLC_PARAMETER_INT = 2 , RCLC_PARAMETER_DOUBLE = 3 , RCLC_PARAMETER_STRING = 4 , RCLC_PARAMETER_BYTE_ARRAY = 5 , RCLC_PARAMETER_BOOL_ARRAY = 6 , RCLC_PARAMETER_INT_ARRAY = 7 , RCLC_PARAMETER_DOUBLE_ARRAY = 8 , RCLC_PARAMETER_STRING_ARRAY = 9 }

Functions
rcl_ret_t	rclc_add_parameter (rclc_parameter_server_t parameter_server, const char parameter_name, rclc_parameter_type_t type)

rcl_ret_t	rclc_add_parameter_constraint_double (rclc_parameter_server_t parameter_server, const char parameter_name, double from_value, double to_value, double step)

rcl_ret_t	rclc_add_parameter_constraint_integer (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t from_value, int64_t to_value, uint64_t step)

rcl_ret_t	rclc_add_parameter_description (rclc_parameter_server_t parameter_server, const char parameter_name, const char parameter_description, const char additional_constraints)

rcl_ret_t	rclc_delete_parameter (rclc_parameter_server_t parameter_server, const char parameter_name)

rcl_ret_t	rclc_executor_add_parameter_server (struct rclc_executor_t executor, rclc_parameter_server_t parameter_server, rclc_parameter_callback_t on_modification)

rcl_ret_t	rclc_executor_add_parameter_server_with_context (struct rclc_executor_t executor, rclc_parameter_server_t parameter_server, rclc_parameter_callback_t on_modification, void *context)

rcl_ret_t	rclc_parameter_declare_bool (rclc_parameter_server_t parameter_server, const char parameter_name, bool default_value)

rcl_ret_t	rclc_parameter_declare_bool_array (rclc_parameter_server_t parameter_server, const char parameter_name, const bool *data, size_t len)

rcl_ret_t	rclc_parameter_declare_byte_array (rclc_parameter_server_t parameter_server, const char parameter_name, const uint8_t *data, size_t len)

rcl_ret_t	rclc_parameter_declare_double (rclc_parameter_server_t parameter_server, const char parameter_name, double default_value)

rcl_ret_t	rclc_parameter_declare_double_array (rclc_parameter_server_t parameter_server, const char parameter_name, const double *data, size_t len)

rcl_ret_t	rclc_parameter_declare_int (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t default_value)

rcl_ret_t	rclc_parameter_declare_int_array (rclc_parameter_server_t parameter_server, const char parameter_name, const int64_t *data, size_t len)

rcl_ret_t	rclc_parameter_declare_string (rclc_parameter_server_t parameter_server, const char parameter_name, const char *default_value)

rcl_ret_t	rclc_parameter_declare_string_array (rclc_parameter_server_t parameter_server, const char parameter_name, const char const data, size_t len)

rcl_ret_t	rclc_parameter_describe (rclc_parameter_server_t parameter_server, const char parameter_name, char out_description, size_t description_capacity, char out_constraints, size_t constraints_capacity, bool *out_read_only)

rcl_ret_t	rclc_parameter_get_bool (rclc_parameter_server_t parameter_server, const char parameter_name, bool *output)

rcl_ret_t	rclc_parameter_get_bool_array (rclc_parameter_server_t parameter_server, const char parameter_name, bool output, size_t capacity, size_t out_len)

rcl_ret_t	rclc_parameter_get_byte_array (rclc_parameter_server_t parameter_server, const char parameter_name, uint8_t output, size_t capacity, size_t out_len)

rcl_ret_t	rclc_parameter_get_double (rclc_parameter_server_t parameter_server, const char parameter_name, double *output)

rcl_ret_t	rclc_parameter_get_double_array (rclc_parameter_server_t parameter_server, const char parameter_name, double output, size_t capacity, size_t out_len)

rcl_ret_t	rclc_parameter_get_double_range (rclc_parameter_server_t parameter_server, const char parameter_name, double out_from, double out_to, double *out_step)

rcl_ret_t	rclc_parameter_get_int (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t *output)

rcl_ret_t	rclc_parameter_get_int_array (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t output, size_t capacity, size_t out_len)

rcl_ret_t	rclc_parameter_get_integer_range (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t out_from, int64_t out_to, int64_t *out_step)

rcl_ret_t	rclc_parameter_get_string (rclc_parameter_server_t parameter_server, const char parameter_name, char *output, size_t capacity)

rcl_ret_t	rclc_parameter_get_string_array (rclc_parameter_server_t parameter_server, const char parameter_name, char output, size_t stride, size_t capacity, size_t out_len)

rclc_parameter_type_t	rclc_parameter_get_type (rclc_parameter_server_t parameter_server, const char parameter_name)

rcl_ret_t	rclc_parameter_list (rclc_parameter_server_t parameter_server, const char prefix, char out_names, size_t name_stride, size_t max_names, size_t out_count)

rcl_ret_t	rclc_parameter_server_fini (rclc_parameter_server_t parameter_server, struct rcl_node_t node)

rcl_ret_t	rclc_parameter_server_init_default (rclc_parameter_server_t parameter_server, struct rcl_node_t node)

rcl_ret_t	rclc_parameter_server_init_with_option (rclc_parameter_server_t parameter_server, struct rcl_node_t node, const rclc_parameter_options_t *options)

rcl_ret_t	rclc_parameter_set_bool (rclc_parameter_server_t parameter_server, const char parameter_name, bool value)

rcl_ret_t	rclc_parameter_set_bool_array (rclc_parameter_server_t parameter_server, const char parameter_name, const bool *data, size_t len)

rcl_ret_t	rclc_parameter_set_byte_array (rclc_parameter_server_t parameter_server, const char parameter_name, const uint8_t *data, size_t len)

rcl_ret_t	rclc_parameter_set_double (rclc_parameter_server_t parameter_server, const char parameter_name, double value)

rcl_ret_t	rclc_parameter_set_double_array (rclc_parameter_server_t parameter_server, const char parameter_name, const double *data, size_t len)

rcl_ret_t	rclc_parameter_set_int (rclc_parameter_server_t parameter_server, const char parameter_name, int64_t value)

rcl_ret_t	rclc_parameter_set_int_array (rclc_parameter_server_t parameter_server, const char parameter_name, const int64_t *data, size_t len)

rcl_ret_t	rclc_parameter_set_string (rclc_parameter_server_t parameter_server, const char parameter_name, const char *value)

rcl_ret_t	rclc_parameter_set_string_array (rclc_parameter_server_t parameter_server, const char parameter_name, const char const data, size_t len)

rcl_ret_t	rclc_set_parameter_read_only (rclc_parameter_server_t parameter_server, const char parameter_name, bool read_only)

Detailed Description

The C parameter server: rclc's API over the executor's store.

RFC-0105 / phase-491. ONE parameter family for C, under rclc's own names and at rclc's include path, so a ported #include <rclc_parameter/rclc_parameter.h> finds it. Every parameter declared here is served by the six rcl_interfaces services (ros2 param list/get/set/describe/dump/load).

What differs from upstream rclc, and why (RFC-0105 "bounded envelope"):

Nothing here allocates. The store is the executor's, sized at build time (NROS_MAX_PARAMETERS); max_params is a per-node quota inside it.
The node must be bound to an executor (rclc_executor_node_init) before rclc_parameter_server_init_*; otherwise RCL_RET_NOT_INIT.
Local typed sets fire the callback and skip read-only and range checks, as rclc's do. REMOTE sets enforce read-only AND the range rclc only advertises (rclcpp's behaviour).
Parameter has rosidl's member paths (p->name.data, p->value.type, p->value.integer_value, ...) but is not a rosidl ABI type; there are no rcl_interfaces__msg__Parameter__init/fini. Its pointers are valid only for the duration of the callback. A scalar string_value is NUL-terminated; array elements, including a string array's, are not — read size.
notify_changed_over_dds is accepted; /parameter_events publication lands with phase-491 W3.

Calling context: the executor's task only, never an ISR. Like rclc, nothing here takes a lock.

Types are spelled with nano-ros's names (rcl_ret_t, struct rcl_node_t, struct rclc_executor_t); <rclc/detail/rcl_compat.h> makes rcl_ret_t, rcl_node_t, rclc_executor_t and the RCL_RET_* codes the same types, so a ported file that includes it compiles unchanged. phase-492 makes the rcl spellings primary across the C API.

Macro Definition Documentation

◆ NROS__RCLC_ARRAY

#define NROS__RCLC_ARRAY	(	NAME,
		T
	)

Value:

    NROS_PUBLIC rcl_ret_t rclc_parameter_declare_##NAME##_array(                                   \
        rclc_parameter_server_t* parameter_server, const char* parameter_name, const T* data,      \
        size_t len);                                                                               \
    NROS_PUBLIC rcl_ret_t rclc_parameter_set_##NAME##_array(                                       \
        rclc_parameter_server_t* parameter_server, const char* parameter_name, const T* data,      \
        size_t len);                                                                               \
    NROS_PUBLIC rcl_ret_t rclc_parameter_get_##NAME##_array(                                       \
        rclc_parameter_server_t* parameter_server, const char* parameter_name, T* output,          \
        size_t capacity, size_t* out_len);

◆ RCL_INTERFACESMSGDETAILPARAMETERSTRUCT_H_

#define RCL_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_

◆ RCL_INTERFACESMSGDETAIL__PARAMETER_VALUE__STRUCT_H_

#define RCL_INTERFACES__MSG__DETAIL__PARAMETER_VALUE__STRUCT_H_

◆ RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES

#define RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES 6

Handles a parameter server takes from rclc_executor_init's count — rclc rolling's six services. Ours are not executor handles, so this only over-reserves; it is defined so ported handle arithmetic compiles.

◆ RCLC_PARAMETER_DISABLED_ON_CALLBACK

#define RCLC_PARAMETER_DISABLED_ON_CALLBACK 40004

◆ RCLC_PARAMETER_MODIFICATION_REJECTED

#define RCLC_PARAMETER_MODIFICATION_REJECTED 4001

◆ RCLC_PARAMETER_TYPE_MISMATCH

#define RCLC_PARAMETER_TYPE_MISMATCH 4002

Typedef Documentation

◆ Parameter

typedef rcl_interfaces__msg__Parameter Parameter

rclc's short names.

◆ ParameterValue

typedef rcl_interfaces__msg__ParameterValue ParameterValue

◆ rclc_parameter_callback_t

typedef bool(* rclc_parameter_callback_t) (const Parameter *old_param, const Parameter *new_param, void *context)

rclc's callback: old_param NULL when the write creates the parameter, new_param NULL when it deletes it; false refuses. Fired by local typed sets, remote sets, remote deletes (NOT_SET) and remote creations of an undeclared name — not by rclc_add_parameter or a local rclc_delete_parameter. While it runs, every mutating call on its server returns RCLC_PARAMETER_DISABLED_ON_CALLBACK.

Enumeration Type Documentation

◆ rclc_parameter_type_t

enum rclc_parameter_type_t

rclc's parameter types (0..3), extended with the rest of rcl_interfaces/msg/ParameterType (4..9), which this server also serves.

Enumerator
RCLC_PARAMETER_NOT_SET
RCLC_PARAMETER_BOOL
RCLC_PARAMETER_INT
RCLC_PARAMETER_DOUBLE
RCLC_PARAMETER_STRING
RCLC_PARAMETER_BYTE_ARRAY
RCLC_PARAMETER_BOOL_ARRAY
RCLC_PARAMETER_INT_ARRAY
RCLC_PARAMETER_DOUBLE_ARRAY
RCLC_PARAMETER_STRING_ARRAY

Function Documentation

◆ rclc_add_parameter()

rcl_ret_t rclc_add_parameter	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		rclc_parameter_type_t	type
	)

Declares type's zero value. A launch value already baked under this name with this type is kept.

◆ rclc_add_parameter_constraint_double()

rcl_ret_t rclc_add_parameter_constraint_double	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double	from_value,
		double	to_value,
		double	step
	)

◆ rclc_add_parameter_constraint_integer()

rcl_ret_t rclc_add_parameter_constraint_integer	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t	from_value,
		int64_t	to_value,
		uint64_t	step
	)

Advertised by describe and enforced on REMOTE writes.

◆ rclc_add_parameter_description()

rcl_ret_t rclc_add_parameter_description	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const char *	parameter_description,
		const char *	additional_constraints
	)

◆ rclc_delete_parameter()

rcl_ret_t rclc_delete_parameter	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name
	)

◆ rclc_executor_add_parameter_server()

rcl_ret_t rclc_executor_add_parameter_server	(	struct rclc_executor_t *	executor,
		rclc_parameter_server_t *	parameter_server,
		rclc_parameter_callback_t	on_modification
	)

Registers the six parameter services and the callback (NULL = none). executor must be the one the server's node is bound to.

◆ rclc_executor_add_parameter_server_with_context()

rcl_ret_t rclc_executor_add_parameter_server_with_context	(	struct rclc_executor_t *	executor,
		rclc_parameter_server_t *	parameter_server,
		rclc_parameter_callback_t	on_modification,
		void *	context
	)

◆ rclc_parameter_declare_bool()

rcl_ret_t rclc_parameter_declare_bool	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		bool	default_value
	)

Declare with a default, keeping a launch value of the same type (rclcpp's declare_parameter). Prefer these over add-then-set, which overwrites it.

◆ rclc_parameter_declare_bool_array()

rcl_ret_t rclc_parameter_declare_bool_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const bool *	data,
		size_t	len
	)

◆ rclc_parameter_declare_byte_array()

rcl_ret_t rclc_parameter_declare_byte_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const uint8_t *	data,
		size_t	len
	)

◆ rclc_parameter_declare_double()

rcl_ret_t rclc_parameter_declare_double	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double	default_value
	)

◆ rclc_parameter_declare_double_array()

rcl_ret_t rclc_parameter_declare_double_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const double *	data,
		size_t	len
	)

◆ rclc_parameter_declare_int()

rcl_ret_t rclc_parameter_declare_int	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t	default_value
	)

◆ rclc_parameter_declare_int_array()

rcl_ret_t rclc_parameter_declare_int_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const int64_t *	data,
		size_t	len
	)

◆ rclc_parameter_declare_string()

rcl_ret_t rclc_parameter_declare_string	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const char *	default_value
	)

◆ rclc_parameter_declare_string_array()

rcl_ret_t rclc_parameter_declare_string_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const char const	data,
		size_t	len
	)

◆ rclc_parameter_describe()

rcl_ret_t rclc_parameter_describe	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		char *	out_description,
		size_t	description_capacity,
		char *	out_constraints,
		size_t	constraints_capacity,
		bool *	out_read_only
	)

Any out pointer may be NULL. RCLC_RET_FULL when a text was truncated (it is still written, NUL-terminated).

◆ rclc_parameter_get_bool()

rcl_ret_t rclc_parameter_get_bool	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		bool *	output
	)

◆ rclc_parameter_get_bool_array()

rcl_ret_t rclc_parameter_get_bool_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		bool *	output,
		size_t	capacity,
		size_t *	out_len
	)

◆ rclc_parameter_get_byte_array()

rcl_ret_t rclc_parameter_get_byte_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		uint8_t *	output,
		size_t	capacity,
		size_t *	out_len
	)

◆ rclc_parameter_get_double()

rcl_ret_t rclc_parameter_get_double	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double *	output
	)

◆ rclc_parameter_get_double_array()

rcl_ret_t rclc_parameter_get_double_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double *	output,
		size_t	capacity,
		size_t *	out_len
	)

◆ rclc_parameter_get_double_range()

rcl_ret_t rclc_parameter_get_double_range	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double *	out_from,
		double *	out_to,
		double *	out_step
	)

◆ rclc_parameter_get_int()

rcl_ret_t rclc_parameter_get_int	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t *	output
	)

◆ rclc_parameter_get_int_array()

rcl_ret_t rclc_parameter_get_int_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t *	output,
		size_t	capacity,
		size_t *	out_len
	)

◆ rclc_parameter_get_integer_range()

rcl_ret_t rclc_parameter_get_integer_range	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t *	out_from,
		int64_t *	out_to,
		int64_t *	out_step
	)

RCL_RET_ERROR when no range of that kind is attached.

◆ rclc_parameter_get_string()

rcl_ret_t rclc_parameter_get_string	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		char *	output,
		size_t	capacity
	)

RCLC_RET_FULL when capacity (NUL included) is too small; nothing is written then.

◆ rclc_parameter_get_string_array()

rcl_ret_t rclc_parameter_get_string_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		char *	output,
		size_t	stride,
		size_t	capacity,
		size_t *	out_len
	)

◆ rclc_parameter_get_type()

rclc_parameter_type_t rclc_parameter_get_type	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name
	)

RCLC_PARAMETER_NOT_SET when undeclared.

◆ rclc_parameter_list()

rcl_ret_t rclc_parameter_list	(	rclc_parameter_server_t *	parameter_server,
		const char *	prefix,
		char *	out_names,
		size_t	name_stride,
		size_t	max_names,
		size_t *	out_count
	)

Names starting with prefix (NULL = all) into max_names rows of name_stride bytes. *out_count always receives the total; pass max_names 0 to count. RCLC_RET_FULL when more matched than fit.

◆ rclc_parameter_server_fini()

rcl_ret_t rclc_parameter_server_fini	(	rclc_parameter_server_t *	parameter_server,
		struct rcl_node_t *	node
	)

Unregisters the callback and deletes the node's parameters.

◆ rclc_parameter_server_init_default()

rcl_ret_t rclc_parameter_server_init_default	(	rclc_parameter_server_t *	parameter_server,
		struct rcl_node_t *	node
	)

Defaults: events on, 4 parameters, undeclared sets refused.

◆ rclc_parameter_server_init_with_option()

rcl_ret_t rclc_parameter_server_init_with_option	(	rclc_parameter_server_t *	parameter_server,
		struct rcl_node_t *	node,
		const rclc_parameter_options_t *	options
	)

◆ rclc_parameter_set_bool()

rcl_ret_t rclc_parameter_set_bool	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		bool	value
	)

◆ rclc_parameter_set_bool_array()

rcl_ret_t rclc_parameter_set_bool_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const bool *	data,
		size_t	len
	)

◆ rclc_parameter_set_byte_array()

rcl_ret_t rclc_parameter_set_byte_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const uint8_t *	data,
		size_t	len
	)

◆ rclc_parameter_set_double()

rcl_ret_t rclc_parameter_set_double	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		double	value
	)

◆ rclc_parameter_set_double_array()

rcl_ret_t rclc_parameter_set_double_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const double *	data,
		size_t	len
	)

◆ rclc_parameter_set_int()

rcl_ret_t rclc_parameter_set_int	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		int64_t	value
	)

◆ rclc_parameter_set_int_array()

rcl_ret_t rclc_parameter_set_int_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const int64_t *	data,
		size_t	len
	)

◆ rclc_parameter_set_string()

rcl_ret_t rclc_parameter_set_string	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const char *	value
	)

◆ rclc_parameter_set_string_array()

rcl_ret_t rclc_parameter_set_string_array	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		const char const	data,
		size_t	len
	)

◆ rclc_set_parameter_read_only()

rcl_ret_t rclc_set_parameter_read_only	(	rclc_parameter_server_t *	parameter_server,
		const char *	parameter_name,
		bool	read_only
	)

Refuses REMOTE writes; the owner's local sets still go through.

Data Structures

Macros

Typedefs

Enumerations

Functions