rclc_parameter.h

Go to the documentation of this file.

 
#ifndef RCLC_PARAMETER__RCLC_PARAMETER_H_
#define RCLC_PARAMETER__RCLC_PARAMETER_H_
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "rclc/types.h"
 
/* Issue 0865 — this surface exists only in an image built with the
 * `param-services` capability. Say so here rather than in `ld`'s output. */
#if defined(NROS_HAS_PARAM_SERVICES) && !NROS_HAS_PARAM_SERVICES
#error "<rclc_parameter/rclc_parameter.h> needs the param_services capability: declare \
features = [\"param_services\"] under [system] in system.toml, or \
set(NROS_FEATURES \"param_services\") before add_subdirectory(<nano-ros>), and rebuild."
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ===================================================================
 * Return codes rclc adds (upstream values, including 40004)
 * =================================================================== */
 
#define RCLC_PARAMETER_MODIFICATION_REJECTED 4001
#define RCLC_PARAMETER_TYPE_MISMATCH 4002
#define RCLC_PARAMETER_DISABLED_ON_CALLBACK 40004

#define RCLC_EXECUTOR_PARAMETER_SERVER_HANDLES 6
 
/* ===================================================================
 * Types
 * =================================================================== */

typedef 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
} rclc_parameter_type_t;

typedef struct rclc_parameter_options_t {
    bool notify_changed_over_dds;
    size_t max_params;
    bool allow_undeclared_parameters;
    bool low_mem_mode;
} rclc_parameter_options_t;
 
/* rosidl's C runtime shapes, from their one definition site in nano-ros
 * (phase-492 W7). Each is guarded with upstream's include guard, so a
 * translation unit that already has rosidl's definition (same layout) keeps
 * it. */
#include <rosidl_runtime_c/primitives_sequence.h>
#include <rosidl_runtime_c/string.h>
 
#ifndef RCL_INTERFACES__MSG__DETAIL__PARAMETER_VALUE__STRUCT_H_
#define RCL_INTERFACES__MSG__DETAIL__PARAMETER_VALUE__STRUCT_H_
typedef struct rcl_interfaces__msg__ParameterValue {
    uint8_t type;
    bool bool_value;
    int64_t integer_value;
    double double_value;
    rosidl_runtime_c__String string_value;
    rosidl_runtime_c__octet__Sequence byte_array_value;
    rosidl_runtime_c__boolean__Sequence bool_array_value;
    rosidl_runtime_c__int64__Sequence integer_array_value;
    rosidl_runtime_c__double__Sequence double_array_value;
    rosidl_runtime_c__String__Sequence string_array_value;
} rcl_interfaces__msg__ParameterValue;
#endif
 
#ifndef RCL_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_
#define RCL_INTERFACES__MSG__DETAIL__PARAMETER__STRUCT_H_
typedef struct rcl_interfaces__msg__Parameter {
    rosidl_runtime_c__String name;
    rcl_interfaces__msg__ParameterValue value;
} rcl_interfaces__msg__Parameter;
#endif

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);

typedef struct rclc_parameter_server_t {
    void* _executor;
    size_t _max_params;
    rclc_parameter_callback_t _on_modification;
    void* _context;
    uint8_t _node_id;
    bool _initialized;
    bool _on_callback;
    bool _has_hook;
    uint16_t _hook;
    bool _notify_changed_over_dds;
    bool _low_mem_mode;
} rclc_parameter_server_t;
 
/* ===================================================================
 * rclc's functions
 * =================================================================== */

NROS_PUBLIC rcl_ret_t rclc_parameter_server_init_default(rclc_parameter_server_t* parameter_server,
                                                         struct rcl_node_t* node);
NROS_PUBLIC 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);
NROS_PUBLIC rcl_ret_t rclc_parameter_server_fini(rclc_parameter_server_t* parameter_server,
                                                 struct rcl_node_t* node);

NROS_PUBLIC 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);
NROS_PUBLIC 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);

NROS_PUBLIC rcl_ret_t rclc_add_parameter(rclc_parameter_server_t* parameter_server,
                                         const char* parameter_name, rclc_parameter_type_t type);
NROS_PUBLIC rcl_ret_t rclc_delete_parameter(rclc_parameter_server_t* parameter_server,
                                            const char* parameter_name);
 
NROS_PUBLIC rcl_ret_t rclc_parameter_set_bool(rclc_parameter_server_t* parameter_server,
                                              const char* parameter_name, bool value);
NROS_PUBLIC rcl_ret_t rclc_parameter_set_int(rclc_parameter_server_t* parameter_server,
                                             const char* parameter_name, int64_t value);
NROS_PUBLIC rcl_ret_t rclc_parameter_set_double(rclc_parameter_server_t* parameter_server,
                                                const char* parameter_name, double value);
NROS_PUBLIC rcl_ret_t rclc_parameter_get_bool(rclc_parameter_server_t* parameter_server,
                                              const char* parameter_name, bool* output);
NROS_PUBLIC rcl_ret_t rclc_parameter_get_int(rclc_parameter_server_t* parameter_server,
                                             const char* parameter_name, int64_t* output);
NROS_PUBLIC rcl_ret_t rclc_parameter_get_double(rclc_parameter_server_t* parameter_server,
                                                const char* parameter_name, double* output);
 
NROS_PUBLIC 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);
NROS_PUBLIC rcl_ret_t rclc_set_parameter_read_only(rclc_parameter_server_t* parameter_server,
                                                   const char* parameter_name, bool read_only);
NROS_PUBLIC 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);
NROS_PUBLIC 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);
 
/* ===================================================================
 * Extensions (nano-ros; rclc has no equivalent)
 * =================================================================== */

NROS_PUBLIC rcl_ret_t rclc_parameter_declare_bool(rclc_parameter_server_t* parameter_server,
                                                  const char* parameter_name, bool default_value);
NROS_PUBLIC rcl_ret_t rclc_parameter_declare_int(rclc_parameter_server_t* parameter_server,
                                                 const char* parameter_name, int64_t default_value);
NROS_PUBLIC rcl_ret_t rclc_parameter_declare_double(rclc_parameter_server_t* parameter_server,
                                                    const char* parameter_name,
                                                    double default_value);
NROS_PUBLIC rcl_ret_t rclc_parameter_declare_string(rclc_parameter_server_t* parameter_server,
                                                    const char* parameter_name,
                                                    const char* default_value);
 
NROS_PUBLIC rcl_ret_t rclc_parameter_set_string(rclc_parameter_server_t* parameter_server,
                                                const char* parameter_name, const char* value);
NROS_PUBLIC rcl_ret_t rclc_parameter_get_string(rclc_parameter_server_t* parameter_server,
                                                const char* parameter_name, char* output,
                                                size_t capacity);
 
/* Arrays, bounded by NROS_MAX_ARRAY_LEN (bytes: NROS_MAX_BYTE_ARRAY_LEN). A get
 * writes the stored length to `*out_len` and returns `RCLC_RET_FULL` without
 * copying when it exceeds `capacity`. */
#define NROS__RCLC_ARRAY(NAME, T)                                                                  \
    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);
NROS__RCLC_ARRAY(bool, bool)
NROS__RCLC_ARRAY(int, int64_t)
NROS__RCLC_ARRAY(double, double)
NROS__RCLC_ARRAY(byte, uint8_t)
#undef NROS__RCLC_ARRAY
 
/* String arrays: `data` is `len` C strings, each at most NROS_MAX_STRING_VALUE_LEN
 * bytes. A get copies into `capacity` rows of `stride` bytes, each
 * NUL-terminated, writes the stored length to `*out_len`, and returns
 * `RCLC_RET_FULL` without copying when the rows or a row are too small. */
NROS_PUBLIC 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);
NROS_PUBLIC 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);
NROS_PUBLIC 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);

NROS_PUBLIC rclc_parameter_type_t rclc_parameter_get_type(rclc_parameter_server_t* parameter_server,
                                                          const char* parameter_name);
NROS_PUBLIC 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);
NROS_PUBLIC 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);
NROS_PUBLIC 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);
NROS_PUBLIC 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);
 
#ifdef __cplusplus
}
#endif
 
#endif /* RCLC_PARAMETER__RCLC_PARAMETER_H_ */