zerodds-c-api 1.0.0-rc.4

/*
 * zerodds.h — ZeroDDS C-FFI (auto-generated by cbindgen, do not edit).
 *
 * This header is the language-agnostic hub used by:
 *  - C++ binding (psm-cxx Method-Bodies in `crates/cpp/`)
 *  - C# binding (P/Invoke wrapper in `crates/cs/`)
 *  - TypeScript binding (node-ffi-napi + WASM, `crates/ts-node-runtime/`)
 *  - Embedded C clients
 *  - Apex.AI performance_test ZeroDDS-Plugin
 *  - ROS 2 RMW adapter (rmw_zerodds)
 *
 * Java + Python use their own native bridges (jni-rs / pyo3) and
 * do NOT go through this header.
 *
 * Memory ownership: handles returned by zerodds_*_create() must be
 * released with the matching zerodds_*_destroy() — no auto-cleanup
 * on FFI boundaries. Bytes returned via zerodds_reader_take() must
 * be released with zerodds_buffer_free().
 */

/*
 * Condition handle types are OPAQUE on the C ABI (the binding holds an
 * opaque pointer only). On the Rust side they are repr(C) so the generic
 * condition dispatcher can read the ConditionKind discriminant at offset 0,
 * but their fields (incl. String/Vec in QueryCondition) must NOT leak into
 * this header - hence they are excluded from cbindgen and forward-declared
 * here. See crates/zerodds-c-api/src/condition_ffi.rs (F-PSM-CXX-readcond-segv).
 */
typedef struct zerodds_ZeroDdsGuardCondition zerodds_ZeroDdsGuardCondition;
typedef struct zerodds_ZeroDdsStatusCondition zerodds_ZeroDdsStatusCondition;
typedef struct zerodds_ZeroDdsReadCondition zerodds_ZeroDdsReadCondition;
typedef struct zerodds_ZeroDdsQueryCondition zerodds_ZeroDdsQueryCondition;


#ifndef ZERODDS_H
#define ZERODDS_H

/* WARNING: AUTO-GENERATED — DO NOT EDIT */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

typedef void (*zerodds_Option_ZeroDdsDataCallback)(void *user_data, const uint8_t *payload, size_t payload_len, uint8_t representation, uint8_t big_endian);

typedef int (*zerodds_Option_ZeroDdsDecodeFn)(const uint8_t *buf, size_t len, void *out_sample);

typedef int (*zerodds_Option_ZeroDdsDecodeReprFn)(const uint8_t *buf, size_t len, uint8_t representation, void *out_sample);

typedef int (*zerodds_Option_ZeroDdsEncodeFn)(const void *sample, uint8_t *out_buf, size_t out_cap, size_t *out_len);

typedef struct zerodds_Option_ZeroDdsEndpointCallback zerodds_Option_ZeroDdsEndpointCallback;

typedef int (*zerodds_Option_ZeroDdsKeyHashFn)(const void *sample, uint8_t *out_hash);

typedef void (*zerodds_Option_ZeroDdsSampleFreeFn)(void *sample);

typedef struct zerodds_Option_ZeroDdsTopicCallback zerodds_Option_ZeroDdsTopicCallback;

/**
 * Opaque BuiltinSubscriber-Handle (Spec §2.2.2.2.1.7).
 */
typedef struct zerodds_ZeroDdsBuiltinSubscriber zerodds_ZeroDdsBuiltinSubscriber;

/**
 * ContentFilteredTopic (Spec §2.2.2.3.3).
 */
typedef struct zerodds_ZeroDdsContentFilteredTopic zerodds_ZeroDdsContentFilteredTopic;

/**
 * DataReader (Spec §2.2.2.5.2).
 */
typedef struct zerodds_ZeroDdsDataReader zerodds_ZeroDdsDataReader;

/**
 * DataWriter (Spec §2.2.2.4.2).
 */
typedef struct zerodds_ZeroDdsDataWriter zerodds_ZeroDdsDataWriter;

/**
 * DomainParticipant (Spec §2.2.2.2.1.1).
 */
typedef struct zerodds_ZeroDdsDomainParticipant zerodds_ZeroDdsDomainParticipant;

/**
 * Singleton DomainParticipantFactory (Spec §2.2.2.2.1).
 */
typedef struct zerodds_ZeroDdsDomainParticipantFactory zerodds_ZeroDdsDomainParticipantFactory;

/**
 * Publisher (Spec §2.2.2.4.1).
 */
typedef struct zerodds_ZeroDdsPublisher zerodds_ZeroDdsPublisher;

/**
 * Opaque reader handle.
 */
typedef struct zerodds_ZeroDdsReader zerodds_ZeroDdsReader;

/**
 * Opaque runtime handle. Holds the DcpsRuntime + spawned threads.
 */
typedef struct zerodds_ZeroDdsRuntime zerodds_ZeroDdsRuntime;

/**
 * Opaque builder for DDS-Security setup. All 6 path fields
 * must be set before `zerodds_runtime_create_secure` may be called
 * — otherwise NULL return + stderr diag.
 */
typedef struct zerodds_ZeroDdsSecurityConfig zerodds_ZeroDdsSecurityConfig;

/**
 * Subscriber (Spec §2.2.2.5.1).
 */
typedef struct zerodds_ZeroDdsSubscriber zerodds_ZeroDdsSubscriber;

/**
 * Topic (Spec §2.2.2.3.1).
 */
typedef struct zerodds_ZeroDdsTopic zerodds_ZeroDdsTopic;

/**
 * WaitSet (Spec §2.2.2.1.2.1.5).
 */
typedef struct zerodds_ZeroDdsWaitSet zerodds_ZeroDdsWaitSet;

/**
 * Opaque writer handle.
 */
typedef struct zerodds_ZeroDdsWriter zerodds_ZeroDdsWriter;

/**
 * `DCPSParticipant` sample (Spec §2.2.5.1).
 */
typedef struct zerodds_ZeroDdsParticipantBuiltinTopicData {
  /**
   * 16-byte GUID.
   */
  uint8_t guid[16];
  /**
   * Pointer to UserData bytes (static over the `dp` lifetime in the RC1
   * snapshot — the caller copies if it outlives the data).
   */
  const uint8_t *user_data;
  /**
   * UserData length.
   */
  uintptr_t user_data_len;
} zerodds_ZeroDdsParticipantBuiltinTopicData;

/**
 * `DCPSTopic` sample (Spec §2.2.5.2).
 */
typedef struct zerodds_ZeroDdsTopicBuiltinTopicData {
  /**
   * Synthetic topic key (16 byte).
   */
  uint8_t key[16];
  /**
   * Topic name as a C string (heap-allocated; the caller must
   * call `zerodds_string_free`).
   */
  char *name;
  /**
   * Type name (heap-allocated; the caller must call `zerodds_string_free`).
   */
  char *type_name;
  /**
   * Durability kind (0=Volatile, 1=TransientLocal, 2=Transient, 3=Persistent).
   */
  uint32_t durability_kind;
  /**
   * Reliability kind (1=BestEffort, 2=Reliable).
   */
  uint32_t reliability_kind;
} zerodds_ZeroDdsTopicBuiltinTopicData;

/**
 * UserDataQosPolicy.
 */
typedef struct zerodds_ZeroDdsUserDataQosPolicy {
  /**
   * Pointer to bytes (Caller-owned).
   */
  const uint8_t *value;
  /**
   * Length.
   */
  uintptr_t value_len;
} zerodds_ZeroDdsUserDataQosPolicy;

/**
 * EntityFactoryQosPolicy.
 */
typedef struct zerodds_ZeroDdsEntityFactoryQosPolicy {
  /**
   * autoenable_created_entities.
   */
  bool autoenable_created_entities;
} zerodds_ZeroDdsEntityFactoryQosPolicy;

/**
 * DomainParticipantQos.
 */
typedef struct zerodds_ZeroDdsDomainParticipantQos {
  /**
   * UserData.
   */
  struct zerodds_ZeroDdsUserDataQosPolicy user_data;
  /**
   * EntityFactory.
   */
  struct zerodds_ZeroDdsEntityFactoryQosPolicy entity_factory;
} zerodds_ZeroDdsDomainParticipantQos;

/**
 * DurabilityQosPolicy.
 */
typedef struct zerodds_ZeroDdsDurabilityQosPolicy {
  /**
   * Kind (0=Volatile, 1=TransientLocal, 2=Transient, 3=Persistent).
   */
  uint32_t kind;
} zerodds_ZeroDdsDurabilityQosPolicy;

/**
 * Duration (Spec §2.2.3.5 + IDL §9.3.2). seconds + nanoseconds form.
 */
typedef struct zerodds_ZeroDdsDuration {
  /**
   * Seconds.
   */
  int32_t sec;
  /**
   * Nanoseconds.
   */
  uint32_t nanosec;
} zerodds_ZeroDdsDuration;
/**
 * INFINITE marker.
 */
#define zerodds_ZeroDdsDuration_INFINITE (zerodds_ZeroDdsDuration){ .sec = INT32_MAX, .nanosec = UINT32_MAX }

/**
 * DurabilityServiceQosPolicy.
 */
typedef struct zerodds_ZeroDdsDurabilityServiceQosPolicy {
  /**
   * service_cleanup_delay.
   */
  struct zerodds_ZeroDdsDuration service_cleanup_delay;
  /**
   * history_kind (0=KeepLast, 1=KeepAll).
   */
  uint32_t history_kind;
  /**
   * history_depth.
   */
  int32_t history_depth;
  /**
   * max_samples.
   */
  int32_t max_samples;
  /**
   * max_instances.
   */
  int32_t max_instances;
  /**
   * max_samples_per_instance.
   */
  int32_t max_samples_per_instance;
} zerodds_ZeroDdsDurabilityServiceQosPolicy;

/**
 * DeadlineQosPolicy.
 */
typedef struct zerodds_ZeroDdsDeadlineQosPolicy {
  /**
   * period.
   */
  struct zerodds_ZeroDdsDuration period;
} zerodds_ZeroDdsDeadlineQosPolicy;

/**
 * LatencyBudgetQosPolicy.
 */
typedef struct zerodds_ZeroDdsLatencyBudgetQosPolicy {
  /**
   * duration.
   */
  struct zerodds_ZeroDdsDuration duration;
} zerodds_ZeroDdsLatencyBudgetQosPolicy;

/**
 * LivelinessQosPolicy.
 */
typedef struct zerodds_ZeroDdsLivelinessQosPolicy {
  /**
   * Kind.
   */
  uint32_t kind;
  /**
   * lease_duration.
   */
  struct zerodds_ZeroDdsDuration lease_duration;
} zerodds_ZeroDdsLivelinessQosPolicy;

/**
 * ReliabilityQosPolicy.
 */
typedef struct zerodds_ZeroDdsReliabilityQosPolicy {
  /**
   * Kind (1=BestEffort, 2=Reliable).
   */
  uint32_t kind;
  /**
   * max_blocking_time.
   */
  struct zerodds_ZeroDdsDuration max_blocking_time;
} zerodds_ZeroDdsReliabilityQosPolicy;

/**
 * DestinationOrderQosPolicy.
 */
typedef struct zerodds_ZeroDdsDestinationOrderQosPolicy {
  /**
   * Kind (0=ByReception, 1=BySource).
   */
  uint32_t kind;
} zerodds_ZeroDdsDestinationOrderQosPolicy;

/**
 * HistoryQosPolicy.
 */
typedef struct zerodds_ZeroDdsHistoryQosPolicy {
  /**
   * Kind (0=KeepLast, 1=KeepAll).
   */
  uint32_t kind;
  /**
   * Depth (for KeepLast).
   */
  int32_t depth;
} zerodds_ZeroDdsHistoryQosPolicy;

/**
 * ResourceLimitsQosPolicy.
 */
typedef struct zerodds_ZeroDdsResourceLimitsQosPolicy {
  /**
   * max_samples.
   */
  int32_t max_samples;
  /**
   * max_instances.
   */
  int32_t max_instances;
  /**
   * max_samples_per_instance.
   */
  int32_t max_samples_per_instance;
} zerodds_ZeroDdsResourceLimitsQosPolicy;

/**
 * TransportPriorityQosPolicy.
 */
typedef struct zerodds_ZeroDdsTransportPriorityQosPolicy {
  /**
   * priority.
   */
  int32_t value;
} zerodds_ZeroDdsTransportPriorityQosPolicy;

/**
 * LifespanQosPolicy.
 */
typedef struct zerodds_ZeroDdsLifespanQosPolicy {
  /**
   * duration.
   */
  struct zerodds_ZeroDdsDuration duration;
} zerodds_ZeroDdsLifespanQosPolicy;

/**
 * OwnershipQosPolicy.
 */
typedef struct zerodds_ZeroDdsOwnershipQosPolicy {
  /**
   * Kind (0=Shared, 1=Exclusive).
   */
  uint32_t kind;
} zerodds_ZeroDdsOwnershipQosPolicy;

/**
 * TopicDataQosPolicy.
 */
typedef struct zerodds_ZeroDdsUserDataQosPolicy zerodds_ZeroDdsTopicDataQosPolicy;

/**
 * TopicQos.
 */
typedef struct zerodds_ZeroDdsTopicQos {
  /**
   * Durability.
   */
  struct zerodds_ZeroDdsDurabilityQosPolicy durability;
  /**
   * DurabilityService.
   */
  struct zerodds_ZeroDdsDurabilityServiceQosPolicy durability_service;
  /**
   * Deadline.
   */
  struct zerodds_ZeroDdsDeadlineQosPolicy deadline;
  /**
   * LatencyBudget.
   */
  struct zerodds_ZeroDdsLatencyBudgetQosPolicy latency_budget;
  /**
   * Liveliness.
   */
  struct zerodds_ZeroDdsLivelinessQosPolicy liveliness;
  /**
   * Reliability.
   */
  struct zerodds_ZeroDdsReliabilityQosPolicy reliability;
  /**
   * DestinationOrder.
   */
  struct zerodds_ZeroDdsDestinationOrderQosPolicy destination_order;
  /**
   * History.
   */
  struct zerodds_ZeroDdsHistoryQosPolicy history;
  /**
   * ResourceLimits.
   */
  struct zerodds_ZeroDdsResourceLimitsQosPolicy resource_limits;
  /**
   * TransportPriority.
   */
  struct zerodds_ZeroDdsTransportPriorityQosPolicy transport_priority;
  /**
   * Lifespan.
   */
  struct zerodds_ZeroDdsLifespanQosPolicy lifespan;
  /**
   * Ownership.
   */
  struct zerodds_ZeroDdsOwnershipQosPolicy ownership;
  /**
   * TopicData.
   */
  zerodds_ZeroDdsTopicDataQosPolicy topic_data;
} zerodds_ZeroDdsTopicQos;

/**
 * PresentationQosPolicy.
 */
typedef struct zerodds_ZeroDdsPresentationQosPolicy {
  /**
   * access_scope.
   */
  uint32_t access_scope;
  /**
   * coherent_access.
   */
  bool coherent_access;
  /**
   * ordered_access.
   */
  bool ordered_access;
} zerodds_ZeroDdsPresentationQosPolicy;

/**
 * PartitionQosPolicy. List of C-string pointers + count.
 */
typedef struct zerodds_ZeroDdsPartitionQosPolicy {
  /**
   * Array von C-String-Pointern (Caller-owned).
   */
  const char *const *names;
  /**
   * Count.
   */
  uintptr_t names_len;
} zerodds_ZeroDdsPartitionQosPolicy;

/**
 * GroupDataQosPolicy.
 */
typedef struct zerodds_ZeroDdsUserDataQosPolicy zerodds_ZeroDdsGroupDataQosPolicy;

/**
 * PublisherQos.
 */
typedef struct zerodds_ZeroDdsPublisherQos {
  /**
   * Presentation.
   */
  struct zerodds_ZeroDdsPresentationQosPolicy presentation;
  /**
   * Partition.
   */
  struct zerodds_ZeroDdsPartitionQosPolicy partition;
  /**
   * GroupData.
   */
  zerodds_ZeroDdsGroupDataQosPolicy group_data;
  /**
   * EntityFactory.
   */
  struct zerodds_ZeroDdsEntityFactoryQosPolicy entity_factory;
} zerodds_ZeroDdsPublisherQos;

/**
 * SubscriberQos.
 */
typedef struct zerodds_ZeroDdsPublisherQos zerodds_ZeroDdsSubscriberQos;

/**
 * OwnershipStrengthQosPolicy.
 */
typedef struct zerodds_ZeroDdsOwnershipStrengthQosPolicy {
  /**
   * strength.
   */
  int32_t value;
} zerodds_ZeroDdsOwnershipStrengthQosPolicy;

/**
 * WriterDataLifecycleQosPolicy.
 */
typedef struct zerodds_ZeroDdsWriterDataLifecycleQosPolicy {
  /**
   * autodispose_unregistered_instances.
   */
  bool autodispose_unregistered_instances;
} zerodds_ZeroDdsWriterDataLifecycleQosPolicy;

/**
 * DataWriterQos.
 */
typedef struct zerodds_ZeroDdsDataWriterQos {
  /**
   * Reliability.
   */
  struct zerodds_ZeroDdsReliabilityQosPolicy reliability;
  /**
   * Durability.
   */
  struct zerodds_ZeroDdsDurabilityQosPolicy durability;
  /**
   * DurabilityService.
   */
  struct zerodds_ZeroDdsDurabilityServiceQosPolicy durability_service;
  /**
   * Deadline.
   */
  struct zerodds_ZeroDdsDeadlineQosPolicy deadline;
  /**
   * LatencyBudget.
   */
  struct zerodds_ZeroDdsLatencyBudgetQosPolicy latency_budget;
  /**
   * Liveliness.
   */
  struct zerodds_ZeroDdsLivelinessQosPolicy liveliness;
  /**
   * DestinationOrder.
   */
  struct zerodds_ZeroDdsDestinationOrderQosPolicy destination_order;
  /**
   * Lifespan.
   */
  struct zerodds_ZeroDdsLifespanQosPolicy lifespan;
  /**
   * Ownership.
   */
  struct zerodds_ZeroDdsOwnershipQosPolicy ownership;
  /**
   * OwnershipStrength.
   */
  struct zerodds_ZeroDdsOwnershipStrengthQosPolicy ownership_strength;
  /**
   * Partition.
   */
  struct zerodds_ZeroDdsPartitionQosPolicy partition;
  /**
   * Presentation.
   */
  struct zerodds_ZeroDdsPresentationQosPolicy presentation;
  /**
   * History.
   */
  struct zerodds_ZeroDdsHistoryQosPolicy history;
  /**
   * ResourceLimits.
   */
  struct zerodds_ZeroDdsResourceLimitsQosPolicy resource_limits;
  /**
   * TransportPriority.
   */
  struct zerodds_ZeroDdsTransportPriorityQosPolicy transport_priority;
  /**
   * WriterDataLifecycle.
   */
  struct zerodds_ZeroDdsWriterDataLifecycleQosPolicy writer_data_lifecycle;
  /**
   * UserData.
   */
  struct zerodds_ZeroDdsUserDataQosPolicy user_data;
  /**
   * TopicData.
   */
  zerodds_ZeroDdsTopicDataQosPolicy topic_data;
  /**
   * GroupData.
   */
  zerodds_ZeroDdsGroupDataQosPolicy group_data;
} zerodds_ZeroDdsDataWriterQos;

/**
 * TimeBasedFilterQosPolicy.
 */
typedef struct zerodds_ZeroDdsTimeBasedFilterQosPolicy {
  /**
   * minimum_separation.
   */
  struct zerodds_ZeroDdsDuration minimum_separation;
} zerodds_ZeroDdsTimeBasedFilterQosPolicy;

/**
 * ReaderDataLifecycleQosPolicy.
 */
typedef struct zerodds_ZeroDdsReaderDataLifecycleQosPolicy {
  /**
   * autopurge_nowriter_samples_delay.
   */
  struct zerodds_ZeroDdsDuration autopurge_nowriter_samples_delay;
  /**
   * autopurge_disposed_samples_delay.
   */
  struct zerodds_ZeroDdsDuration autopurge_disposed_samples_delay;
} zerodds_ZeroDdsReaderDataLifecycleQosPolicy;

/**
 * DataReaderQos.
 */
typedef struct zerodds_ZeroDdsDataReaderQos {
  /**
   * Reliability.
   */
  struct zerodds_ZeroDdsReliabilityQosPolicy reliability;
  /**
   * Durability.
   */
  struct zerodds_ZeroDdsDurabilityQosPolicy durability;
  /**
   * Deadline.
   */
  struct zerodds_ZeroDdsDeadlineQosPolicy deadline;
  /**
   * LatencyBudget.
   */
  struct zerodds_ZeroDdsLatencyBudgetQosPolicy latency_budget;
  /**
   * Liveliness.
   */
  struct zerodds_ZeroDdsLivelinessQosPolicy liveliness;
  /**
   * DestinationOrder.
   */
  struct zerodds_ZeroDdsDestinationOrderQosPolicy destination_order;
  /**
   * Ownership.
   */
  struct zerodds_ZeroDdsOwnershipQosPolicy ownership;
  /**
   * Partition.
   */
  struct zerodds_ZeroDdsPartitionQosPolicy partition;
  /**
   * Presentation.
   */
  struct zerodds_ZeroDdsPresentationQosPolicy presentation;
  /**
   * History.
   */
  struct zerodds_ZeroDdsHistoryQosPolicy history;
  /**
   * ResourceLimits.
   */
  struct zerodds_ZeroDdsResourceLimitsQosPolicy resource_limits;
  /**
   * TimeBasedFilter.
   */
  struct zerodds_ZeroDdsTimeBasedFilterQosPolicy time_based_filter;
  /**
   * ReaderDataLifecycle.
   */
  struct zerodds_ZeroDdsReaderDataLifecycleQosPolicy reader_data_lifecycle;
  /**
   * UserData.
   */
  struct zerodds_ZeroDdsUserDataQosPolicy user_data;
  /**
   * TopicData.
   */
  zerodds_ZeroDdsTopicDataQosPolicy topic_data;
  /**
   * GroupData.
   */
  zerodds_ZeroDdsGroupDataQosPolicy group_data;
} zerodds_ZeroDdsDataReaderQos;

/**
 * `DCPSSubscription` sample (Spec §2.2.5.4).
 */
typedef struct zerodds_ZeroDdsSubscriptionBuiltinTopicData {
  /**
   * Endpoint GUID (reader).
   */
  uint8_t key[16];
  /**
   * Owning participant GUID.
   */
  uint8_t participant_key[16];
  /**
   * Topic name (heap-allocated).
   */
  char *topic_name;
  /**
   * Type name (heap-allocated).
   */
  char *type_name;
  /**
   * Durability.
   */
  uint32_t durability_kind;
  /**
   * Reliability.
   */
  uint32_t reliability_kind;
  /**
   * Ownership.
   */
  uint32_t ownership_kind;
  /**
   * Liveliness lease in seconds.
   */
  int32_t liveliness_lease_seconds;
  /**
   * Deadline period in seconds.
   */
  int32_t deadline_seconds;
} zerodds_ZeroDdsSubscriptionBuiltinTopicData;

/**
 * SampleInfo (Spec §2.2.2.5.4 + DDS-PSM-Cxx §7.5.8.1).
 */
typedef struct zerodds_ZeroDdsSampleInfo {
  /**
   * Sample-state bit (1=READ, 2=NOT_READ).
   */
  uint32_t sample_state;
  /**
   * View state (1=NEW, 2=NOT_NEW).
   */
  uint32_t view_state;
  /**
   * Instance state (1=ALIVE, 2=NOT_ALIVE_DISPOSED, 4=NOT_ALIVE_NO_WRITERS).
   */
  uint32_t instance_state;
  /**
   * disposed_generation_count.
   */
  int32_t disposed_generation_count;
  /**
   * no_writers_generation_count.
   */
  int32_t no_writers_generation_count;
  /**
   * sample_rank.
   */
  int32_t sample_rank;
  /**
   * generation_rank.
   */
  int32_t generation_rank;
  /**
   * absolute_generation_rank.
   */
  int32_t absolute_generation_rank;
  /**
   * source_timestamp seconds.
   */
  int32_t source_timestamp_sec;
  /**
   * source_timestamp nanoseconds.
   */
  uint32_t source_timestamp_nanosec;
  /**
   * Instance handle.
   */
  uint64_t instance_handle;
  /**
   * Publication handle (writer-GUID hash).
   */
  uint64_t publication_handle;
  /**
   * `true` if the payload actually has data (vs. a lifecycle marker).
   */
  bool valid_data;
  /**
   * XCDR version of the payload from the encapsulation header (RTPS 2.5
   * §10.5): `0` = XCDR1 (CDR/PL_CDR), `1` = XCDR2 (CDR2/D_CDR2/PL_CDR2).
   * The typed consumer needs this to apply the correct alignment rule.
   * `0` for lifecycle markers (no payload).
   */
  uint8_t representation;
  /**
   * Wire byte order of the payload: `0` = little-endian (the canonical
   * XCDR2 wire), `1` = big-endian — from the encapsulation representation
   * identifier's low bit. The typed consumer dispatches its little-endian
   * vs big-endian decoder on this. `0` for lifecycle markers.
   */
  uint8_t big_endian;
} zerodds_ZeroDdsSampleInfo;

/**
 * Sample array (Spec §5 mini-spec).
 */
typedef struct zerodds_ZeroDdsSampleArray {
  /**
   * Array of payload pointers.
   */
  uint8_t **buffers;
  /**
   * Array of payload lengths.
   */
  uintptr_t *lengths;
  /**
   * Array of SampleInfos.
   */
  struct zerodds_ZeroDdsSampleInfo *infos;
  /**
   * Number of samples.
   */
  uintptr_t count;
  /**
   * Internal loan token (pointer to a `Vec<UserSample>` box). Freed
   * by `return_loan`.
   */
  void *loan_token;
} zerodds_ZeroDdsSampleArray;

/**
 * `DCPSPublication` sample (Spec §2.2.5.3).
 */
typedef struct zerodds_ZeroDdsPublicationBuiltinTopicData {
  /**
   * Endpoint GUID (writer).
   */
  uint8_t key[16];
  /**
   * Owning participant GUID.
   */
  uint8_t participant_key[16];
  /**
   * Topic name (heap-allocated; via `zerodds_string_free`).
   */
  char *topic_name;
  /**
   * Type name (heap-allocated).
   */
  char *type_name;
  /**
   * Durability.
   */
  uint32_t durability_kind;
  /**
   * Reliability.
   */
  uint32_t reliability_kind;
  /**
   * Ownership (0=Shared, 1=Exclusive).
   */
  uint32_t ownership_kind;
  /**
   * Ownership strength.
   */
  int32_t ownership_strength;
  /**
   * Liveliness lease in seconds.
   */
  int32_t liveliness_lease_seconds;
  /**
   * Deadline period in seconds.
   */
  int32_t deadline_seconds;
  /**
   * Lifespan duration in seconds.
   */
  int32_t lifespan_seconds;
} zerodds_ZeroDdsPublicationBuiltinTopicData;

/**
 * DomainParticipantFactoryQos.
 */
typedef struct zerodds_ZeroDdsDomainParticipantFactoryQos {
  /**
   * EntityFactory.
   */
  struct zerodds_ZeroDdsEntityFactoryQosPolicy entity_factory;
} zerodds_ZeroDdsDomainParticipantFactoryQos;

/**
 * `DomainParticipantListener` — Spec §2.2.4.2.1.
 *
 * Alle Felder sind optional (NULL-Pointer = Callback ignoriert).
 * `user_data` wird unveraendert an jeden Callback gereicht.
 */
typedef struct zerodds_ZeroDdsDomainParticipantListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Inconsistent-Topic.
   */
  void (*on_inconsistent_topic)(void*, struct zerodds_ZeroDdsTopic*);
  /**
   * Aggregator: Data-On-Readers (Subscriber-Bubble-Up).
   */
  void (*on_data_on_readers)(void*, struct zerodds_ZeroDdsSubscriber*);
} zerodds_ZeroDdsDomainParticipantListener;

/**
 * `PublisherListener` — Spec §2.2.4.2.2.
 */
typedef struct zerodds_ZeroDdsPublisherListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Aggregator-Pfad: alle Writer-Status-Bubble-Ups.
   */
  void (*on_offered_deadline_missed)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Liveliness lost.
   */
  void (*on_liveliness_lost)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Offered-Incompatible-QoS.
   */
  void (*on_offered_incompatible_qos)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Publication-matched.
   */
  void (*on_publication_matched)(void*, struct zerodds_ZeroDdsDataWriter*);
} zerodds_ZeroDdsPublisherListener;

/**
 * `SubscriberListener` — Spec §2.2.4.2.3.
 */
typedef struct zerodds_ZeroDdsSubscriberListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Data-On-Readers (Sub-Aggregator).
   */
  void (*on_data_on_readers)(void*, struct zerodds_ZeroDdsSubscriber*);
  /**
   * Sample-Lost (Reader-Bubble-Up).
   */
  void (*on_sample_lost)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Sample-Rejected.
   */
  void (*on_sample_rejected)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Liveliness-Changed.
   */
  void (*on_liveliness_changed)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Subscription-Matched.
   */
  void (*on_subscription_matched)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Requested-Deadline-Missed.
   */
  void (*on_requested_deadline_missed)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Requested-Incompatible-QoS.
   */
  void (*on_requested_incompatible_qos)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Data-Available.
   */
  void (*on_data_available)(void*, struct zerodds_ZeroDdsDataReader*);
} zerodds_ZeroDdsSubscriberListener;

/**
 * `TopicListener` — Spec §2.2.4.2.4.
 */
typedef struct zerodds_ZeroDdsTopicListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Inconsistent-Topic.
   */
  void (*on_inconsistent_topic)(void*, struct zerodds_ZeroDdsTopic*);
} zerodds_ZeroDdsTopicListener;

/**
 * `DataWriterListener` — Spec §2.2.4.2.5.
 */
typedef struct zerodds_ZeroDdsDataWriterListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Liveliness-Lost.
   */
  void (*on_liveliness_lost)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Offered-Deadline-Missed.
   */
  void (*on_offered_deadline_missed)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Offered-Incompatible-QoS.
   */
  void (*on_offered_incompatible_qos)(void*, struct zerodds_ZeroDdsDataWriter*);
  /**
   * Publication-Matched.
   */
  void (*on_publication_matched)(void*, struct zerodds_ZeroDdsDataWriter*);
} zerodds_ZeroDdsDataWriterListener;

/**
 * `DataReaderListener` — Spec §2.2.4.2.6.
 */
typedef struct zerodds_ZeroDdsDataReaderListener {
  /**
   * Caller-State.
   */
  void *user_data;
  /**
   * Data-Available.
   */
  void (*on_data_available)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Sample-Rejected.
   */
  void (*on_sample_rejected)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Liveliness-Changed.
   */
  void (*on_liveliness_changed)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Requested-Deadline-Missed.
   */
  void (*on_requested_deadline_missed)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Requested-Incompatible-QoS.
   */
  void (*on_requested_incompatible_qos)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Subscription-Matched.
   */
  void (*on_subscription_matched)(void*, struct zerodds_ZeroDdsDataReader*);
  /**
   * Sample-Lost.
   */
  void (*on_sample_lost)(void*, struct zerodds_ZeroDdsDataReader*);
} zerodds_ZeroDdsDataReaderListener;

/**
 * Time point (Spec §2.2.3.5 + IDL §9.3.2). seconds + nanoseconds form
 * (the spec's `zerodds_Time`; cbindgen emits it as `zerodds_ZeroDdsTime`,
 * like every other FFI struct). Used by `zerodds_dp_get_current_time`.
 */
typedef struct zerodds_ZeroDdsTime {
  /**
   * Seconds.
   */
  int32_t sec;
  /**
   * Nanoseconds.
   */
  uint32_t nanosec;
} zerodds_ZeroDdsTime;

/**
 * LivelinessLostStatus (Spec §2.2.4.1).
 */
typedef struct zerodds_ZeroDdsLivelinessLostStatus {
  int32_t total_count;
  int32_t total_count_change;
} zerodds_ZeroDdsLivelinessLostStatus;

/**
 * OfferedDeadlineMissedStatus (Spec §2.2.4.1).
 */
typedef struct zerodds_ZeroDdsOfferedDeadlineMissedStatus {
  int32_t total_count;
  int32_t total_count_change;
  uint64_t last_instance_handle;
} zerodds_ZeroDdsOfferedDeadlineMissedStatus;

/**
 * OfferedIncompatibleQosStatus (Spec §2.2.4.1, without a per-policy list —
 * `last_policy_id` covers the mandatory path).
 */
typedef struct zerodds_ZeroDdsOfferedIncompatibleQosStatus {
  int32_t total_count;
  int32_t total_count_change;
  uint32_t last_policy_id;
} zerodds_ZeroDdsOfferedIncompatibleQosStatus;

/**
 * PublicationMatchedStatus (Spec §2.2.4.1).
 */
typedef struct zerodds_ZeroDdsPublicationMatchedStatus {
  int32_t total_count;
  int32_t total_count_change;
  int32_t current_count;
  int32_t current_count_change;
  uint64_t last_subscription_handle;
} zerodds_ZeroDdsPublicationMatchedStatus;

/**
 * LivelinessChangedStatus (Spec §2.2.4.1).
 */
typedef struct zerodds_ZeroDdsLivelinessChangedStatus {
  /**
   * Total alive count.
   */
  int32_t alive_count;
  /**
   * Total not-alive count.
   */
  int32_t not_alive_count;
  /**
   * Change in alive_count since last read.
   */
  int32_t alive_count_change;
  /**
   * Change in not_alive_count since last read.
   */
  int32_t not_alive_count_change;
  /**
   * Last writer that triggered a change.
   */
  uint64_t last_publication_handle;
} zerodds_ZeroDdsLivelinessChangedStatus;

/**
 * SubscriptionMatchedStatus.
 */
typedef struct zerodds_ZeroDdsSubscriptionMatchedStatus {
  /**
   * Total cumulative count.
   */
  int32_t total_count;
  /**
   * Change since last read.
   */
  int32_t total_count_change;
  /**
   * Currently matched.
   */
  int32_t current_count;
  /**
   * Change in current_count.
   */
  int32_t current_count_change;
  /**
   * Last DataWriter that matched.
   */
  uint64_t last_publication_handle;
} zerodds_ZeroDdsSubscriptionMatchedStatus;

/**
 * RequestedDeadlineMissedStatus.
 */
typedef struct zerodds_ZeroDdsRequestedDeadlineMissedStatus {
  /**
   * Total cumulative count.
   */
  int32_t total_count;
  /**
   * Change since last read.
   */
  int32_t total_count_change;
  /**
   * Last instance handle.
   */
  uint64_t last_instance_handle;
} zerodds_ZeroDdsRequestedDeadlineMissedStatus;

/**
 * RequestedIncompatibleQosStatus.
 */
typedef struct zerodds_ZeroDdsRequestedIncompatibleQosStatus {
  /**
   * Total cumulative count.
   */
  int32_t total_count;
  /**
   * Change since last read.
   */
  int32_t total_count_change;
  /**
   * Last policy id.
   */
  uint32_t last_policy_id;
} zerodds_ZeroDdsRequestedIncompatibleQosStatus;

/**
 * SampleLostStatus.
 */
typedef struct zerodds_ZeroDdsSampleLostStatus {
  /**
   * Total cumulative count.
   */
  int32_t total_count;
  /**
   * Change since last read.
   */
  int32_t total_count_change;
} zerodds_ZeroDdsSampleLostStatus;

/**
 * SampleRejectedStatus.
 */
typedef struct zerodds_ZeroDdsSampleRejectedStatus {
  /**
   * Total cumulative count.
   */
  int32_t total_count;
  /**
   * Change since last read.
   */
  int32_t total_count_change;
  /**
   * Reason kind: 0=NotRejected, 1=ByInstancesLimit, 2=BySamplesLimit,
   * 3=BySamplesPerInstanceLimit.
   */
  uint32_t last_reason;
  /**
   * Last instance handle.
   */
  uint64_t last_instance_handle;
} zerodds_ZeroDdsSampleRejectedStatus;

/**
 * InconsistentTopicStatus (Spec §2.2.4.2.4).
 */
typedef struct zerodds_ZeroDdsInconsistentTopicStatus {
  /**
   * Total count of inconsistent topic detections seen so far.
   */
  int32_t total_count;
  /**
   * Change in total_count since last get-call (Spec read-and-clear).
   */
  int32_t total_count_change;
} zerodds_ZeroDdsInconsistentTopicStatus;

/**
 * TypeSupport function table (vendor spec §2).
 *
 * ABI-stable; fields are versioned via `zerodds_c_api_version()`.
 * Per IDL type the C codegen emits exactly one `static const`
 * instance of this struct.
 *
 * Layout reasons:
 * - 16-byte `type_hash` first (XTypes EquivalenceHash).
 * - `type_name` as a NUL-terminated pointer (no owned String).
 * - `is_keyed` + `extensibility` as `u8` for compact packing.
 * - 6 bytes padding up to the function-pointer-aligned fields.
 * - 5 function pointers in fixed order.
 */
typedef struct zerodds_ZeroDdsTypeSupport {
  /**
   * 16-byte EquivalenceHash (XTypes §7.3.4).
   */
  uint8_t type_hash[16];
  /**
   * NUL-terminated type name (Module::Sub::Struct, ASCII).
   */
  const char *type_name;
  /**
   * 1 = at least one @key member present.
   */
  uint8_t is_keyed;
  /**
   * 0=Final, 1=Appendable, 2=Mutable.
   */
  uint8_t extensibility;
  /**
   * Reserved for future fields. MUST be 0.
   */
  uint8_t _reserved[6];
  /**
   * Encoder pointer (see `ZeroDdsEncodeFn`).
   */
  zerodds_Option_ZeroDdsEncodeFn encode;
  /**
   * Decoder pointer (see `ZeroDdsDecodeFn`).
   */
  zerodds_Option_ZeroDdsDecodeFn decode;
  /**
   * Key-hash pointer (see `ZeroDdsKeyHashFn`); NULL allowed if
   * `is_keyed = 0`.
   */
  zerodds_Option_ZeroDdsKeyHashFn key_hash;
  /**
   * Sample-free pointer (see `ZeroDdsSampleFreeFn`); NULL allowed
   * if the type has no heap fields.
   */
  zerodds_Option_ZeroDdsSampleFreeFn sample_free;
  /**
   * Representation-aware decoder (see `ZeroDdsDecodeReprFn`); Bug R4b.
   *
   * ADDITIVE TAIL FIELD (minor-bump ABI, `zerodds-c-api-1.0` §7): a
   * codegen table built before this field was added simply omits it
   * from its designated-initializer list, so it is zero-filled to
   * NULL — the take path then falls back to the legacy `decode`
   * pointer. New codegen that wants representation-correct alignment
   * for 64-bit members sets this pointer.
   */
  zerodds_Option_ZeroDdsDecodeReprFn decode_repr;
} zerodds_ZeroDdsTypeSupport;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Creates a new ZeroDDS runtime on the given domain ID.
 *
 * # Safety
 * The return value is a heap-allocated pointer; the caller must
 * free it with `zerodds_runtime_destroy`.
 *
 * Returns `NULL` on error.
 */
struct zerodds_ZeroDdsRuntime *zerodds_runtime_create(uint32_t domain_id);

/**
 * Like [`zerodds_runtime_create`] but with the **ROS-2 out-of-the-box profile**
 * ([`RuntimeConfig::ros_defaults`]): the reader announces both XCDR1 and XCDR2
 * data representations, so a ZeroDDS node matches `rmw_cyclonedds`/
 * `rmw_fastrtps` writers that emit XCDR1 for final/simple types
 * (e.g. `std_msgs/String`) without any `ZERODDS_DATA_REPR_OFFER` env tuning.
 * This is what `rmw_zerodds` uses, so ROS-2 interop works config-free.
 *
 * # Safety
 * Same as [`zerodds_runtime_create`].
 */
struct zerodds_ZeroDdsRuntime *zerodds_runtime_create_ros_defaults(uint32_t domain_id);

/**
 * Destroys a runtime. NULL-safe.
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
void zerodds_runtime_destroy(struct zerodds_ZeroDdsRuntime *runtime);

/**
 * Prints phase timing counters to stderr (active only if the
 * runtime code was started with `ZERODDS_PHASE_TIMING=1`).
 *
 * This is called by the bench app code before `runtime_destroy`, because
 * the runtime drop-path threads hold the Arc refcount and the
 * real drop only fires on process exit.
 */
void zerodds_phase_dump(void);

/**
 * Waits until SPDP has discovered at least `min_count` remote
 * participants. Returns 0 (Ok) on success, -4 (Timeout) if the number is
 * not reached within `timeout_ms`.
 *
 * **Optional, not mandatory.** SEDP is reliable + keeps history,
 * so an endpoint registered too early will self-heal after 600-720 ms
 * (empirically llvm-Linux) as soon as SPDP sees the peer
 * and the heartbeat replay runs through. This helper is useful
 * when you want a deterministic test setup or want to avoid a long
 * publish loop.
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
int zerodds_runtime_wait_for_peers(struct zerodds_ZeroDdsRuntime *runtime,
                                   int min_count,
                                   uint64_t timeout_ms);

/**
 * Invokes `callback` once per discovered remote **publication**, passing the
 * raw DDS topic + type name. For ROS-2 graph introspection
 * (`rmw_get_topic_names_and_types`, `rmw_count_publishers`).
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
int zerodds_runtime_for_each_publication(struct zerodds_ZeroDdsRuntime *runtime,
                                         struct zerodds_Option_ZeroDdsTopicCallback callback,
                                         void *user_data);

/**
 * Invokes `callback` once per discovered remote **subscription**. Counterpart
 * to [`zerodds_runtime_for_each_publication`].
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
int zerodds_runtime_for_each_subscription(struct zerodds_ZeroDdsRuntime *runtime,
                                          struct zerodds_Option_ZeroDdsTopicCallback callback,
                                          void *user_data);

/**
 * Writes this runtime's 16-byte participant GUID (12-byte RTPS GUID prefix +
 * 4-byte `ENTITYID_PARTICIPANT` = `00 00 01 c1`) into `out_guid`. ROS 2 uses
 * this as the participant gid on `ros_discovery_info`; the first 12 bytes match
 * every endpoint GUID owned by this participant, so endpoint-info lookups can
 * resolve a node name from an endpoint's GUID prefix.
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL; `out_guid` must
 * point to at least 16 writable bytes.
 */
int zerodds_runtime_participant_guid(struct zerodds_ZeroDdsRuntime *runtime, uint8_t *out_guid);

/**
 * Writes a writer's 16-byte endpoint GUID (participant prefix + entity id) into
 * `out_guid`. The first 12 bytes equal the participant GUID, so ROS 2 can map
 * the endpoint to its owning node.
 *
 * # Safety
 * `writer` must come from `zerodds_writer_create` or be NULL; `out_guid` must
 * point to at least 16 writable bytes.
 */
int zerodds_writer_guid(struct zerodds_ZeroDdsWriter *writer, uint8_t *out_guid);

/**
 * Writes a reader's 16-byte endpoint GUID into `out_guid`. See
 * [`zerodds_writer_guid`].
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create` or be NULL; `out_guid` must
 * point to at least 16 writable bytes.
 */
int zerodds_reader_guid(struct zerodds_ZeroDdsReader *reader, uint8_t *out_guid);

/**
 * Invokes `callback` once per **publication** endpoint on this domain (local
 * user writers + remote SEDP), with full per-endpoint info (GUID + QoS).
 * Backs `rmw_get_publishers_info_by_topic`.
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
int zerodds_runtime_for_each_publication_endpoint(struct zerodds_ZeroDdsRuntime *runtime,
                                                  struct zerodds_Option_ZeroDdsEndpointCallback callback,
                                                  void *user_data);

/**
 * Counterpart to [`zerodds_runtime_for_each_publication_endpoint`] for
 * **subscription** endpoints. Backs `rmw_get_subscriptions_info_by_topic`.
 *
 * # Safety
 * `runtime` must come from `zerodds_runtime_create` or be NULL.
 */
int zerodds_runtime_for_each_subscription_endpoint(struct zerodds_ZeroDdsRuntime *runtime,
                                                   struct zerodds_Option_ZeroDdsEndpointCallback callback,
                                                   void *user_data);

/**
 * Creates a DataWriter on a topic. Topic + type are identified by name
 * (DDS spec §2.2.2).
 *
 * # Safety
 * `runtime` must be valid. `topic_name` and `type_name` must
 * be NUL-terminated UTF-8 strings.
 */
struct zerodds_ZeroDdsWriter *zerodds_writer_create(struct zerodds_ZeroDdsRuntime *runtime,
                                                    const char *topic_name,
                                                    const char *type_name,
                                                    int reliable);

/**
 * Creates a DataWriter with an explicit keyed/no-keyed flag.
 *
 * Cross-vendor interop: if the IDL type has no `@key`, `is_keyed=0`
 * MUST be set. Otherwise ZeroDDS publishes as a
 * WithKey writer (entityKind 0x02) and a remote reader (e.g. Cyclone)
 * rejects the DATA submessage due to a mismatch with its NoKey reader
 * (entityKind 0x04). Spec §9.3.1.2 Table 9.1.
 *
 * # Safety
 * Same as [`zerodds_writer_create`].
 */
struct zerodds_ZeroDdsWriter *zerodds_writer_create_kind(struct zerodds_ZeroDdsRuntime *runtime,
                                                         const char *topic_name,
                                                         const char *type_name,
                                                         int reliable,
                                                         int is_keyed);

/**
 * Writes a sample. `payload` points to already-CDR-encoded bytes.
 *
 * # Safety
 * `writer` and `payload` must be valid, `len` <= buffer size.
 */
int zerodds_writer_write(struct zerodds_ZeroDdsWriter *writer,
                         const uint8_t *payload,
                         uintptr_t len);

/**
 * Sets a writer's type extensibility, so that the
 * encapsulation header of the payload is declared correctly:
 * `0` = FINAL (PLAIN_CDR/PLAIN_CDR2), `1` = APPENDABLE (DELIMITED_CDR2),
 * `2` = MUTABLE (PL_CDR/PL_CDR2). The default without a call is FINAL.
 *
 * Only relevant for XCDR2 wire (offer XCDR2-first) with non-@final
 * types — otherwise the header is `CDR_LE` in both cases. The codegen
 * calls this after `zerodds_writer_create*` with the compile-time
 * extensibility of the type.
 *
 * # Safety
 * `writer` must come from `zerodds_writer_create*` and be valid.
 */
int zerodds_writer_set_wire_extensibility(struct zerodds_ZeroDdsWriter *writer, int extensibility);

/**
 * Waits until at least `min_count` subscriptions have matched or
 * the timeout elapses. `timeout_ms` = 0 -> non-blocking poll.
 *
 * # Safety
 * `writer` must be valid.
 */
int zerodds_writer_wait_for_matched(struct zerodds_ZeroDdsWriter *writer,
                                    int min_count,
                                    uint64_t timeout_ms);

/**
 * Sends a lifecycle marker (Spec §9.6.3.9 PID_STATUS_INFO):
 * `dispose` sets the DISPOSED bit, so that remote readers classify the
 * instance as NotAliveDisposed. The caller must pass the 16-byte
 * key hash of the instance (PLAIN_CDR2-BE encoding with zero
 * padding, or MD5 if > 16 bytes).
 *
 * # Safety
 * `writer` and `key_hash` must be valid; `key_hash` must point to
 * exactly 16 bytes.
 */
int zerodds_writer_dispose(struct zerodds_ZeroDdsWriter *writer, const uint8_t *key_hash);

/**
 * Sends an UNREGISTER marker (Spec §2.2.2.4.2.7). Sets only the
 * UNREGISTERED bit (no autodispose). A caller wanting spec-default
 * behavior (autodispose=true) should instead use
 * `zerodds_writer_unregister_with_dispose`.
 *
 * # Safety
 * Like [`zerodds_writer_dispose`].
 */
int zerodds_writer_unregister(struct zerodds_ZeroDdsWriter *writer, const uint8_t *key_hash);

/**
 * Sends a combined DISPOSE+UNREGISTER marker (Spec §2.2.3.21 with
 * `autodispose_unregistered_instances=true`). The reader sees both
 * NotAliveDisposed and NotAliveNoWriters.
 *
 * # Safety
 * Like [`zerodds_writer_dispose`].
 */
int zerodds_writer_unregister_with_dispose(struct zerodds_ZeroDdsWriter *writer,
                                           const uint8_t *key_hash);

/**
 * Number of remote DataReaders currently matched to this writer (DDS 1.4
 * §2.2.4.2 PublicationMatchedStatus.current_count). Powers
 * `rmw_publisher_count_matched_subscriptions` → `Publisher.get_subscription_count()`
 * in rclpy/rclcpp. Returns `0` on a NULL handle.
 *
 * # Safety
 * `writer` must come from `zerodds_writer_create*` or be NULL.
 */
uintptr_t zerodds_writer_matched_count(struct zerodds_ZeroDdsWriter *writer);

/**
 * Number of remote DataWriters currently matched to this reader (DDS 1.4
 * §2.2.4.2 SubscriptionMatchedStatus.current_count). Powers
 * `rmw_subscription_count_matched_publishers` → `Subscription.get_publisher_count()`.
 * Returns `0` on a NULL handle.
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create*` or be NULL.
 */
uintptr_t zerodds_reader_matched_count(struct zerodds_ZeroDdsReader *reader);

/**
 * Destroys a writer. NULL-safe.
 *
 * # Safety
 * `writer` must come from `zerodds_writer_create` or be NULL.
 */
void zerodds_writer_destroy(struct zerodds_ZeroDdsWriter *writer);

/**
 * Creates a DataReader on a topic.
 *
 * # Safety
 * Like `zerodds_writer_create`.
 */
struct zerodds_ZeroDdsReader *zerodds_reader_create(struct zerodds_ZeroDdsRuntime *runtime,
                                                    const char *topic_name,
                                                    const char *type_name,
                                                    int reliable);

/**
 * Like [`zerodds_reader_create`] but with an explicit keyed/no-keyed
 * flag. Cross-vendor interop: the reader kind must match the writer kind
 * (Spec §9.3.1.2 Table 9.1).
 *
 * # Safety
 * Same as [`zerodds_reader_create`].
 */
struct zerodds_ZeroDdsReader *zerodds_reader_create_kind(struct zerodds_ZeroDdsRuntime *runtime,
                                                         const char *topic_name,
                                                         const char *type_name,
                                                         int reliable,
                                                         int is_keyed);

/**
 * Tries to read a sample.
 * * On success: writes an allocated buffer into `*out_buf`, its
 *   length into `*out_len`. The caller MUST call `zerodds_buffer_free(*out_buf)`.
 * * On no sample: `*out_buf = NULL`, `*out_len = 0`, returns Ok.
 * * On error: a negative status code.
 *
 * `out_repr` (nullable): receives the XCDR version of the sample —
 * `0` = XCDR1, `1` = XCDR2 — from the encapsulation header of the
 * wire sample. The typed consumer needs this to decode the body
 * with the correct alignment rule. NULL = ignore.
 *
 * This little-endian-default form does not surface the wire byte order;
 * a consumer that must decode a big-endian peer uses
 * [`zerodds_reader_take_endian`].
 *
 * # Safety
 * Pointers must be valid. `out_repr` may be NULL.
 */
int zerodds_reader_take(struct zerodds_ZeroDdsReader *reader,
                        uint8_t **out_buf,
                        uintptr_t *out_len,
                        uint8_t *out_repr);

/**
 * Like [`zerodds_reader_take`], plus `out_be` (nullable): receives the wire
 * byte order — `0` = little-endian (the canonical XCDR2 wire), `1` =
 * big-endian — derived from the encapsulation representation identifier
 * (RTPS 2.5 §10.5). A typed FFI consumer dispatches its little-endian vs
 * big-endian decoder on this, so a big-endian peer's sample decodes
 * correctly. NULL = ignore (assume little-endian).
 *
 * # Safety
 * Pointers must be valid. `out_repr` and `out_be` may be NULL.
 */
int zerodds_reader_take_endian(struct zerodds_ZeroDdsReader *reader,
                               uint8_t **out_buf,
                               uintptr_t *out_len,
                               uint8_t *out_repr,
                               uint8_t *out_be);

/**
 * Fixed-buffer `take` convenience: copies one sample's payload into a
 * caller-supplied buffer and returns the byte count — no heap
 * allocation, no `zerodds_buffer_free`.
 *
 * This is the ergonomic shape for plain-C / FFI consumers that prefer a
 * stack buffer + return-length idiom (Go/Zig/Ada/MATLAB cgo bindings,
 * the C quickstart) over the allocate-and-out-param
 * [`zerodds_reader_take`].
 *
 * Returns:
 * * `> 0`: number of payload bytes written into `buf` (one sample).
 * * `0`: no sample available right now.
 * * `< 0`: a negative status code (bad handle, or — if the sample is
 *   larger than `cap` — `ZeroDdsStatus::OutOfResources`, in which case
 *   the sample is consumed; use [`zerodds_reader_take`] for unbounded
 *   samples).
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create*` or be NULL. `buf`
 * must point to at least `cap` writable bytes (or be NULL iff
 * `cap == 0`).
 */
intptr_t zerodds_reader_take_into(struct zerodds_ZeroDdsReader *reader,
                                  uint8_t *buf,
                                  uintptr_t cap);

/**
 * Waits until at least `min_count` publications have matched.
 *
 * # Safety
 * `reader` must be valid.
 */
int zerodds_reader_wait_for_matched(struct zerodds_ZeroDdsReader *reader,
                                    int min_count,
                                    uint64_t timeout_ms);

/**
 * Returns the number of samples dropped because of an unknown writer (no
 * matching writer_proxy). Diagnosis for interop bugs:
 * if the writer_proxy was not created from SEDP PublicationData
 * (e.g. because of an entity-id mismatch between the SEDP pub and the DATA submessage),
 * this counter increments for every incoming DATA sample.
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create*` or be NULL.
 */
uint64_t zerodds_reader_unknown_src_count(struct zerodds_ZeroDdsReader *reader);

/**
 * A2 — arm TIME_BASED_FILTER (DDS 1.4 §2.2.3.12) on a reader: it then delivers
 * at most one sample per instance per `min_separation_nanos`; closer-spaced
 * samples are dropped before `zerodds_reader_take`/the data callback sees them.
 * `0` disables the filter. ROS 2 exposes no TIME_BASED_FILTER field in
 * `rmw_qos_profile_t`, so `rmw_zerodds` calls this from the
 * `ZERODDS_TIME_BASED_FILTER` env to rate-limit a subscription. Returns `0` on
 * success, `-1` on a NULL/unknown reader.
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create*` or be NULL.
 */
int zerodds_reader_set_time_based_filter_ns(struct zerodds_ZeroDdsReader *reader,
                                            uint64_t min_separation_nanos);

/**
 * Destroys a reader handle and releases its resources.
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create*` or be NULL and
 * must not be used afterwards.
 */
void zerodds_reader_destroy(struct zerodds_ZeroDdsReader *reader);

/**
 * Sets a data-available callback (or clears it with NULL).
 * See the `ZeroDdsDataCallback` docs for the full contract.
 *
 * # Safety
 * `reader` must come from `zerodds_reader_create`.
 */
int zerodds_reader_set_data_callback(struct zerodds_ZeroDdsReader *reader,
                                     zerodds_Option_ZeroDdsDataCallback callback,
                                     void *user_data);

/**
 * Frees a buffer that a previous `zerodds_reader_take`
 * allocated. NULL-safe.
 *
 * # Safety
 * `buf` must come from `zerodds_reader_take` or be NULL.
 * `len` must be exactly the value belonging to that buffer.
 */
void zerodds_buffer_free(uint8_t *buf, uintptr_t len);

/**
 * Loan-based `take`: returns a live pointer into an
 * internal `Arc<[u8]>` without a copy.
 *
 * On success:
 * * `*out_buf` points to the payload (read-only),
 * * `*out_len` is the length,
 * * `*out_loan_handle` is an opaque pointer that must later be passed to
 *   [`zerodds_reader_return_loan`].
 *
 * On no sample: `*out_buf = NULL`, `*out_len = 0`,
 * `*out_loan_handle = NULL`, returns Ok.
 *
 * # Safety
 * All pointers must be valid. The returned `*out_buf` is
 * valid only while `*out_loan_handle` lives; after
 * `zerodds_reader_return_loan` the read lifetime has ended.
 */
int zerodds_reader_loan(struct zerodds_ZeroDdsReader *reader,
                        const uint8_t **out_buf,
                        uintptr_t *out_len,
                        void **out_loan_handle);

/**
 * Returns a loan that a previous [`zerodds_reader_loan`]
 * created. After this call the associated `*out_buf`
 * pointer is invalid (the Arc refcount may go to 0 and the bytes
 * are freed).
 *
 * NULL-safe — a `loan_handle = NULL` is a no-op.
 *
 * # Safety
 * `loan_handle` must come from [`zerodds_reader_loan`] or be NULL.
 * Do not return it twice.
 */
void zerodds_reader_return_loan(void *loan_handle);

/**
 * Reserves an output buffer at the writer for zero-copy publish.
 * The caller writes the sample into the returned pointer and
 * then commits it via [`zerodds_writer_commit_loan`].
 *
 * Returns 0 (Ok) on success + fills `*out_ptr` and `*out_len`.
 * On today's malloc-backed path `*out_len = len`; for
 * SHM-backed loans `*out_len > len` is possible (slot boundary).
 *
 * # Safety
 * `writer` valid; `out_ptr`/`out_len` non-null.
 */
int zerodds_writer_loan_message(struct zerodds_ZeroDdsWriter *writer,
                                uintptr_t len,
                                uint8_t **out_ptr,
                                uintptr_t *out_len);

/**
 * Commit path: writes the loaned buffer as a sample and frees
 * it. The caller must not read the pointer afterwards.
 *
 * # Safety
 * `writer` from `zerodds_writer_create`; `ptr` from
 * `zerodds_writer_loan_message`; `len` the same value as returned in
 * `out_len`.
 */
int zerodds_writer_commit_loan(struct zerodds_ZeroDdsWriter *writer, uint8_t *ptr, uintptr_t len);

/**
 * Discards a loan without publishing it. The buffer is freed.
 *
 * # Safety
 * Like `zerodds_writer_commit_loan`.
 */
int zerodds_writer_discard_loan(struct zerodds_ZeroDdsWriter *_writer, uint8_t *ptr, uintptr_t len);

/**
 * Sets the delivery mode of a runtime-path DataWriter (the handle the ROS-2
 * RMW bridge uses). `0`=Portable (default, interop-safe), `1`=RawSameHost
 * (same-host, no wire). `2`=Iceoryx is not yet wired → `Unsupported`. Other
 * values → `BadParameter`.
 *
 * # Safety
 * `writer` from `zerodds_writer_create`.
 */
int zerodds_writer_set_delivery_mode(struct zerodds_ZeroDdsWriter *writer, int mode);

/**
 * Enables zero-copy SHM loan on a runtime-path DataWriter (the handle the
 * ROS-2 RMW bridge uses). Creates a POSIX shared-memory segment of
 * `slot_count` slots × `slot_capacity` bytes at the flink path `name`. After
 * this, `zerodds_writer_loan_message` returns a pointer into a SHM slot and
 * `zerodds_writer_commit_loan` finalizes it in place — no staging copy.
 *
 * The loan state is keyed by `(runtime, entity-id)`, so a writer reached
 * through the DCPS FFI (`zerodds_dw_*`) and this runtime FFI shares the same
 * backend. Without this feature/call the loan path stays on the heap box.
 *
 * # Safety
 * `writer` from `zerodds_writer_create`; `name` is a NUL-terminated C string.
 */
int zerodds_writer_enable_shm_loan(struct zerodds_ZeroDdsWriter *writer,
                                   const char *name,
                                   uintptr_t slot_count,
                                   uintptr_t slot_capacity);

/**
 * Maps the writer's SHM segment at flink path `name` on a runtime-path
 * DataReader for zero-copy reads. `reader_index` is the reader's bit (0..32)
 * in the slot reader-mask.
 *
 * # Safety
 * `reader` from `zerodds_reader_create`; `name` is a NUL-terminated C string.
 */
int zerodds_reader_enable_shm(struct zerodds_ZeroDdsReader *reader,
                              const char *name,
                              uint8_t reader_index);

/**
 * Zero-copy take on a runtime-path DataReader: returns a read-only pointer
 * into the writer's SHM slot, its length and the slot index (for
 * `zerodds_reader_release_shm`). Returns `NoData` when nothing is pending.
 * The pointer stays valid until `zerodds_reader_release_shm`.
 *
 * # Safety
 * `reader`/`out_ptr`/`out_len`/`out_slot` valid.
 */
int zerodds_reader_take_shm(struct zerodds_ZeroDdsReader *reader,
                            const uint8_t **out_ptr,
                            uintptr_t *out_len,
                            uint32_t *out_slot);

/**
 * Releases a slot previously returned by `zerodds_reader_take_shm`.
 *
 * # Safety
 * `reader` valid; `slot_index` from a prior `zerodds_reader_take_shm`.
 */
int zerodds_reader_release_shm(struct zerodds_ZeroDdsReader *reader, uint32_t slot_index);

/**
 * Blocks until this reader's raw source (RawSameHost SHM segment or Iceoryx
 * service) signals a new sample, or `timeout_ms` elapses — event-driven (SHM
 * change-generation futex / iceoryx2 listener), no busy-poll. Lets a consumer
 * (e.g. the ROS-2 RMW `rmw_wait` doorbell) park on raw-data arrival instead of
 * polling. A spurious wake is harmless — re-check with `zerodds_reader_take_shm`.
 * Returns `Ok` when woken or timed out, `PreconditionNotMet` if no raw source.
 *
 * # Safety
 * `reader` from `zerodds_reader_create` or NULL.
 */
int zerodds_reader_raw_wait(struct zerodds_ZeroDdsReader *reader, uint64_t timeout_ms);

/**
 * Enables `Iceoryx` delivery on a runtime-path DataWriter (feature
 * `delivery-iceoryx`): publishes its samples over the iceoryx2 service
 * `service_name` (max `max_len` bytes/sample). The loan API then routes through
 * iceoryx2; commit does not publish over RTPS.
 *
 * # Safety
 * `writer` from `zerodds_writer_create`; `service_name` is a NUL-terminated C
 * string.
 */
int zerodds_writer_enable_iceoryx(struct zerodds_ZeroDdsWriter *writer,
                                  const char *service_name,
                                  uintptr_t max_len);

/**
 * Enables `Iceoryx` delivery on a runtime-path DataReader: receives from the
 * iceoryx2 service `service_name` via `zerodds_reader_take_shm` /
 * `zerodds_reader_release_shm`.
 *
 * # Safety
 * `reader` from `zerodds_reader_create`; `service_name` is a NUL-terminated C
 * string.
 */
int zerodds_reader_enable_iceoryx(struct zerodds_ZeroDdsReader *reader, const char *service_name);

/**
 * Version string of the C-FFI. Static, not to be freed.
 */
const char *zerodds_version(void);

/**
 * Returns the InstanceHandles of all discovered topics.
 *
 * # Safety
 * `p`, `out`, `out_count` valid.
 */
int zerodds_dp_get_discovered_topics(struct zerodds_ZeroDdsDomainParticipant *p,
                                     uint64_t *out,
                                     uintptr_t *out_count,
                                     uintptr_t cap);

/**
 * Returns the `ParticipantBuiltinTopicData` for an InstanceHandle.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_discovered_participant_data(struct zerodds_ZeroDdsDomainParticipant *p,
                                               uint64_t handle,
                                               struct zerodds_ZeroDdsParticipantBuiltinTopicData *out);

/**
 * Returns a previously allocated UserData slice.
 *
 * # Safety
 * `p[0..len]` must come from `dp_get_discovered_participant_data`.
 */
void zerodds_builtin_userdata_free(const uint8_t *p, uintptr_t len);

/**
 * Returns the `TopicBuiltinTopicData` for an InstanceHandle.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_discovered_topic_data(struct zerodds_ZeroDdsDomainParticipant *p,
                                         uint64_t handle,
                                         struct zerodds_ZeroDdsTopicBuiltinTopicData *out);

/**
 * Number of discovered publications (Spec §2.2.2.2.1.13).
 *
 * # Safety
 * `p` valid.
 */
uintptr_t zerodds_dp_discovered_publications_count(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Number of discovered subscriptions.
 *
 * # Safety
 * `p` valid.
 */
uintptr_t zerodds_dp_discovered_subscriptions_count(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Reads the current trigger status of a condition (Spec §2.2.2.1.2.1.1).
 *
 * # Safety
 * `c` valid or NULL.
 */
bool zerodds_condition_get_trigger_value(const void *c);

/**
 * Creates a GuardCondition.
 */
zerodds_ZeroDdsGuardCondition *zerodds_guardcondition_create(void);

/**
 * Deletes a GuardCondition.
 *
 * # Safety
 * `g` must come from `zerodds_guardcondition_create`.
 */
void zerodds_guardcondition_destroy(zerodds_ZeroDdsGuardCondition *g);

/**
 * Sets the trigger value.
 *
 * # Safety
 * `g` valid.
 */
int zerodds_guardcondition_set_trigger_value(zerodds_ZeroDdsGuardCondition *g, bool v);

/**
 * Creates a StatusCondition for an entity. RC1: allows any
 * `*mut c_void` as the entity slot — the match logic reads the status per
 * entity type via the listener FFI (follow-up WP).
 *
 * # Safety
 * `entity` valid or NULL.
 */
zerodds_ZeroDdsStatusCondition *zerodds_entity_get_statuscondition(void *entity);

/**
 * Enables the status bits set in `mask`.
 *
 * # Safety
 * `c` valid.
 */
int zerodds_statuscondition_set_enabled_statuses(zerodds_ZeroDdsStatusCondition *c, uint32_t mask);

/**
 * Reads the enabled status bits.
 *
 * # Safety
 * `c` valid.
 */
uint32_t zerodds_statuscondition_get_enabled_statuses(zerodds_ZeroDdsStatusCondition *c);

/**
 * Deletes a StatusCondition.
 *
 * # Safety
 * `c` valid.
 */
void zerodds_statuscondition_destroy(zerodds_ZeroDdsStatusCondition *c);

/**
 * Creates a ReadCondition (Spec §2.2.2.5.2.4).
 *
 * # Safety
 * `dr` valid.
 */
zerodds_ZeroDdsReadCondition *zerodds_dr_create_readcondition(struct zerodds_ZeroDdsDataReader *dr,
                                                              uint32_t sample_states,
                                                              uint32_t view_states,
                                                              uint32_t instance_states);

/**
 * Creates a QueryCondition (Spec §2.2.2.5.2.5).
 *
 * # Safety
 * `dr`, `expr` valid; `params[0..param_count]` valid.
 */
zerodds_ZeroDdsQueryCondition *zerodds_dr_create_querycondition(struct zerodds_ZeroDdsDataReader *dr,
                                                                uint32_t sample_states,
                                                                uint32_t view_states,
                                                                uint32_t instance_states,
                                                                const char *expr,
                                                                const char *const *params,
                                                                uintptr_t param_count);

/**
 * Deletes a ReadCondition or QueryCondition.
 *
 * # Safety
 * `c` valid; must come from `dr_create_readcondition` or
 * `dr_create_querycondition`.
 */
int zerodds_dr_delete_readcondition(struct zerodds_ZeroDdsDataReader *_dr, void *c);

/**
 * Creates a WaitSet.
 */
struct zerodds_ZeroDdsWaitSet *zerodds_waitset_create(void);

/**
 * Deletes a WaitSet.
 *
 * # Safety
 * `w` valid.
 */
void zerodds_waitset_destroy(struct zerodds_ZeroDdsWaitSet *w);

/**
 * Attach Condition.
 *
 * # Safety
 * `w`, `cond` valid.
 */
int zerodds_waitset_attach_condition(struct zerodds_ZeroDdsWaitSet *w, void *cond);

/**
 * Detach Condition.
 *
 * # Safety
 * `w`, `cond` valid.
 */
int zerodds_waitset_detach_condition(struct zerodds_ZeroDdsWaitSet *w, void *cond);

/**
 * Waits until at least one condition triggers or a timeout.
 * Writes active conditions into `out_active[0..*out_count]`.
 *
 * # Safety
 * `w`, `out_active`, `out_count`, `timeout` valid.
 */
int zerodds_waitset_wait(struct zerodds_ZeroDdsWaitSet *w,
                         void **out_active,
                         uintptr_t cap,
                         uintptr_t *out_count,
                         int32_t timeout_sec,
                         uint32_t timeout_nanosec);

/**
 * Returns all attached conditions.
 *
 * # Safety
 * `w`, `out`, `out_count` valid.
 */
int zerodds_waitset_get_conditions(struct zerodds_ZeroDdsWaitSet *w,
                                   void **out,
                                   uintptr_t cap,
                                   uintptr_t *out_count);

/**
 * `lookup_topicdescription(name)` — Spec §2.2.2.2.1.13.
 * Returns the first topic with the same name, or NULL.
 *
 * # Safety
 * `p`, `name` valid.
 */
struct zerodds_ZeroDdsTopic *zerodds_dp_lookup_topicdescription(struct zerodds_ZeroDdsDomainParticipant *p,
                                                                const char *name);

/**
 * `get_builtin_subscriber()` — Spec §2.2.2.2.1.7.
 * Returns a pointer to a wrapper around the DCPS BuiltinSubscriber.
 * The caller must call `zerodds_builtin_subscriber_destroy`.
 *
 * # Safety
 * `p` valid.
 */
struct zerodds_ZeroDdsBuiltinSubscriber *zerodds_dp_get_builtin_subscriber(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Deletes a BuiltinSubscriber wrapper.
 *
 * # Safety
 * `bs` valid or NULL.
 */
void zerodds_builtin_subscriber_destroy(struct zerodds_ZeroDdsBuiltinSubscriber *bs);

/**
 * Sets the DomainParticipant QoS (Spec §2.2.2.2.1.3).
 *
 * # Safety
 * `p` valid; `qos` darf NULL sein (Reset auf Default).
 */
int zerodds_dp_set_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                       const struct zerodds_ZeroDdsDomainParticipantQos *qos);

/**
 * Reads the DomainParticipant QoS into `out` (Spec §2.2.2.2.1.4).
 * `out.user_data.value` must be initialized by the caller with a sufficient
 * buffer. On a too-small buffer the required
 * size is written back into `out.user_data.value_len` + `OutOfResources`.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                       struct zerodds_ZeroDdsDomainParticipantQos *out);

/**
 * Set-Default-Topic-QoS.
 *
 * # Safety
 * `p` valid; `qos` darf NULL sein.
 */
int zerodds_dp_set_default_topic_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                     const struct zerodds_ZeroDdsTopicQos *qos);

/**
 * Get-Default-Topic-QoS-Snapshot.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_default_topic_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                     struct zerodds_ZeroDdsTopicQos *out);

/**
 * Set-Default-Publisher-QoS.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_set_default_publisher_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                         const struct zerodds_ZeroDdsPublisherQos *qos);

/**
 * Get-Default-Publisher-QoS.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_default_publisher_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                         struct zerodds_ZeroDdsPublisherQos *out);

/**
 * Set-Default-Subscriber-QoS.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_set_default_subscriber_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                          const zerodds_ZeroDdsSubscriberQos *qos);

/**
 * Get-Default-Subscriber-QoS.
 *
 * # Safety
 * `p`, `out` valid.
 */
int zerodds_dp_get_default_subscriber_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                          zerodds_ZeroDdsSubscriberQos *out);

/**
 * Publisher set/get QoS.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_set_qos(struct zerodds_ZeroDdsPublisher *pub_,
                        const struct zerodds_ZeroDdsPublisherQos *qos);

/**
 * Publisher get_qos.
 *
 * # Safety
 * `pub_`, `out` valid.
 */
int zerodds_pub_get_qos(struct zerodds_ZeroDdsPublisher *pub_,
                        struct zerodds_ZeroDdsPublisherQos *out);

/**
 * Pub set_default_datawriter_qos.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_set_default_datawriter_qos(struct zerodds_ZeroDdsPublisher *pub_,
                                           const struct zerodds_ZeroDdsDataWriterQos *qos);

/**
 * Pub get_default_datawriter_qos.
 *
 * # Safety
 * `pub_`, `out` valid.
 */
int zerodds_pub_get_default_datawriter_qos(struct zerodds_ZeroDdsPublisher *pub_,
                                           struct zerodds_ZeroDdsDataWriterQos *out);

/**
 * Pub copy_from_topic_qos: copies the policies from TopicQos into
 * the DataWriterQos `history`/`durability`/`reliability`/etc. in place.
 *
 * # Safety
 * Both pointers valid.
 */
int zerodds_pub_copy_from_topic_qos(struct zerodds_ZeroDdsPublisher *_pub,
                                    struct zerodds_ZeroDdsDataWriterQos *dwqos_inout,
                                    const struct zerodds_ZeroDdsTopicQos *tqos);

/**
 * Sub set/get QoS.
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_set_qos(struct zerodds_ZeroDdsSubscriber *sub,
                        const zerodds_ZeroDdsSubscriberQos *qos);

/**
 * Sub get_qos.
 *
 * # Safety
 * `sub`, `out` valid.
 */
int zerodds_sub_get_qos(struct zerodds_ZeroDdsSubscriber *sub, zerodds_ZeroDdsSubscriberQos *out);

/**
 * Sub set_default_datareader_qos.
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_set_default_datareader_qos(struct zerodds_ZeroDdsSubscriber *sub,
                                           const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * Sub get_default_datareader_qos.
 *
 * # Safety
 * `sub`, `out` valid.
 */
int zerodds_sub_get_default_datareader_qos(struct zerodds_ZeroDdsSubscriber *sub,
                                           struct zerodds_ZeroDdsDataReaderQos *out);

/**
 * Sub copy_from_topic_qos.
 *
 * # Safety
 * Both pointers valid.
 */
int zerodds_sub_copy_from_topic_qos(struct zerodds_ZeroDdsSubscriber *_sub,
                                    struct zerodds_ZeroDdsDataReaderQos *drqos_inout,
                                    const struct zerodds_ZeroDdsTopicQos *tqos);

/**
 * DataWriter set_qos.
 *
 * # Safety
 * `dw` valid.
 */
int zerodds_dw_set_qos(struct zerodds_ZeroDdsDataWriter *dw,
                       const struct zerodds_ZeroDdsDataWriterQos *qos);

/**
 * DataWriter get_qos.
 *
 * # Safety
 * `dw`, `out` valid.
 */
int zerodds_dw_get_qos(struct zerodds_ZeroDdsDataWriter *dw,
                       struct zerodds_ZeroDdsDataWriterQos *out);

/**
 * DataReader set_qos.
 *
 * # Safety
 * `dr` valid.
 */
int zerodds_dr_set_qos(struct zerodds_ZeroDdsDataReader *dr,
                       const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * DataReader get_qos.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_get_qos(struct zerodds_ZeroDdsDataReader *dr,
                       struct zerodds_ZeroDdsDataReaderQos *out);

/**
 * `register_instance` — vendor variant: the caller provides a 16-byte key hash
 * instead of a generic `T instance_data`. The wire path knows only bytes.
 *
 * # Safety
 * `dw` valid; `key`+`out_handle` valid.
 */
int zerodds_dw_register_instance(struct zerodds_ZeroDdsDataWriter *dw,
                                 const uint8_t *key,
                                 uintptr_t key_len,
                                 uint64_t *out_handle);

/**
 * `register_instance_w_timestamp`. RC1: source timestamp ignored
 * (same path as register_instance, documented in the vendor spec).
 *
 * # Safety
 * Wie `register_instance`.
 */
int zerodds_dw_register_instance_w_timestamp(struct zerodds_ZeroDdsDataWriter *dw,
                                             const uint8_t *key,
                                             uintptr_t key_len,
                                             int32_t _ts_sec,
                                             uint32_t _ts_nanosec,
                                             uint64_t *out_handle);

/**
 * `unregister_instance` — emits the UNREGISTERED lifecycle.
 *
 * # Safety
 * `dw` valid; `handle` must come from `register_instance`.
 */
int zerodds_dw_unregister_instance(struct zerodds_ZeroDdsDataWriter *dw, uint64_t handle);

/**
 * `unregister_instance_w_timestamp`.
 *
 * # Safety
 * Wie `unregister_instance`.
 */
int zerodds_dw_unregister_instance_w_timestamp(struct zerodds_ZeroDdsDataWriter *dw,
                                               uint64_t handle,
                                               int32_t _ts_sec,
                                               uint32_t _ts_nanosec);

/**
 * `lookup_instance` — vendor variant: returns a deterministic
 * handle from the first 8 key-hash bytes.
 *
 * # Safety
 * `key[0..16]` valid.
 */
int zerodds_dw_lookup_instance(struct zerodds_ZeroDdsDataWriter *_dw,
                               const uint8_t *key,
                               uintptr_t key_len,
                               uint64_t *out_handle);

/**
 * `get_key_value(handle)` — in the C-FFI only a vendor variant: copies
 * 8 bytes of the handle into `out_buf[0..8]`. The full spec round-trip
 * (T-encoded key) is the codegen path.
 *
 * # Safety
 * `dw` valid; `out_buf[0..*inout_len]` valid.
 */
int zerodds_dw_get_key_value(struct zerodds_ZeroDdsDataWriter *_dw,
                             uint64_t handle,
                             uint8_t *out_buf,
                             uintptr_t *inout_len);

/**
 * `dispose_w_timestamp`.
 *
 * # Safety
 * Wie `dispose`.
 */
int zerodds_dw_dispose_w_timestamp(struct zerodds_ZeroDdsDataWriter *dw,
                                   const uint8_t *key_hash,
                                   uint64_t handle,
                                   int32_t _ts_sec,
                                   uint32_t _ts_nanosec);

/**
 * `get_matched_subscriptions` — list of the `InstanceHandle`s of all
 * matched remote readers (Spec §2.2.2.4.2.x).
 *
 * # Safety
 * `dw` valid; `out_handles[0..cap]` writeable; `out_count` valid.
 */
int zerodds_dw_get_matched_subscriptions(struct zerodds_ZeroDdsDataWriter *dw,
                                         uint64_t *out_handles,
                                         uintptr_t *out_count,
                                         uintptr_t cap);

/**
 * `get_matched_subscription_data(handle)` — Spec §2.2.2.4.2.x.
 * Returns the `SubscriptionBuiltinTopicData` for a matched
 * reader, obtained from the BuiltinSubscriber SEDP cache.
 *
 * # Safety
 * `dw` and `out` valid.
 */
int zerodds_dw_get_matched_subscription_data(struct zerodds_ZeroDdsDataWriter *dw,
                                             uint64_t handle,
                                             struct zerodds_ZeroDdsSubscriptionBuiltinTopicData *out);

/**
 * `loan_message` — zero-copy loan via a heap box (vendor variant).
 * Allocates a Box<[u8]>, leaks the pointer; the caller writes into
 * the buffer and calls `commit_loan` (sends via write_user_sample)
 * or `discard_loan` (frees the buffer without sending).
 *
 * **Vendor decision (Spec §2.2.2.4.2 loan API + vendor spec
 * `zerodds-flatdata-1.0.md` §4):** real Iceoryx SHM zero-copy
 * requires a separate `zerodds-flatdata` Iceoryx backend wireup;
 * the heap-loan variant exposed here fulfills the DDS spec
 * contract (the caller writes into the buffer, then commit/discard)
 * without the SHM optimization. The real SHM loan is transparent via the
 * `zerodds-flatdata` Iceoryx backend when it is active.
 *
 * # Safety
 * Alle Pointers valid; `len > 0`.
 */
int zerodds_dw_loan_message(struct zerodds_ZeroDdsDataWriter *dw,
                            uintptr_t len,
                            uint8_t **out_ptr,
                            uintptr_t *out_len);

/**
 * `commit_loan` — writes the loan buffer as a sample and frees the
 * buffer.
 *
 * # Safety
 * `dw`, `ptr` valid; `(ptr, len)` from `loan_message`.
 */
int zerodds_dw_commit_loan(struct zerodds_ZeroDdsDataWriter *dw, uint8_t *ptr, uintptr_t len);

/**
 * `discard_loan` — frees the loan buffer without sending.
 *
 * # Safety
 * `dw`, `ptr` valid; `(ptr, len)` from `loan_message`.
 */
int zerodds_dw_discard_loan(struct zerodds_ZeroDdsDataWriter *_dw, uint8_t *ptr, uintptr_t len);

/**
 * `read_instance(handle)` — Spec §2.2.2.5.3.5: returns only samples
 * of this instance.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_read_instance(struct zerodds_ZeroDdsDataReader *dr,
                             uint64_t handle,
                             struct zerodds_ZeroDdsSampleArray *out,
                             uintptr_t max,
                             uint32_t s,
                             uint32_t v,
                             uint32_t i);

/**
 * `take_instance(handle)`.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_take_instance(struct zerodds_ZeroDdsDataReader *dr,
                             uint64_t handle,
                             struct zerodds_ZeroDdsSampleArray *out,
                             uintptr_t max,
                             uint32_t s,
                             uint32_t v,
                             uint32_t i);

/**
 * `read_next_instance(prev_handle)` — Spec §2.2.2.5.3.7: returns
 * samples of the next instance > prev_handle.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_read_next_instance(struct zerodds_ZeroDdsDataReader *dr,
                                  uint64_t prev_handle,
                                  struct zerodds_ZeroDdsSampleArray *out,
                                  uintptr_t max,
                                  uint32_t s,
                                  uint32_t v,
                                  uint32_t i);

/**
 * `take_next_instance(prev_handle)`.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_take_next_instance(struct zerodds_ZeroDdsDataReader *dr,
                                  uint64_t prev_handle,
                                  struct zerodds_ZeroDdsSampleArray *out,
                                  uintptr_t max,
                                  uint32_t s,
                                  uint32_t v,
                                  uint32_t i);

/**
 * `read_w_condition` — Spec §2.2.2.5.3.4: returns only samples that
 * match the condition state mask (ReadCondition.sample_states/
 * view_states/instance_states).
 *
 * # Safety
 * `dr`, `out` valid; `cond` is a ReadCondition or QueryCondition.
 */
int zerodds_dr_read_w_condition(struct zerodds_ZeroDdsDataReader *dr,
                                struct zerodds_ZeroDdsSampleArray *out,
                                uintptr_t max,
                                void *cond);

/**
 * `take_w_condition`.
 *
 * # Safety
 * Wie `read_w_condition`.
 */
int zerodds_dr_take_w_condition(struct zerodds_ZeroDdsDataReader *dr,
                                struct zerodds_ZeroDdsSampleArray *out,
                                uintptr_t max,
                                void *cond);

/**
 * `lookup_instance` (Reader).
 *
 * # Safety
 * `key[0..16]` valid; `out_handle` valid.
 */
int zerodds_dr_lookup_instance(struct zerodds_ZeroDdsDataReader *_dr,
                               const uint8_t *key,
                               uintptr_t key_len,
                               uint64_t *out_handle);

/**
 * `get_key_value` (Reader) — analog zu Writer.
 *
 * # Safety
 * `out_buf[0..*inout_len]` valid.
 */
int zerodds_dr_get_key_value(struct zerodds_ZeroDdsDataReader *_dr,
                             uint64_t handle,
                             uint8_t *out_buf,
                             uintptr_t *inout_len);

/**
 * `wait_for_historical_data(timeout)` — RC1: Volatile default → Ok without wait.
 *
 * # Safety
 * `dr` valid.
 */
int zerodds_dr_wait_for_historical_data(struct zerodds_ZeroDdsDataReader *dr,
                                        int32_t _timeout_sec,
                                        uint32_t _timeout_nanosec);

/**
 * `get_matched_publications` — list of the `InstanceHandle`s of all
 * matched remote writers (Spec §2.2.2.5.x).
 *
 * # Safety
 * `dr` valid; `out_handles[0..cap]` writeable; `out_count` valid.
 */
int zerodds_dr_get_matched_publications(struct zerodds_ZeroDdsDataReader *dr,
                                        uint64_t *out_handles,
                                        uintptr_t *out_count,
                                        uintptr_t cap);

/**
 * `get_matched_publication_data(handle)` — Spec §2.2.2.5.x.
 * Returns `PublicationBuiltinTopicData` from the BuiltinSubscriber cache.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_get_matched_publication_data(struct zerodds_ZeroDdsDataReader *dr,
                                            uint64_t handle,
                                            struct zerodds_ZeroDdsPublicationBuiltinTopicData *out);

/**
 * Get singleton: returns the global factory pointer. Never NULL.
 * The caller must **not** free the pointer.
 */
const struct zerodds_ZeroDdsDomainParticipantFactory *zerodds_dpf_get_instance(void);

/**
 * Creates a new DomainParticipant.
 *
 * # Safety
 * `f` must come from `zerodds_dpf_get_instance` or be NULL.
 * `qos` may be NULL (default).
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_dpf_create_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                                                        uint32_t domain_id,
                                                                        const struct zerodds_ZeroDdsDomainParticipantQos *qos);

/**
 * Deletes a DomainParticipant.
 *
 * # Safety
 * `f` and `p` must be valid handles. `p` must not have any
 * contained entities (topics, publishers, subscribers) at the time
 * of the call — the caller must call `delete_contained_entities`.
 */
int zerodds_dpf_delete_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                   struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Finds an active participant for the given domain ID. Returns
 * NULL if none exists.
 *
 * # Safety
 * `f` must be valid.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_dpf_lookup_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                                                        uint32_t domain_id);

/**
 * Get default participant QoS via a pass-through pointer to an
 * `Arc<...>`-internal snapshot. The caller may only read the pointer,
 * not free it (static lifetime of the singleton factory).
 *
 * In this RC1 surface form the default QoS is returned as an opaque
 * `Arc<DomainParticipantQos>` — the full field getter/setter
 * comes with the `qos.rs` structs in a follow-up pass.
 *
 * # Safety
 * `f` valid.
 */
int zerodds_dpf_set_default_participant_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                            const struct zerodds_ZeroDdsDomainParticipantQos *qos);

/**
 * Returns a copy of the current default participant QoS in `out`.
 * As long as the `zerodds_DomainParticipantQos` struct is not defined in the
 * `qos.rs` layer, `out` is an opaque `void*`.
 *
 * # Safety
 * `f` valid; `out` may be NULL (no-op).
 */
int zerodds_dpf_get_default_participant_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                            struct zerodds_ZeroDdsDomainParticipantQos *out);

/**
 * Sets the factory's own QoS (Spec §2.2.2.2.2.6).
 *
 * # Safety
 * `f` valid; `qos` may be NULL (reset).
 */
int zerodds_dpf_set_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                        const struct zerodds_ZeroDdsDomainParticipantFactoryQos *qos);

/**
 * Reads the factory's own QoS.
 *
 * # Safety
 * `f`, `out` valid.
 */
int zerodds_dpf_get_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                        struct zerodds_ZeroDdsDomainParticipantFactoryQos *out);

/**
 * `dp_set_listener`. NULL = clear.
 *
 * # Safety
 * `p` valide; `l` darf NULL sein.
 */
int zerodds_dp_set_listener(struct zerodds_ZeroDdsDomainParticipant *p,
                            const struct zerodds_ZeroDdsDomainParticipantListener *l,
                            uint32_t status_mask);

/**
 * `pub_set_listener`.
 *
 * # Safety
 * `pub_` valide.
 */
int zerodds_pub_set_listener(struct zerodds_ZeroDdsPublisher *pub_,
                             const struct zerodds_ZeroDdsPublisherListener *l,
                             uint32_t status_mask);

/**
 * `sub_set_listener`.
 *
 * # Safety
 * `sub` valide.
 */
int zerodds_sub_set_listener(struct zerodds_ZeroDdsSubscriber *sub,
                             const struct zerodds_ZeroDdsSubscriberListener *l,
                             uint32_t status_mask);

/**
 * `topic_set_listener`.
 *
 * # Safety
 * `t` valide.
 */
int zerodds_topic_set_listener(struct zerodds_ZeroDdsTopic *t,
                               const struct zerodds_ZeroDdsTopicListener *l,
                               uint32_t status_mask);

/**
 * `dw_set_listener`.
 *
 * # Safety
 * `dw` valide.
 */
int zerodds_dw_set_listener(struct zerodds_ZeroDdsDataWriter *dw,
                            const struct zerodds_ZeroDdsDataWriterListener *l,
                            uint32_t status_mask);

/**
 * `dr_set_listener`.
 *
 * # Safety
 * `dr` valide.
 */
int zerodds_dr_set_listener(struct zerodds_ZeroDdsDataReader *dr,
                            const struct zerodds_ZeroDdsDataReaderListener *l,
                            uint32_t status_mask);

/**
 * `dp_get_listener` — liefert den zuletzt gesetzten Pointer oder NULL.
 *
 * # Safety
 * `p` valide.
 */
const struct zerodds_ZeroDdsDomainParticipantListener *zerodds_dp_get_listener(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * `dw_get_listener`.
 *
 * # Safety
 * `dw` valide.
 */
const struct zerodds_ZeroDdsDataWriterListener *zerodds_dw_get_listener(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * `dr_get_listener`.
 *
 * # Safety
 * `dr` valide.
 */
const struct zerodds_ZeroDdsDataReaderListener *zerodds_dr_get_listener(struct zerodds_ZeroDdsDataReader *dr);

/**
 * Polls all registered listeners and fires callbacks on status counter
 * deltas. Each entity level (DataWriter/DataReader) and each aggregator
 * level (Publisher/Subscriber/DomainParticipant/Topic) fires independently
 * — multi-bind semantics, no first-match suppression. Returns the number
 * of callbacks fired.
 *
 * # Safety
 * The caller must guarantee that every entity pointer registered in the
 * registry (including the contained child entities) and every listener
 * pointer is still valid (not freed via `*_destroy` without a preceding
 * `set_listener(NULL)`).
 */
uintptr_t zerodds_poll_listeners(void);

/**
 * Creates a topic. Returns NULL on NULL arguments or a topic-name
 * conflict with another type.
 *
 * # Safety
 * `p`, `name`, `type_name` must be valid. `qos` may be NULL
 * (default from `default_topic_qos`).
 */
struct zerodds_ZeroDdsTopic *zerodds_dp_create_topic(struct zerodds_ZeroDdsDomainParticipant *p,
                                                     const char *name,
                                                     const char *type_name,
                                                     const struct zerodds_ZeroDdsTopicQos *qos);

/**
 * Deletes a topic.
 *
 * # Safety
 * `p` and `t` must be valid handles and belong together.
 */
int zerodds_dp_delete_topic(struct zerodds_ZeroDdsDomainParticipant *p,
                            struct zerodds_ZeroDdsTopic *t);

/**
 * Finds an already-created topic by name. Returns NULL if none.
 *
 * # Safety
 * `p`, `name` valid.
 */
struct zerodds_ZeroDdsTopic *zerodds_dp_find_topic(struct zerodds_ZeroDdsDomainParticipant *p,
                                                   const char *name);

/**
 * Creates a publisher.
 *
 * # Safety
 * `p` valid; `qos` may be NULL.
 */
struct zerodds_ZeroDdsPublisher *zerodds_dp_create_publisher(struct zerodds_ZeroDdsDomainParticipant *p,
                                                             const struct zerodds_ZeroDdsPublisherQos *qos);

/**
 * Deletes a publisher.
 *
 * # Safety
 * Both handles valid; the publisher must contain no more DataWriters.
 */
int zerodds_dp_delete_publisher(struct zerodds_ZeroDdsDomainParticipant *p,
                                struct zerodds_ZeroDdsPublisher *pubh);

/**
 * Creates a subscriber.
 *
 * # Safety
 * `p` valid; `qos` may be NULL.
 */
struct zerodds_ZeroDdsSubscriber *zerodds_dp_create_subscriber(struct zerodds_ZeroDdsDomainParticipant *p,
                                                               const zerodds_ZeroDdsSubscriberQos *qos);

/**
 * Deletes a subscriber.
 *
 * # Safety
 * Both handles valid; the subscriber must hold no more DataReaders.
 */
int zerodds_dp_delete_subscriber(struct zerodds_ZeroDdsDomainParticipant *p,
                                 struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Creates a ContentFilteredTopic.
 *
 * # Safety
 * `p`, `name`, `related`, `filter_expression` valid.
 */
struct zerodds_ZeroDdsContentFilteredTopic *zerodds_dp_create_contentfilteredtopic(struct zerodds_ZeroDdsDomainParticipant *p,
                                                                                   const char *name,
                                                                                   struct zerodds_ZeroDdsTopic *related,
                                                                                   const char *filter_expression,
                                                                                   const char *const *parameters,
                                                                                   uintptr_t param_count);

/**
 * Sets the positional CDR field schema on a ContentFilteredTopic so the
 * untyped C-FFI filter actually evaluates the payload (Spec §2.2.2.3.3).
 *
 * `names[i]` is the field name referenced by the filter expression;
 * `kinds[i]` is its CDR encoding (0=bool, 1=int32, 2=int64, 3=float32,
 * 4=float64, 5=string). The fields MUST be listed in their on-wire
 * declaration order, starting from the first member of the payload.
 *
 * This variant assumes a `@final` payload (no leading DHEADER, offset 0). For
 * an `@appendable`/`@mutable` payload use [`zerodds_cft_set_schema_ex`].
 *
 * Note: filter literals are passed as-is — the SQL `WHERE` expression carries
 * its own typed literals (e.g. `seq > 4`, `name = 'foo'`); the schema only
 * declares how to decode the payload columns, it does not coerce the literals.
 *
 * # Safety
 * `cft` valid; `names[0..count]` valid NUL-terminated C strings;
 * `kinds[0..count]` readable.
 */
int zerodds_cft_set_schema(struct zerodds_ZeroDdsContentFilteredTopic *cft,
                           const char *const *names,
                           const uint32_t *kinds,
                           uintptr_t count);

/**
 * Like [`zerodds_cft_set_schema`] but additionally declares the payload's type
 * `extensibility` (XTypes 1.3 §7.3.1.2.1): `0 = @final`, `1 = @appendable`,
 * `2 = @mutable`. For `@appendable`/`@mutable` the XCDR2 stream is prefixed
 * with a 4-byte DHEADER (§7.4.3.4.2) before the first member, so the
 * positional decoder skips 4 bytes; for `@final` the first member is at
 * offset 0. Any other value is rejected.
 *
 * Filter literals are passed as-is (see [`zerodds_cft_set_schema`]).
 *
 * # Safety
 * `cft` valid; `names[0..count]` valid NUL-terminated C strings;
 * `kinds[0..count]` readable.
 */
int zerodds_cft_set_schema_ex(struct zerodds_ZeroDdsContentFilteredTopic *cft,
                              const char *const *names,
                              const uint32_t *kinds,
                              uintptr_t count,
                              uint32_t extensibility);

/**
 * Deletes a ContentFilteredTopic.
 *
 * # Safety
 * Both handles valid.
 */
int zerodds_dp_delete_contentfilteredtopic(struct zerodds_ZeroDdsDomainParticipant *p,
                                           struct zerodds_ZeroDdsContentFilteredTopic *cft);

/**
 * Ignore Participant by InstanceHandle.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_ignore_participant(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Ignore Topic by InstanceHandle.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_ignore_topic(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Ignore Publication by InstanceHandle.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_ignore_publication(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Ignore Subscription by InstanceHandle.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_ignore_subscription(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Domain ID of the participant.
 *
 * # Safety
 * `p` valid.
 */
uint32_t zerodds_dp_get_domain_id(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Asserts liveliness for all MANUAL_BY_PARTICIPANT writers held by the
 * participant.
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_assert_liveliness(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Writes the participant's current wall-clock time into `*out`
 * (Spec §2.2.2.1.1.21 `get_current_time`).
 *
 * # Safety
 * `p` and `out` valid.
 */
int zerodds_dp_get_current_time(struct zerodds_ZeroDdsDomainParticipant *p,
                                struct zerodds_ZeroDdsTime *out);

/**
 * Deletes all topics, publishers, subscribers held by the participant
 * recursively (Spec §2.2.2.2.1.10).
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_delete_contained_entities(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Checks whether an InstanceHandle belongs to an entity in this participant
 * (Spec §2.2.2.2.1.11).
 *
 * # Safety
 * `p` valid.
 */
int zerodds_dp_contains_entity(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Returns the InstanceHandles of all discovered remote participants.
 * `out_handles[0..*out_count]` are written, max `cap`.
 *
 * # Safety
 * `p`, `out_handles`, `out_count` valid; `out_handles[0..cap]` writeable.
 */
int zerodds_dp_get_discovered_participants(struct zerodds_ZeroDdsDomainParticipant *p,
                                           uint64_t *out_handles,
                                           uintptr_t *out_count,
                                           uintptr_t cap);

/**
 * Returns the owning participant.
 *
 * # Safety
 * `pub_` valid.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_pub_get_participant(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * Suspend publications (Spec §2.2.2.4.1.10). Sets a flag — the
 * hot path queues writes instead of sending them, until `resume_publications`.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_suspend_publications(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * Resume publications.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_resume_publications(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * begin_coherent_changes (Spec §2.2.2.4.1.12). In RC1 a no-bracket
 * marker — a spec-conformant tracker at the publisher level; the coherent-set
 * result wire frames live at the writer level and take effect independently.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_begin_coherent_changes(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * end_coherent_changes.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_end_coherent_changes(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * wait_for_acknowledgments(timeout_ms) — waits until all DWs are
 * acked or the timeout fires.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_wait_for_acknowledgments(struct zerodds_ZeroDdsPublisher *pub_,
                                         uint64_t timeout_ms);

/**
 * Creates a DataWriter over the topic.
 *
 * # Safety
 * `pub_`, `topic` valid; `qos` may be NULL (default = pub.default_dw_qos).
 */
struct zerodds_ZeroDdsDataWriter *zerodds_pub_create_datawriter(struct zerodds_ZeroDdsPublisher *pub_,
                                                                struct zerodds_ZeroDdsTopic *topic,
                                                                const struct zerodds_ZeroDdsDataWriterQos *qos);

/**
 * Deletes a DataWriter.
 *
 * # Safety
 * `pub_`, `dw` valid and belonging together.
 */
int zerodds_pub_delete_datawriter(struct zerodds_ZeroDdsPublisher *pub_,
                                  struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Returns the DataWriter for a topic name, or NULL.
 *
 * # Safety
 * `pub_`, `topic_name` valid.
 */
struct zerodds_ZeroDdsDataWriter *zerodds_pub_lookup_datawriter(struct zerodds_ZeroDdsPublisher *pub_,
                                                                const char *topic_name);

/**
 * Deletes all DataWriters held by the publisher.
 *
 * # Safety
 * `pub_` valid.
 */
int zerodds_pub_delete_contained_entities(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * Returns the topic.
 *
 * # Safety
 * `dw` valid.
 */
struct zerodds_ZeroDdsTopic *zerodds_dw_get_topic(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Returns the publisher.
 *
 * # Safety
 * `dw` valid.
 */
struct zerodds_ZeroDdsPublisher *zerodds_dw_get_publisher(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Writes a pre-made CDR payload (the caller serializes via
 * idl codegen or DynamicData). The encap header prefix is added by the
 * runtime.
 *
 * # Safety
 * `dw`, `payload[0..len]` valid. `handle` is a spec-mandatory param that
 * identifies the instance — `0` = HANDLE_NIL = "writer computes it".
 */
int zerodds_dw_write(struct zerodds_ZeroDdsDataWriter *dw,
                     const uint8_t *payload,
                     uintptr_t len,
                     uint64_t _handle);

/**
 * Writes with a source timestamp. RC1 surface: forwards to `write`
 * — the source timestamp lands in the future inline-QoS implementation.
 *
 * # Safety
 * Like `zerodds_dw_write`.
 */
int zerodds_dw_write_w_timestamp(struct zerodds_ZeroDdsDataWriter *dw,
                                 const uint8_t *payload,
                                 uintptr_t len,
                                 uint64_t handle,
                                 int32_t _ts_sec,
                                 uint32_t _ts_nanosec);

/**
 * Dispose: emits a DISPOSED lifecycle marker for the instance.
 *
 * # Safety
 * `dw` valid; `key_hash[0..16]` readable. `handle` informational.
 */
int zerodds_dw_dispose(struct zerodds_ZeroDdsDataWriter *dw,
                       const uint8_t *key_hash,
                       uint64_t _handle);

/**
 * Waits until all currently outstanding writes are acked or a timeout.
 *
 * # Safety
 * `dw` valid.
 */
int zerodds_dw_wait_for_acknowledgments(struct zerodds_ZeroDdsDataWriter *dw, uint64_t timeout_ms);

/**
 * Manually asserts liveliness for this writer.
 *
 * # Safety
 * `dw` valid.
 */
int zerodds_dw_assert_liveliness(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Waits until at least `min` matched subscriptions exist or a timeout.
 *
 * # Safety
 * `dw` valid.
 */
int zerodds_dw_wait_for_matched(struct zerodds_ZeroDdsDataWriter *dw,
                                int32_t min,
                                uint64_t timeout_ms);

/**
 * `LIVELINESS_LOST_STATUS` (Spec §2.2.2.4.2.x).
 *
 * # Safety
 * `dw` and `out` valid.
 */
int zerodds_dw_get_liveliness_lost_status(struct zerodds_ZeroDdsDataWriter *dw,
                                          struct zerodds_ZeroDdsLivelinessLostStatus *out);

/**
 * `OFFERED_DEADLINE_MISSED_STATUS`.
 *
 * # Safety
 * `dw` and `out` valid.
 */
int zerodds_dw_get_offered_deadline_missed_status(struct zerodds_ZeroDdsDataWriter *dw,
                                                  struct zerodds_ZeroDdsOfferedDeadlineMissedStatus *out);

/**
 * `OFFERED_INCOMPATIBLE_QOS_STATUS`.
 *
 * # Safety
 * `dw` and `out` valid.
 */
int zerodds_dw_get_offered_incompatible_qos_status(struct zerodds_ZeroDdsDataWriter *dw,
                                                   struct zerodds_ZeroDdsOfferedIncompatibleQosStatus *out);

/**
 * `PUBLICATION_MATCHED_STATUS`.
 *
 * # Safety
 * `dw` and `out` valid.
 */
int zerodds_dw_get_publication_matched_status(struct zerodds_ZeroDdsDataWriter *dw,
                                              struct zerodds_ZeroDdsPublicationMatchedStatus *out);

/**
 * Creates an empty security config builder.
 *
 * # Safety
 * The return value is Box::into_raw — the caller owns it + must
 * pair `zerodds_security_config_destroy`.
 */
struct zerodds_ZeroDdsSecurityConfig *zerodds_security_config_create(void);

/**
 * Destroys the config builder. NULL-safe.
 *
 * # Safety
 * `cfg` must come from `zerodds_security_config_create` or be NULL.
 */
void zerodds_security_config_destroy(struct zerodds_ZeroDdsSecurityConfig *cfg);

/**
 * Setter `identity_ca_path` (PEM bundle, trust anchors).
 *
 * # Safety
 * `cfg` from `zerodds_security_config_create`, `path` null-terminated or NULL.
 */
int32_t zerodds_security_set_identity_ca_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                              const char *path);

/**
 * Setter `identity_cert_path` (PEM, local identity cert).
 *
 * # Safety
 * See [`zerodds_security_set_identity_ca_path`].
 */
int32_t zerodds_security_set_identity_cert_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                                const char *path);

/**
 * Setter `identity_key_path` (PKCS#8 PEM private key).
 *
 * # Safety
 * See [`zerodds_security_set_identity_ca_path`].
 */
int32_t zerodds_security_set_private_key_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                              const char *path);

/**
 * Setter `permissions_ca_path` (PEM bundle, often = identity_ca).
 *
 * # Safety
 * See [`zerodds_security_set_identity_ca_path`].
 */
int32_t zerodds_security_set_permissions_ca_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                                 const char *path);

/**
 * Setter `governance_path` (CMS-signed governance XML, `.p7s`).
 *
 * # Safety
 * See [`zerodds_security_set_identity_ca_path`].
 */
int32_t zerodds_security_set_governance_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                             const char *path);

/**
 * Setter `permissions_path` (CMS-signed permissions XML, `.p7s`).
 *
 * # Safety
 * See [`zerodds_security_set_identity_ca_path`].
 */
int32_t zerodds_security_set_permissions_path(struct zerodds_ZeroDdsSecurityConfig *cfg,
                                              const char *path);

/**
 * Creates a ZeroDDS runtime with DDS-Security 1.2 active.
 *
 * `cfg` must have all 6 paths set; PKI + CMS verify + governance/
 * permissions parsing run synchronously on the call. On error in
 * one of the steps: NULL return + stderr diag, **but** `cfg`
 * stays unchanged (no auto-destroy).
 *
 * # Safety
 * `cfg` from `zerodds_security_config_create` (or NULL). `cfg` must
 * not be mutated concurrently from another thread.
 */
struct zerodds_ZeroDdsRuntime *zerodds_runtime_create_secure(uint32_t domain_id,
                                                             const struct zerodds_ZeroDdsSecurityConfig *cfg);

/**
 * Creates a ZeroDDS runtime with DDS-Security from an **SROS2 enclave**
 * (C7 "secure by default"). Reads `ZERODDS_SECURITY_DIR` (enclave directory)
 * and `ROS_DOMAIN_ID`, and builds the `SecurityProfile` in one call — no
 * per-path setter ceremony.
 *
 * Return: NULL if `ZERODDS_SECURITY_DIR` is not set (the caller then falls
 * back to the plain path) OR on a load/verify error (stderr diag);
 * otherwise the secured runtime. `domain_id` does not override `ROS_DOMAIN_ID` —
 * it is the explicit value the runtime starts with.
 *
 * # Safety
 * No pointer arguments; always callable.
 */
struct zerodds_ZeroDdsRuntime *zerodds_runtime_create_secure_from_env(uint32_t domain_id);

/**
 * Enables zero-copy SHM loan on a DCPS DataWriter. Creates a POSIX
 * shared-memory segment of `slot_count` slots × `slot_capacity` bytes at the
 * flink path `name`. After this, `zerodds_dw_loan_message` returns a pointer
 * into a SHM slot and `zerodds_dw_commit_loan` finalizes it in place.
 *
 * # Safety
 * `dw` is a valid registered DataWriter; `name` is a NUL-terminated C string.
 */
int zerodds_dw_enable_shm_loan(struct zerodds_ZeroDdsDataWriter *dw,
                               const char *name,
                               uintptr_t slot_count,
                               uintptr_t slot_capacity);

/**
 * Sets the delivery mode of a DCPS DataWriter (`zerodds-delivery-modes-1.0`
 * §3/§4): `0`=Portable (default, interop-safe), `1`=RawSameHost (same-host,
 * no wire). `2`=Iceoryx is not yet wired → `Unsupported`. Other values →
 * `BadParameter`.
 *
 * # Safety
 * `dw` is a valid registered DataWriter.
 */
int zerodds_dw_set_delivery_mode(struct zerodds_ZeroDdsDataWriter *dw, int mode);

/**
 * Maps the writer's SHM segment at flink path `name` on a DCPS DataReader for
 * zero-copy reads. `reader_index` is the reader's bit (0..32) in the slot mask.
 *
 * # Safety
 * `dr` valid; `name` is a NUL-terminated C string.
 */
int zerodds_dr_enable_shm(struct zerodds_ZeroDdsDataReader *dr,
                          const char *name,
                          uint8_t reader_index);

/**
 * Zero-copy take on a DCPS DataReader: returns a read-only pointer into the
 * writer's SHM slot, its length and the slot index (for
 * `zerodds_dr_release_shm`). `NoData` when nothing is pending.
 *
 * # Safety
 * `dr`/`out_ptr`/`out_len`/`out_slot` valid.
 */
int zerodds_dr_take_shm(struct zerodds_ZeroDdsDataReader *dr,
                        const uint8_t **out_ptr,
                        uintptr_t *out_len,
                        uint32_t *out_slot);

/**
 * Releases a slot previously returned by `zerodds_dr_take_shm`.
 *
 * # Safety
 * `dr` valid; `slot_index` from a prior `zerodds_dr_take_shm`.
 */
int zerodds_dr_release_shm(struct zerodds_ZeroDdsDataReader *dr, uint32_t slot_index);

/**
 * Enables `Iceoryx` delivery on a DCPS DataWriter (feature `delivery-iceoryx`):
 * publishes the writer's samples over the iceoryx2 service `service_name`, with
 * a max payload of `max_len` bytes. The loan API then routes through iceoryx2
 * and commit does not publish over RTPS.
 *
 * # Safety
 * `dw` is a valid registered DataWriter; `service_name` is a NUL-terminated C
 * string.
 */
int zerodds_dw_enable_iceoryx(struct zerodds_ZeroDdsDataWriter *dw,
                              const char *service_name,
                              uintptr_t max_len);

/**
 * Enables `Iceoryx` delivery on a DCPS DataReader: receives samples from the
 * iceoryx2 service `service_name` via `zerodds_dr_take_shm` /
 * `zerodds_dr_release_shm`.
 *
 * # Safety
 * `dr` valid; `service_name` is a NUL-terminated C string.
 */
int zerodds_dr_enable_iceoryx(struct zerodds_ZeroDdsDataReader *dr, const char *service_name);

/**
 * Returns the owning participant.
 *
 * # Safety
 * `sub` valid.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_sub_get_participant(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * `begin_access` (Spec §2.2.2.5.1.13). RC1: no-op marker for
 * coherent sets — the real set boundaries are on the reader wire path.
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_begin_access(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * `end_access`.
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_end_access(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Returns the list of active DataReaders.
 *
 * # Safety
 * `sub`, `out`, `out_count` valid.
 */
int zerodds_sub_get_datareaders(struct zerodds_ZeroDdsSubscriber *sub,
                                struct zerodds_ZeroDdsDataReader **out,
                                uintptr_t *out_count,
                                uintptr_t cap);

/**
 * `notify_datareaders` (Spec §2.2.2.5.1.16). RC1: no-op — the listener bubble-up
 * runs per-reader, the subscriber aggregator is wired in the WP "Listeners-FFI".
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_notify_datareaders(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Creates a DataReader.
 *
 * # Safety
 * `sub`, `topic` valid; `qos` may be NULL.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_create_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                                                struct zerodds_ZeroDdsTopic *topic,
                                                                const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * Creates a DataReader on a ContentFilteredTopic.
 * On every `take`/`read` the filter expression is evaluated
 * (Spec §2.2.2.3.3 + §2.2.2.5.2.5).
 *
 * # Safety
 * `sub`, `cft` valid; `qos` may be NULL.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_create_datareader_with_cft(struct zerodds_ZeroDdsSubscriber *sub,
                                                                         struct zerodds_ZeroDdsContentFilteredTopic *cft,
                                                                         const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * Deletes a DataReader.
 *
 * # Safety
 * `sub`, `dr` valid and belonging together.
 */
int zerodds_sub_delete_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                  struct zerodds_ZeroDdsDataReader *dr);

/**
 * Look up a DataReader by topic name.
 *
 * # Safety
 * `sub`, `topic_name` valid.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_lookup_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                                                const char *topic_name);

/**
 * Deletes all DataReaders held by the subscriber.
 *
 * # Safety
 * `sub` valid.
 */
int zerodds_sub_delete_contained_entities(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Returns the TopicDescription handle (in RC1: the topic pointer).
 *
 * # Safety
 * `dr` valid.
 */
struct zerodds_ZeroDdsTopic *zerodds_dr_get_topicdescription(struct zerodds_ZeroDdsDataReader *dr);

/**
 * Returns the subscriber.
 *
 * # Safety
 * `dr` valid.
 */
struct zerodds_ZeroDdsSubscriber *zerodds_dr_get_subscriber(struct zerodds_ZeroDdsDataReader *dr);

/**
 * Take: consumes samples from the cache + channel (Spec §2.2.2.5.3).
 * Goes through read_cache (sample-state READ + NOT_READ) and the channel
 * (sample-state NOT_READ), removes all delivered samples.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_take(struct zerodds_ZeroDdsDataReader *dr,
                    struct zerodds_ZeroDdsSampleArray *out,
                    uintptr_t max_samples,
                    uint32_t _sample_states,
                    uint32_t _view_states,
                    uint32_t _instance_states);

/**
 * Read: non-destructive variant of take (Spec §2.2.2.5.3).
 * Returns samples from the cache + channel, but ALL of them remain afterwards
 * in the read cache with sample-state = READ.
 *
 * # Safety
 * `dr`, `out` valid.
 */
int zerodds_dr_read(struct zerodds_ZeroDdsDataReader *dr,
                    struct zerodds_ZeroDdsSampleArray *out,
                    uintptr_t max_samples,
                    uint32_t _sample_states,
                    uint32_t _view_states,
                    uint32_t _instance_states);

/**
 * Take next single sample.
 *
 * # Safety
 * `dr`, `out_buf`, `out_len`, `out_info` valid.
 */
int zerodds_dr_take_next_sample(struct zerodds_ZeroDdsDataReader *dr,
                                uint8_t **out_buf,
                                uintptr_t *out_len,
                                struct zerodds_ZeroDdsSampleInfo *out_info);

/**
 * Read next single sample. Identical to take_next_sample in RC1.
 *
 * # Safety
 * Like `take_next_sample`.
 */
int zerodds_dr_read_next_sample(struct zerodds_ZeroDdsDataReader *dr,
                                uint8_t **out_buf,
                                uintptr_t *out_len,
                                struct zerodds_ZeroDdsSampleInfo *out_info);

/**
 * Returns loaned sample buffers.
 *
 * # Safety
 * `arr` must come from a previous `zerodds_dr_take`/`read`,
 * `loan_token` must still be valid.
 */
int zerodds_dr_return_loan(struct zerodds_ZeroDdsDataReader *_dr,
                           struct zerodds_ZeroDdsSampleArray *arr);

/**
 * Waits until `min` matched publications or a timeout.
 *
 * # Safety
 * `dr` valid.
 */
int zerodds_dr_wait_for_matched(struct zerodds_ZeroDdsDataReader *dr,
                                int32_t min,
                                uint64_t timeout_ms);

/**
 * `LIVELINESS_CHANGED_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_liveliness_changed_status(struct zerodds_ZeroDdsDataReader *dr,
                                             struct zerodds_ZeroDdsLivelinessChangedStatus *out);

/**
 * `SUBSCRIPTION_MATCHED_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_subscription_matched_status(struct zerodds_ZeroDdsDataReader *dr,
                                               struct zerodds_ZeroDdsSubscriptionMatchedStatus *out);

/**
 * `REQUESTED_DEADLINE_MISSED_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_requested_deadline_missed_status(struct zerodds_ZeroDdsDataReader *dr,
                                                    struct zerodds_ZeroDdsRequestedDeadlineMissedStatus *out);

/**
 * `REQUESTED_INCOMPATIBLE_QOS_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_requested_incompatible_qos_status(struct zerodds_ZeroDdsDataReader *dr,
                                                     struct zerodds_ZeroDdsRequestedIncompatibleQosStatus *out);

/**
 * `SAMPLE_LOST_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_sample_lost_status(struct zerodds_ZeroDdsDataReader *dr,
                                      struct zerodds_ZeroDdsSampleLostStatus *out);

/**
 * `SAMPLE_REJECTED_STATUS`.
 *
 * # Safety
 * `dr` and `out` valid.
 */
int zerodds_dr_get_sample_rejected_status(struct zerodds_ZeroDdsDataReader *dr,
                                          struct zerodds_ZeroDdsSampleRejectedStatus *out);

/**
 * Returns the topic name as a heap-allocated C string. The caller must
 * call `zerodds_string_free`.
 *
 * # Safety
 * `t` valid.
 */
char *zerodds_topic_get_name(struct zerodds_ZeroDdsTopic *t);

/**
 * Returns the topic type name. The caller must call `zerodds_string_free`.
 *
 * # Safety
 * `t` valid.
 */
char *zerodds_topic_get_type_name(struct zerodds_ZeroDdsTopic *t);

/**
 * Returns the owning participant.
 *
 * # Safety
 * `t` valid.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_topic_get_participant(struct zerodds_ZeroDdsTopic *t);

/**
 * Frees a C string previously allocated by `zerodds_topic_get_*`.
 *
 * # Safety
 * `s` must come from a `zerodds_*_get_*` function that produces a
 * `*mut c_char` via `CString::into_raw`.
 */
void zerodds_string_free(char *s);

/**
 * Get QoS into `out` (Spec §2.2.2.3.2.x).
 * `out` is `*mut ZeroDdsTopicQos` with a caller-supplied buffer for
 * `topic_data.value` (variable length).
 *
 * # Safety
 * `t`, `out` valid.
 */
int zerodds_topic_get_qos(struct zerodds_ZeroDdsTopic *t, struct zerodds_ZeroDdsTopicQos *out);

/**
 * Set QoS (Spec §2.2.2.3.2.x). NULL = default.
 *
 * # Safety
 * `t` valid.
 */
int zerodds_topic_set_qos(struct zerodds_ZeroDdsTopic *t,
                          const struct zerodds_ZeroDdsTopicQos *qos);

/**
 * Returns the InconsistentTopicStatus.
 *
 * # Safety
 * `t` and `out` valid.
 */
int zerodds_topic_get_inconsistent_topic_status(struct zerodds_ZeroDdsTopic *t,
                                                struct zerodds_ZeroDdsInconsistentTopicStatus *out);

/**
 * Creates a typed topic handle. Stores the TypeSupport
 * table so that writer/reader operations can access it.
 *
 * `out_topic` must be non-NULL and is set to the newly allocated
 * topic handle. The caller MUST later call
 * `zerodds_topic_destroy_typed`.
 *
 * # Safety
 * `participant`/`topic_name`/`type_support`/`out_topic` must be valid
 * pointers. `topic_name` must be NUL-terminated. `type_support`
 * MUST point to a static table with live function pointers.
 */
int zerodds_topic_create_typed(struct zerodds_ZeroDdsRuntime *participant,
                               const char *topic_name,
                               const struct zerodds_ZeroDdsTypeSupport *type_support,
                               struct zerodds_ZeroDdsTopic **out_topic);

/**
 * Destroys a topic handle. NULL-safe.
 *
 * # Safety
 * `topic` must come from `zerodds_topic_create_typed` or be NULL.
 */
void zerodds_topic_destroy_typed(struct zerodds_ZeroDdsTopic *topic);

/**
 * Standalone encoder. Calls `ts.encode(sample, out_buf, out_cap, out_len)`
 * and passes the return code through.
 *
 * `out_buf=NULL` with `out_cap=0` is a size probe: the codegen encoder
 * MUST set `out_len` to the needed size and
 * return `BUFFER_TOO_SMALL`.
 *
 * # Safety
 * `ts`, `sample`, `out_len` must be valid pointers. `out_buf` may
 * be NULL if `out_cap = 0`.
 */
int zerodds_xcdr2_encode(const struct zerodds_ZeroDdsTypeSupport *ts,
                         const void *sample,
                         uint8_t *out_buf,
                         uintptr_t out_cap,
                         uintptr_t *out_len);

/**
 * Standalone decoder. Calls `ts.decode(buf, len, out_sample)`.
 *
 * # Safety
 * `ts`/`buf`/`out_sample` valid; `buf` must be readable for `len` bytes;
 * `out_sample` must point zero-initialized to the language type.
 */
int zerodds_xcdr2_decode(const struct zerodds_ZeroDdsTypeSupport *ts,
                         const uint8_t *buf,
                         uintptr_t len,
                         void *out_sample);

/**
 * Standalone representation-aware decoder (Bug R4b). Prefers
 * `ts.decode_repr(buf, len, representation, out_sample)` when present so
 * the decoder can pick the correct `max_align` (8 for XCDR1 = `0`,
 * 4 for XCDR2 = `1`); falls back to the legacy `ts.decode` when the
 * TypeSupport table predates the repr-aware entry-point.
 *
 * `representation`: `0` = XCDR1, `1` = XCDR2 (the value reported by
 * `zerodds_reader_take`'s `out_repr`).
 *
 * # Safety
 * `ts`/`buf`/`out_sample` valid; `buf` readable for `len` bytes;
 * `out_sample` zero-initialized to the language type.
 */
int zerodds_xcdr2_decode_repr(const struct zerodds_ZeroDdsTypeSupport *ts,
                              const uint8_t *buf,
                              uintptr_t len,
                              uint8_t representation,
                              void *out_sample);

/**
 * Writes a typed sample. Encodes via
 * `ts.encode` into an internal heap buffer and passes the bytes to
 * `zerodds_writer_write`.
 *
 * Strategy:
 * 1. Size probe (`out_buf=NULL`).
 * 2. Allocate a heap buffer of the probed size.
 * 3. Real encode in.
 * 4. `zerodds_writer_write(writer, bytes, len)`.
 *
 * # Safety
 * `writer`/`ts`/`sample` valid; cf. `zerodds_writer_write` and
 * `zerodds_xcdr2_encode`.
 */
int zerodds_writer_write_typed(struct zerodds_ZeroDdsWriter *writer,
                               const struct zerodds_ZeroDdsTypeSupport *ts,
                               const void *sample);

/**
 * Reads a typed sample. Fetches bytes via `zerodds_reader_take`
 * and decodes them via `ts.decode` into `out_sample`.
 *
 * `out_info` is currently unused (reserved for the sample-info spec
 * rollout); MUST be NULL or point to a caller-allocated
 * `zerodds_sample_info_t` that is filled with default values.
 *
 * Returns:
 * - 0 (Ok) if a sample was decoded successfully.
 * - `NoData` (-7) if the reader is empty.
 * - other negative codes on a decoder error.
 *
 * # Safety
 * `reader`/`ts`/`out_sample` valid. `out_info` NULL or valid.
 */
int zerodds_reader_take_typed(struct zerodds_ZeroDdsReader *reader,
                              const struct zerodds_ZeroDdsTypeSupport *ts,
                              void *out_sample,
                              void *out_info);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* ZERODDS_H */