rclc_parameter.h File Reference

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 (default on) gives the node one /parameter_events publisher, and each accepted change is published on it (phase-491 W3, RFC-0105 D8).

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_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_

#define RCL_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_

RCL_INTERFACES__MSG__DETAIL__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.