rmw_entity.h

Go to the documentation of this file.

#ifndef NROS_RMW_ENTITY_H
#define NROS_RMW_ENTITY_H
 
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "nros/rmw_ret.h"   /* the two pure functions below return rmw_ret_t */
 
/* ------------------------------------------------------------------ */
/* QoS profile — full DDS shape (matches `rmw_qos_profile_t`)          */
/* ------------------------------------------------------------------ */
 
/* Policy values carry UPSTREAM's numbering — phase-376 W5/B2.
 *
 * They did not until 2026-08-24, and the disagreement was not academic. Ours
 * were a dense 0/1 pair per policy, which put a DIFFERENT meaning on the same
 * integer:
 *
 *     value | upstream                          | ours (before)
 *     ------|-----------------------------------|-------------------
 *       0   | *_SYSTEM_DEFAULT                  | BEST_EFFORT / VOLATILE / KEEP_LAST
 *       1   | RELIABLE / TRANSIENT_LOCAL / KEEP_LAST | RELIABLE / TRANSIENT_LOCAL / KEEP_ALL
 *
 * so `HISTORY == 1` meant KEEP_LAST to upstream and KEEP_ALL to us — the two
 * opposite answers to the question. Liveliness was worse: MANUAL_BY_NODE and
 * MANUAL_BY_TOPIC were SWAPPED (2 and 3).
 *
 * These values cross the ABI. `rmw_qos_profile_check_compatible` is a name
 * upstream owns and we export, and the cyclonedds backend translates this
 * struct into real DDS QoS that a ROS peer matches against. A caller reasoning
 * in upstream's vocabulary got silently wrong policies. Same argument as W3.d
 * step B for the return codes: where a value crosses the boundary, upstream's
 * numbering is the only one that cannot be wrong.
 *
 * The names keep the `NROS_RMW_` prefix — as the return codes do — because the
 * set is ours to extend, not upstream's to define.
 */
 
#define NROS_RMW_RELIABILITY_SYSTEM_DEFAULT 0
#define NROS_RMW_RELIABILITY_RELIABLE       1
#define NROS_RMW_RELIABILITY_BEST_EFFORT    2
#define NROS_RMW_RELIABILITY_UNKNOWN        3
 
#define NROS_RMW_DURABILITY_SYSTEM_DEFAULT   0
#define NROS_RMW_DURABILITY_TRANSIENT_LOCAL  1
#define NROS_RMW_DURABILITY_VOLATILE         2
#define NROS_RMW_DURABILITY_UNKNOWN          3
 
#define NROS_RMW_HISTORY_SYSTEM_DEFAULT 0
#define NROS_RMW_HISTORY_KEEP_LAST      1
#define NROS_RMW_HISTORY_KEEP_ALL       2
#define NROS_RMW_HISTORY_UNKNOWN        3
 
typedef enum rmw_feature_t {
    RMW_FEATURE_MESSAGE_INFO_PUBLICATION_SEQUENCE_NUMBER = 0,
    RMW_FEATURE_MESSAGE_INFO_RECEPTION_SEQUENCE_NUMBER   = 1,
} rmw_feature_t;
 
typedef int64_t rmw_time_point_value_t;
 
#define RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED UINT64_MAX
 
#define RMW_GID_STORAGE_SIZE 24u
 
typedef struct rmw_byte_span_t {
    const uint8_t *data;
    size_t len;
} rmw_byte_span_t;
 
typedef struct rmw_mut_byte_span_t {
    uint8_t *data;
    size_t capacity;
    size_t len;
} rmw_mut_byte_span_t;
 
typedef struct rmw_message_type_support_t {
    const char *type_name;
    const char *type_hash;
} rmw_message_type_support_t;
 
typedef struct rmw_service_type_support_t {
    const char *type_name;
    const char *type_hash;
} rmw_service_type_support_t;
 
typedef struct rmw_gid_t {
    const char *implementation_identifier;
    uint8_t data[RMW_GID_STORAGE_SIZE];
} rmw_gid_t;
 
 
typedef struct rmw_message_info_t {
    rmw_time_point_value_t source_timestamp;
    rmw_time_point_value_t received_timestamp;
    uint64_t publication_sequence_number;
    uint64_t reception_sequence_number;
    rmw_gid_t publisher_gid;
    bool from_intra_process;
} rmw_message_info_t;
 
typedef enum rmw_liveliness_kind_t {
    NROS_RMW_LIVELINESS_SYSTEM_DEFAULT    = 0,
    NROS_RMW_LIVELINESS_AUTOMATIC         = 1,
    NROS_RMW_LIVELINESS_MANUAL_BY_NODE    = 2,
    NROS_RMW_LIVELINESS_MANUAL_BY_TOPIC   = 3,
    NROS_RMW_LIVELINESS_UNKNOWN           = 4,
} rmw_liveliness_kind_t;
 
typedef struct rmw_qos_profile_t {
    /* ---- 8-byte core, layout-equivalent to the original subset ---- */
    uint8_t  reliability;     
    uint8_t  durability;      
    uint8_t  history;         
    uint8_t  liveliness_kind; 
    uint16_t depth;
    uint16_t _reserved0;      
    /* ---- 16-byte extension (Phase 109) ---- */
    uint32_t deadline_ms;
 
    uint32_t lifespan_ms;
 
    uint32_t liveliness_lease_ms;
 
    uint8_t  avoid_ros_namespace_conventions;
    uint8_t  _reserved1[3];   
} rmw_qos_profile_t;
 
 
/* ====================================================================
 * Phase 376 W4 — the two PURE functions.
 *
 * Plain exported C functions, deliberately NOT vtable slots, and the reason is
 * the campaign's own rule read the other way round: a vtable slot is the
 * mechanism for letting backends DIFFER, and these two must not. Both compute
 * over types this header defines; if two backends disagreed about whether a QoS
 * pair is compatible, or whether two gids name the same entity, that is a
 * DEFECT with as many places to fix it as there are backends.
 *
 * Three supporting reasons:
 *
 *  - The useful call sites have no vtable to dispatch through. QoS
 *    compatibility is wanted at `create_*` time (that is what produces
 *    `NROS_RMW_RET_INCOMPATIBLE_QOS`), in codegen'd validation, and in host
 *    tooling with no session. Neither function takes an entity, so a slot would
 *    force a caller to invent a session — and neither could be called BEFORE a
 *    backend registers, which is exactly when create-time validation runs.
 *
 *  - Upstream is not evidence for a slot. `rmw_qos_profile_check_compatible`
 *    lives in `rmw/qos_profiles.h` and is defined by librmw ITSELF; it appears
 *    in the implementation contract only because each `librmw_*_cpp.so`
 *    statically links librmw and re-exports it. That is plugin packaging, not
 *    semantics, and we load no plugin.
 *
 *  - Precedent: `nros_rmw_cffi_register_named` and friends are declared here
 *    and defined once in Rust with `#[no_mangle]`, so `nros-rmw-abi` stays a
 *    header-only INTERFACE target — no new compiled TU, no new link edge.
 *    (`static inline` was the alternative and is worse: bindgen does not emit
 *    it, so RFC-0054 would force a SECOND Rust implementation, which is the
 *    first reason again.)
 * ==================================================================== */
 
typedef enum rmw_qos_compatibility_type_t {
    RMW_QOS_COMPATIBILITY_OK      = 0,
    RMW_QOS_COMPATIBILITY_WARNING = 1,
    RMW_QOS_COMPATIBILITY_ERROR   = 2,
} rmw_qos_compatibility_type_t;
 
typedef enum nros_rmw_qos_clash_t {
    NROS_RMW_QOS_CLASH_NONE             = 0,
    NROS_RMW_QOS_CLASH_RELIABILITY      = 1u << 0,
    NROS_RMW_QOS_CLASH_DURABILITY       = 1u << 1,
    NROS_RMW_QOS_CLASH_DEADLINE         = 1u << 2,
    NROS_RMW_QOS_CLASH_LIVELINESS_KIND  = 1u << 3,
    NROS_RMW_QOS_CLASH_LIVELINESS_LEASE = 1u << 4,
} nros_rmw_qos_clash_t;
 
rmw_ret_t nros_rmw_qos_incompatibility_mask(
    rmw_qos_profile_t offered, rmw_qos_profile_t requested,
    rmw_qos_compatibility_type_t *compatibility, uint32_t *clash_mask);
 
rmw_ret_t rmw_qos_profile_check_compatible(
    rmw_qos_profile_t publisher_profile, rmw_qos_profile_t subscription_profile,
    rmw_qos_compatibility_type_t *compatibility, char *reason, size_t reason_size);
 
rmw_ret_t rmw_compare_gids_equal(const rmw_gid_t *gid1, const rmw_gid_t *gid2,
    bool *result);
 
typedef enum rmw_log_severity_t {
    RMW_LOG_SEVERITY_UNSET = 0,
    RMW_LOG_SEVERITY_DEBUG = 10,
    RMW_LOG_SEVERITY_INFO  = 20,
    RMW_LOG_SEVERITY_WARN  = 30,
    RMW_LOG_SEVERITY_ERROR = 40,
    RMW_LOG_SEVERITY_FATAL = 50,
} rmw_log_severity_t;
 
typedef enum rmw_endpoint_type_t {
    RMW_ENDPOINT_INVALID      = 0,
    RMW_ENDPOINT_PUBLISHER    = 1,
    RMW_ENDPOINT_SUBSCRIPTION = 2,
} rmw_endpoint_type_t;
 
typedef struct rmw_topic_endpoint_info_t {
    const char *node_name;
    const char *node_namespace;
    const char *topic_type;
    rmw_endpoint_type_t endpoint_type;
    rmw_gid_t endpoint_gid;
    rmw_qos_profile_t qos_profile;
} rmw_topic_endpoint_info_t;
             /* 24 bytes */
 
typedef enum rmw_transport_protocol_t {
    RMW_TRANSPORT_PROTOCOL_UNKNOWN = 0,
    RMW_TRANSPORT_PROTOCOL_UDP     = 1,
    RMW_TRANSPORT_PROTOCOL_TCP     = 2,
    RMW_TRANSPORT_PROTOCOL_COUNT   = 3,
} rmw_transport_protocol_t;
 
typedef enum rmw_internet_protocol_t {
    RMW_INTERNET_PROTOCOL_UNKNOWN = 0,
    RMW_INTERNET_PROTOCOL_IPV4    = 1,
    RMW_INTERNET_PROTOCOL_IPV6    = 2,
    RMW_INTERNET_PROTOCOL_COUNT   = 3,
} rmw_internet_protocol_t;
 
#define RMW_INET_ADDRSTRLEN 48
 
typedef struct rmw_network_flow_endpoint_t {
    rmw_transport_protocol_t transport_protocol;
    rmw_internet_protocol_t  internet_protocol;
    uint16_t                 transport_port;
    uint32_t                 flow_label;
    uint8_t                  dscp;
    char                     internet_address[RMW_INET_ADDRSTRLEN];
} rmw_network_flow_endpoint_t;
 
typedef bool (*rmw_network_flow_endpoint_visit_fn)(void *ctx,
    const rmw_network_flow_endpoint_t *endpoint);
 
typedef void (*rmw_content_filter_visit_fn)(void *ctx,
    const char *expression, const char *const *parameters, size_t parameter_count);
 
#define NROS_RMW_DURATION_INFINITE_MS  UINT32_MAX
 
/* ------------------------------------------------------------------ */
/* Entity options — transport hints (phase-301, issue 0240)           */
/* ------------------------------------------------------------------ */
 
typedef struct rmw_session_property_t {
    const char *key;   
    const char *value; 
} rmw_session_property_t;
 
#define RMW_SESSION_MAX_PROPERTIES 16
 
typedef struct rmw_session_options_t {
    uint8_t localhost_only;
    uint8_t _reserved[7];     
    const char *enclave;
    const rmw_session_property_t *properties;
    size_t property_count; 
} rmw_session_options_t;
 
typedef struct rmw_publisher_options_t {
    uint8_t tx_express;
    uint8_t _reserved[7];     
} rmw_publisher_options_t;
 
typedef struct rmw_subscription_options_t {
    uint32_t rx_buffer_hint;
    uint8_t  _reserved[4];    
} rmw_subscription_options_t;
 
/* ---- Standard QoS profile constants ---- */
/* Defined as static const initialisers at the bottom of this
 * header so they're available in every compilation unit that
 * includes it. Match the field set of upstream
 * `rmw_qos_profile_default` etc. */
 
#define NROS_RMW_QOS_PROFILE_DEFAULT \
    ((rmw_qos_profile_t){                                                   \
        .reliability = NROS_RMW_RELIABILITY_RELIABLE,                    \
        .durability  = NROS_RMW_DURABILITY_VOLATILE,                     \
        .history     = NROS_RMW_HISTORY_KEEP_LAST,                       \
        .liveliness_kind = NROS_RMW_LIVELINESS_AUTOMATIC,                \
        .depth       = 10,                                               \
        ._reserved0  = 0,                                                \
        .deadline_ms = 0,                                                \
        .lifespan_ms = 0,                                                \
        .liveliness_lease_ms = 0,                                        \
        .avoid_ros_namespace_conventions = 0,                            \
        ._reserved1  = {0, 0, 0},                                        \
    })
 
#define NROS_RMW_QOS_PROFILE_SENSOR_DATA \
    ((rmw_qos_profile_t){                                                   \
        .reliability = NROS_RMW_RELIABILITY_BEST_EFFORT,                 \
        .durability  = NROS_RMW_DURABILITY_VOLATILE,                     \
        .history     = NROS_RMW_HISTORY_KEEP_LAST,                       \
        .liveliness_kind = NROS_RMW_LIVELINESS_AUTOMATIC,                \
        .depth       = 5,                                                \
        ._reserved0  = 0,                                                \
        .deadline_ms = 0,                                                \
        .lifespan_ms = 0,                                                \
        .liveliness_lease_ms = 0,                                        \
        .avoid_ros_namespace_conventions = 0,                            \
        ._reserved1  = {0, 0, 0},                                        \
    })
 
#define NROS_RMW_QOS_PROFILE_SERVICES_DEFAULT  NROS_RMW_QOS_PROFILE_DEFAULT
 
#define NROS_RMW_QOS_PROFILE_PARAMETERS \
    ((rmw_qos_profile_t){                                                   \
        .reliability = NROS_RMW_RELIABILITY_RELIABLE,                    \
        .durability  = NROS_RMW_DURABILITY_VOLATILE,                     \
        .history     = NROS_RMW_HISTORY_KEEP_LAST,                       \
        .liveliness_kind = NROS_RMW_LIVELINESS_AUTOMATIC,                \
        .depth       = 1000,                                             \
        ._reserved0  = 0,                                                \
        .deadline_ms = 0,                                                \
        .lifespan_ms = 0,                                                \
        .liveliness_lease_ms = 0,                                        \
        .avoid_ros_namespace_conventions = 0,                            \
        ._reserved1  = {0, 0, 0},                                        \
    })
 
#define NROS_RMW_QOS_PROFILE_SYSTEM_DEFAULT                                 \
    ((rmw_qos_profile_t){                                                   \
        .reliability = NROS_RMW_RELIABILITY_SYSTEM_DEFAULT,              \
        .durability  = NROS_RMW_DURABILITY_SYSTEM_DEFAULT,               \
        .history     = NROS_RMW_HISTORY_SYSTEM_DEFAULT,                  \
        .liveliness_kind = NROS_RMW_LIVELINESS_SYSTEM_DEFAULT,           \
        .depth       = 0,                                                \
        ._reserved0  = 0,                                                \
        .deadline_ms = 0,                                                \
        .lifespan_ms = 0,                                                \
        .liveliness_lease_ms = 0,                                        \
        .avoid_ros_namespace_conventions = 0,                            \
        ._reserved1  = {0, 0, 0},                                        \
    })
 
/* ------------------------------------------------------------------ */
/* Entity structs                                                     */
/* ------------------------------------------------------------------ */
 
typedef struct rmw_session_t {
    const char *node_name;
    const char *namespace_;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_session_t;
 
typedef struct rmw_node_t {
    const char *name;
    const char *namespace_;
    rmw_session_t *session;
    uint8_t _reserved[8];
    void *backend_data;
} rmw_node_t;
 
typedef struct rmw_publisher_t {
    const char    *topic_name;
    const char    *type_name;
    rmw_qos_profile_t qos;
    bool           can_loan_messages;
    uint8_t        _reserved[7];
    void          *backend_data;
} rmw_publisher_t;
 
typedef struct rmw_subscription_t {
    const char    *topic_name;
    const char    *type_name;
    rmw_qos_profile_t qos;
    bool           can_loan_messages;
    uint8_t        _reserved[7];
    void          *backend_data;
} rmw_subscription_t;
 
typedef struct rmw_service_t {
    const char *service_name;
    const char *type_name;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_service_t;
 
typedef struct rmw_client_t {
    const char *service_name;
    const char *type_name;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_client_t;
 
#endif /* NROS_RMW_ENTITY_H */