zerodds-c-api 1.0.0-rc.1

/*
 * 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().
 */


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

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

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

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

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

/**
 * 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;

/**
 * GuardCondition (Spec §2.2.2.1.2.1.6).
 */
typedef struct zerodds_ZeroDdsGuardCondition zerodds_ZeroDdsGuardCondition;

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

/**
 * QueryCondition (Spec §2.2.2.5.9).
 */
typedef struct zerodds_ZeroDdsQueryCondition zerodds_ZeroDdsQueryCondition;

/**
 * ReadCondition (Spec §2.2.2.5.8).
 */
typedef struct zerodds_ZeroDdsReadCondition zerodds_ZeroDdsReadCondition;

/**
 * Opaque Reader-Handle.
 */
typedef struct zerodds_ZeroDdsReader zerodds_ZeroDdsReader;

/**
 * Opaque Runtime-Handle. Hält die DcpsRuntime + spawned threads.
 */
typedef struct zerodds_ZeroDdsRuntime zerodds_ZeroDdsRuntime;

/**
 * StatusCondition (Spec §2.2.2.1.2.1.4). Im RC1 an `Entity = void*`
 * gebunden — kein Status-Polling-Plumb (folge-WP).
 */
typedef struct zerodds_ZeroDdsStatusCondition zerodds_ZeroDdsStatusCondition;

/**
 * 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 auf UserData-Bytes (statisch ueber `dp`-Lifetime im RC1
   * Snapshot — Caller kopiert wenn er die Daten ueberlebt).
   */
  const uint8_t *user_data;
  /**
   * UserData-Laenge.
   */
  uintptr_t user_data_len;
} zerodds_ZeroDdsParticipantBuiltinTopicData;

/**
 * `DCPSTopic`-Sample (Spec §2.2.5.2).
 */
typedef struct zerodds_ZeroDdsTopicBuiltinTopicData {
  /**
   * Synthetischer Topic-Key (16 byte).
   */
  uint8_t key[16];
  /**
   * Topic-Name als C-String (heap-allokiert; Caller muss
   * `zerodds_string_free` rufen).
   */
  char *name;
  /**
   * Type-Name (heap-allokiert; Caller muss `zerodds_string_free` rufen).
   */
  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 (für 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. Liste C-string-Pointer + Anzahl.
 */
typedef struct zerodds_ZeroDdsPartitionQosPolicy {
  /**
   * Array von C-String-Pointern (Caller-owned).
   */
  const char *const *names;
  /**
   * Anzahl.
   */
  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-allokiert).
   */
  char *topic_name;
  /**
   * Type-Name (heap-allokiert).
   */
  char *type_name;
  /**
   * Durability.
   */
  uint32_t durability_kind;
  /**
   * Reliability.
   */
  uint32_t reliability_kind;
  /**
   * Ownership.
   */
  uint32_t ownership_kind;
  /**
   * Liveliness-Lease in Sekunden.
   */
  int32_t liveliness_lease_seconds;
  /**
   * Deadline-Period in Sekunden.
   */
  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` wenn payload tatsaechlich Daten hat (vs. Lifecycle-Marker).
   */
  bool valid_data;
} zerodds_ZeroDdsSampleInfo;

/**
 * Sample-Array (Spec §5 Mini-Spec).
 */
typedef struct zerodds_ZeroDdsSampleArray {
  /**
   * Array von Payload-Pointern.
   */
  uint8_t **buffers;
  /**
   * Array von Payload-Laengen.
   */
  uintptr_t *lengths;
  /**
   * Array von SampleInfos.
   */
  struct zerodds_ZeroDdsSampleInfo *infos;
  /**
   * Anzahl Samples.
   */
  uintptr_t count;
  /**
   * Internes Loan-Token (Pointer auf `Vec<UserSample>` Box). Wird
   * von `return_loan` freigegeben.
   */
  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-allokiert; via `zerodds_string_free`).
   */
  char *topic_name;
  /**
   * Type-Name (heap-allokiert).
   */
  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 Sekunden.
   */
  int32_t liveliness_lease_seconds;
  /**
   * Deadline-Period in Sekunden.
   */
  int32_t deadline_seconds;
  /**
   * Lifespan-Duration in Sekunden.
   */
  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;

/**
 * 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, ohne Per-Policy-Liste —
 * `last_policy_id` deckt den Pflicht-Pfad).
 */
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-Funktion-Tabelle (Vendor-Spec §2).
 *
 * ABI-stabil; Felder sind versioniert via `zerodds_c_api_version()`.
 * Pro IDL-Type emittiert der C-Codegen genau eine `static const`-
 * Instanz dieser Struktur.
 *
 * Layout-Gruende:
 * - 16-Byte `type_hash` zuerst (XTypes EquivalenceHash).
 * - `type_name` als NUL-terminierter Pointer (kein owned String).
 * - `is_keyed` + `extensibility` als `u8` fuer kompakte Packung.
 * - 6 Byte Padding bis zu den function-pointer-aligned Feldern.
 * - 5 Function-Pointers in fester Reihenfolge.
 */
typedef struct zerodds_ZeroDdsTypeSupport {
  /**
   * 16-Byte EquivalenceHash (XTypes §7.3.4).
   */
  uint8_t type_hash[16];
  /**
   * NUL-terminierter Type-Name (Module::Sub::Struct, ASCII).
   */
  const char *type_name;
  /**
   * 1 = mindestens ein @key-Member vorhanden.
   */
  uint8_t is_keyed;
  /**
   * 0=Final, 1=Appendable, 2=Mutable.
   */
  uint8_t extensibility;
  /**
   * Reserved fuer zukuenftige Felder. MUSS auf 0 stehen.
   */
  uint8_t _reserved[6];
  /**
   * Encoder-Pointer (siehe `ZeroDdsEncodeFn`).
   */
  zerodds_Option_ZeroDdsEncodeFn encode;
  /**
   * Decoder-Pointer (siehe `ZeroDdsDecodeFn`).
   */
  zerodds_Option_ZeroDdsDecodeFn decode;
  /**
   * Key-Hash-Pointer (siehe `ZeroDdsKeyHashFn`); NULL erlaubt wenn
   * `is_keyed = 0`.
   */
  zerodds_Option_ZeroDdsKeyHashFn key_hash;
  /**
   * Sample-Free-Pointer (siehe `ZeroDdsSampleFreeFn`); NULL erlaubt
   * wenn der Type keine heap-Felder hat.
   */
  zerodds_Option_ZeroDdsSampleFreeFn sample_free;
} zerodds_ZeroDdsTypeSupport;

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

/**
 * Erzeugt eine neue ZeroDDS-Runtime auf der gegebenen Domain-ID.
 *
 * # Safety
 * Der Rückgabewert ist ein Heap-allokierter Pointer; der Aufrufer muss
 * ihn mit `zerodds_runtime_destroy` freigeben.
 *
 * Liefert `NULL` bei Fehler.
 */
struct zerodds_ZeroDdsRuntime *zerodds_runtime_create(uint32_t domain_id);

/**
 * Zerstört eine Runtime. NULL-safe.
 *
 * # Safety
 * `runtime` muss aus `zerodds_runtime_create` stammen oder NULL sein.
 */
void zerodds_runtime_destroy(struct zerodds_ZeroDdsRuntime *runtime);

/**
 * Wartet bis SPDP mindestens `min_count` Remote-Participants entdeckt
 * hat. Returnt 0 (Ok) bei Erfolg, -4 (Timeout) wenn die Zahl in
 * `timeout_ms` nicht erreicht wird.
 *
 * **Optional, nicht zwingend.** SEDP ist reliable + behaelt History,
 * also wird ein zu frueh registrierter Endpoint sich nach 600-720 ms
 * (empirisch llvm-Linux) selbst heilen sobald SPDP den Peer sieht
 * und der Heartbeat-Replay durchlaeuft. Dieser Helper ist nuetzlich
 * wenn man deterministisches Test-Setup will oder einen langen
 * Publish-Loop vermeiden moechte.
 *
 * # Safety
 * `runtime` muss aus `zerodds_runtime_create` stammen oder NULL sein.
 */
int zerodds_runtime_wait_for_peers(struct zerodds_ZeroDdsRuntime *runtime,
                                   int min_count,
                                   uint64_t timeout_ms);

/**
 * Erzeugt einen DataWriter auf einem Topic. Topic + Type werden by-name
 * identifiziert (DDS-Spec §2.2.2).
 *
 * # Safety
 * `runtime` muss valide sein. `topic_name` und `type_name` müssen
 * NUL-terminierte UTF-8-Strings sein.
 */
struct zerodds_ZeroDdsWriter *zerodds_writer_create(struct zerodds_ZeroDdsRuntime *runtime,
                                                    const char *topic_name,
                                                    const char *type_name,
                                                    int reliable);

/**
 * Schreibt einen Sample. `payload` zeigt auf bereits-CDR-encodete Bytes.
 *
 * # Safety
 * `writer` und `payload` muessen valide sein, `len` <= Buffergröße.
 */
int zerodds_writer_write(struct zerodds_ZeroDdsWriter *writer,
                         const uint8_t *payload,
                         uintptr_t len);

/**
 * Wartet bis mindestens `min_count` Subscriptions gematcht haben oder
 * Timeout abläuft. `timeout_ms` = 0 -> non-blocking poll.
 *
 * # Safety
 * `writer` muss valide sein.
 */
int zerodds_writer_wait_for_matched(struct zerodds_ZeroDdsWriter *writer,
                                    int min_count,
                                    uint64_t timeout_ms);

/**
 * Sendet einen Lifecycle-Marker (Spec §9.6.3.9 PID_STATUS_INFO):
 * `dispose` setzt das DISPOSED-Bit, sodass Remote-Reader die Instanz
 * als NotAliveDisposed klassifizieren. Der Caller muss den 16-byte
 * Key-Hash der Instanz uebergeben (PLAIN_CDR2-BE-Encoding mit Zero-
 * Padding bzw. MD5 falls > 16 byte).
 *
 * # Safety
 * `writer` und `key_hash` muessen valide sein; `key_hash` muss auf
 * genau 16 byte zeigen.
 */
int zerodds_writer_dispose(struct zerodds_ZeroDdsWriter *writer, const uint8_t *key_hash);

/**
 * Sendet einen UNREGISTER-Marker (Spec §2.2.2.4.2.7). Setzt nur das
 * UNREGISTERED-Bit (kein autodispose). Caller, der Spec-Default-
 * Verhalten will (autodispose=true), soll stattdessen
 * `zerodds_writer_unregister_with_dispose` nutzen.
 *
 * # Safety
 * Wie [`zerodds_writer_dispose`].
 */
int zerodds_writer_unregister(struct zerodds_ZeroDdsWriter *writer, const uint8_t *key_hash);

/**
 * Sendet kombinierten DISPOSE+UNREGISTER-Marker (Spec §2.2.3.21 mit
 * `autodispose_unregistered_instances=true`). Reader sieht sowohl
 * NotAliveDisposed als auch NotAliveNoWriters.
 *
 * # Safety
 * Wie [`zerodds_writer_dispose`].
 */
int zerodds_writer_unregister_with_dispose(struct zerodds_ZeroDdsWriter *writer,
                                           const uint8_t *key_hash);

/**
 * Zerstört einen Writer. NULL-safe.
 *
 * # Safety
 * `writer` muss aus `zerodds_writer_create` stammen oder NULL sein.
 */
void zerodds_writer_destroy(struct zerodds_ZeroDdsWriter *writer);

/**
 * Erzeugt einen DataReader auf einem Topic.
 *
 * # Safety
 * Wie `zerodds_writer_create`.
 */
struct zerodds_ZeroDdsReader *zerodds_reader_create(struct zerodds_ZeroDdsRuntime *runtime,
                                                    const char *topic_name,
                                                    const char *type_name,
                                                    int reliable);

/**
 * Versucht einen Sample zu lesen.
 * * Bei Erfolg: schreibt allocierten Buffer in `*out_buf`, dessen
 *   Länge in `*out_len`. Caller MUSS `zerodds_buffer_free(*out_buf)`.
 * * Bei keinem Sample: `*out_buf = NULL`, `*out_len = 0`, return Ok.
 * * Bei Fehler: negativer Statuscode.
 *
 * # Safety
 * Pointers müssen valide sein.
 */
int zerodds_reader_take(struct zerodds_ZeroDdsReader *reader,
                        uint8_t **out_buf,
                        uintptr_t *out_len);

/**
 * Wartet bis mindestens `min_count` Publications gematcht haben.
 *
 * # Safety
 * `reader` muss valide sein.
 */
int zerodds_reader_wait_for_matched(struct zerodds_ZeroDdsReader *reader,
                                    int min_count,
                                    uint64_t timeout_ms);

/**
 * Zerstört einen Reader. NULL-safe.
 *
 * # Safety
 * Wie `zerodds_writer_destroy`.
 */
void zerodds_reader_destroy(struct zerodds_ZeroDdsReader *reader);

int zerodds_reader_set_data_callback(struct zerodds_ZeroDdsReader *reader,
                                     zerodds_Option_ZeroDdsDataCallback callback,
                                     void *user_data);

/**
 * Gibt einen Buffer frei, den ein vorheriges `zerodds_reader_take`
 * alloziert hat. NULL-safe.
 *
 * # Safety
 * `buf` muss aus `zerodds_reader_take` stammen oder NULL sein.
 * `len` muss exakt der zu dem Buffer gehörige Wert sein.
 */
void zerodds_buffer_free(uint8_t *buf, uintptr_t len);

/**
 * Reserviert einen Output-Buffer beim Writer fuer Zero-Copy-Publish.
 * Caller schreibt den Sample in den zurueckgegebenen Pointer und
 * commit'd ihn dann via [`zerodds_writer_commit_loan`].
 *
 * Returnt 0 (Ok) bei Erfolg + befuellt `*out_ptr` und `*out_len`.
 * Beim heutigen malloc-backed Pfad ist `*out_len = len`; bei
 * SHM-backed Loans kann `*out_len > len` sein (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-Pfad: schreibt den geliehenen Buffer als Sample und gibt
 * ihn frei. Caller darf den Pointer danach nicht mehr lesen.
 *
 * # Safety
 * `writer` aus `zerodds_writer_create`; `ptr` aus
 * `zerodds_writer_loan_message`; `len` der gleiche Wert wie in
 * `out_len` zurueckgegeben.
 */
int zerodds_writer_commit_loan(struct zerodds_ZeroDdsWriter *writer, uint8_t *ptr, uintptr_t len);

/**
 * Verwirft einen Loan ohne ihn zu publishen. Buffer wird freigegeben.
 *
 * # Safety
 * Wie `zerodds_writer_commit_loan`.
 */
int zerodds_writer_discard_loan(struct zerodds_ZeroDdsWriter *_writer, uint8_t *ptr, uintptr_t len);

/**
 * Version-String des C-FFI. Statisch, nicht freizugeben.
 */
const char *zerodds_version(void);

/**
 * Liefert die InstanceHandles aller entdeckten Topics.
 *
 * # Safety
 * `p`, `out`, `out_count` valide.
 */
int zerodds_dp_get_discovered_topics(struct zerodds_ZeroDdsDomainParticipant *p,
                                     uint64_t *out,
                                     uintptr_t *out_count,
                                     uintptr_t cap);

/**
 * Liefert die `ParticipantBuiltinTopicData` zu einem InstanceHandle.
 *
 * # Safety
 * `p`, `out` valide.
 */
int zerodds_dp_get_discovered_participant_data(struct zerodds_ZeroDdsDomainParticipant *p,
                                               uint64_t handle,
                                               struct zerodds_ZeroDdsParticipantBuiltinTopicData *out);

/**
 * Gibt einen vorher allokierten UserData-Slice zurueck.
 *
 * # Safety
 * `p[0..len]` muss aus `dp_get_discovered_participant_data` stammen.
 */
void zerodds_builtin_userdata_free(const uint8_t *p, uintptr_t len);

/**
 * Liefert die `TopicBuiltinTopicData` zu einem InstanceHandle.
 *
 * # Safety
 * `p`, `out` valide.
 */
int zerodds_dp_get_discovered_topic_data(struct zerodds_ZeroDdsDomainParticipant *p,
                                         uint64_t handle,
                                         struct zerodds_ZeroDdsTopicBuiltinTopicData *out);

/**
 * Anzahl entdeckter Publications (Spec §2.2.2.2.1.13).
 *
 * # Safety
 * `p` valide.
 */
uintptr_t zerodds_dp_discovered_publications_count(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Anzahl entdeckter Subscriptions.
 *
 * # Safety
 * `p` valide.
 */
uintptr_t zerodds_dp_discovered_subscriptions_count(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Liest den aktuellen Trigger-Status einer Condition (Spec §2.2.2.1.2.1.1).
 *
 * # Safety
 * `c` valide oder NULL.
 */
bool zerodds_condition_get_trigger_value(const void *c);

/**
 * Erzeugt GuardCondition.
 */
struct zerodds_ZeroDdsGuardCondition *zerodds_guardcondition_create(void);

/**
 * Loescht GuardCondition.
 *
 * # Safety
 * `g` muss aus `zerodds_guardcondition_create` stammen.
 */
void zerodds_guardcondition_destroy(struct zerodds_ZeroDdsGuardCondition *g);

/**
 * Setzt den Trigger-Wert.
 *
 * # Safety
 * `g` valide.
 */
int zerodds_guardcondition_set_trigger_value(struct zerodds_ZeroDdsGuardCondition *g, bool v);

/**
 * Erzeugt eine StatusCondition fuer eine Entity. RC1: erlaubt jeden
 * `*mut c_void` als Entity-Slot — Match-Logik liest den Status pro
 * Entity-Type via Listener-FFI (folge-WP).
 *
 * # Safety
 * `entity` valide oder NULL.
 */
struct zerodds_ZeroDdsStatusCondition *zerodds_entity_get_statuscondition(void *entity);

/**
 * Aktiviert die in `mask` gesetzten Status-Bits.
 *
 * # Safety
 * `c` valide.
 */
int zerodds_statuscondition_set_enabled_statuses(struct zerodds_ZeroDdsStatusCondition *c,
                                                 uint32_t mask);

/**
 * Liest die aktivierten Status-Bits.
 *
 * # Safety
 * `c` valide.
 */
uint32_t zerodds_statuscondition_get_enabled_statuses(struct zerodds_ZeroDdsStatusCondition *c);

/**
 * Loescht eine StatusCondition.
 *
 * # Safety
 * `c` valide.
 */
void zerodds_statuscondition_destroy(struct zerodds_ZeroDdsStatusCondition *c);

/**
 * Erzeugt eine ReadCondition (Spec §2.2.2.5.2.4).
 *
 * # Safety
 * `dr` valide.
 */
struct zerodds_ZeroDdsReadCondition *zerodds_dr_create_readcondition(struct zerodds_ZeroDdsDataReader *dr,
                                                                     uint32_t sample_states,
                                                                     uint32_t view_states,
                                                                     uint32_t instance_states);

/**
 * Erzeugt eine QueryCondition (Spec §2.2.2.5.2.5).
 *
 * # Safety
 * `dr`, `expr` valide; `params[0..param_count]` valide.
 */
struct 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);

/**
 * Loescht eine ReadCondition oder QueryCondition.
 *
 * # Safety
 * `c` valide; muss aus `dr_create_readcondition` oder
 * `dr_create_querycondition` stammen.
 */
int zerodds_dr_delete_readcondition(struct zerodds_ZeroDdsDataReader *_dr, void *c);

/**
 * Erzeugt WaitSet.
 */
struct zerodds_ZeroDdsWaitSet *zerodds_waitset_create(void);

/**
 * Loescht WaitSet.
 *
 * # Safety
 * `w` valide.
 */
void zerodds_waitset_destroy(struct zerodds_ZeroDdsWaitSet *w);

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

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

/**
 * Wartet bis mindestens eine Condition triggert oder Timeout.
 * Schreibt aktive Conditions in `out_active[0..*out_count]`.
 *
 * # Safety
 * `w`, `out_active`, `out_count`, `timeout` valide.
 */
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);

/**
 * Liefert alle attached Conditions.
 *
 * # Safety
 * `w`, `out`, `out_count` valide.
 */
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.
 * Liefert das erste Topic mit gleichem Namen, oder NULL.
 *
 * # Safety
 * `p`, `name` valide.
 */
struct zerodds_ZeroDdsTopic *zerodds_dp_lookup_topicdescription(struct zerodds_ZeroDdsDomainParticipant *p,
                                                                const char *name);

/**
 * `get_builtin_subscriber()` — Spec §2.2.2.2.1.7.
 * Liefert einen Pointer auf einen Wrapper um den DCPS-BuiltinSubscriber.
 * Caller muss `zerodds_builtin_subscriber_destroy` rufen.
 *
 * # Safety
 * `p` valide.
 */
struct zerodds_ZeroDdsBuiltinSubscriber *zerodds_dp_get_builtin_subscriber(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Loescht ein BuiltinSubscriber-Wrapper.
 *
 * # Safety
 * `bs` valide oder NULL.
 */
void zerodds_builtin_subscriber_destroy(struct zerodds_ZeroDdsBuiltinSubscriber *bs);

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

/**
 * Liest die DomainParticipant-QoS in `out` (Spec §2.2.2.2.1.4).
 * `out.user_data.value` muss vom Caller mit ausreichendem Buffer
 * initialisiert sein. Bei zu kleinem Buffer wird die erforderliche
 * Groesse in `out.user_data.value_len` zurueckgeschrieben + `OutOfResources`.
 *
 * # Safety
 * `p`, `out` valide.
 */
int zerodds_dp_get_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                       struct zerodds_ZeroDdsDomainParticipantQos *out);

/**
 * Set-Default-Topic-QoS.
 *
 * # Safety
 * `p` valide; `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` valide.
 */
int zerodds_dp_get_default_topic_qos(struct zerodds_ZeroDdsDomainParticipant *p,
                                     struct zerodds_ZeroDdsTopicQos *out);

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

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

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

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

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

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

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

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

/**
 * Pub copy_from_topic_qos: kopiert die Policies aus TopicQos in
 * die DataWriterQos-`history`/`durability`/`reliability`/etc. Inplace.
 *
 * # Safety
 * Beide Pointer valide.
 */
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` valide.
 */
int zerodds_sub_set_qos(struct zerodds_ZeroDdsSubscriber *sub,
                        const zerodds_ZeroDdsSubscriberQos *qos);

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

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

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

/**
 * Sub copy_from_topic_qos.
 *
 * # Safety
 * Beide Pointer valide.
 */
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` valide.
 */
int zerodds_dw_set_qos(struct zerodds_ZeroDdsDataWriter *dw,
                       const struct zerodds_ZeroDdsDataWriterQos *qos);

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

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

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

/**
 * `register_instance` — Vendor-Variante: caller liefert 16-byte Key-Hash
 * statt generic `T instance_data`. Der Wire-Pfad kennt nur Bytes.
 *
 * # Safety
 * `dw` valide; `key`+`out_handle` valide.
 */
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 ignoriert
 * (gleicher Pfad wie register_instance, dokumentiert in 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` — emittiert UNREGISTERED-Lifecycle.
 *
 * # Safety
 * `dw` valide; `handle` muss aus `register_instance` stammen.
 */
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-Variante: liefert deterministischen
 * Handle aus den ersten 8 Key-Hash-Bytes.
 *
 * # Safety
 * `key[0..16]` valide.
 */
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)` — bei C-FFI nur Vendor-Variante: kopiert
 * 8 Bytes des Handles in `out_buf[0..8]`. Volle Spec-Round-trip
 * (T-Encoded-Key) ist Codegen-Pfad.
 *
 * # Safety
 * `dw` valide; `out_buf[0..*inout_len]` valide.
 */
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` — Liste der `InstanceHandle`s aller
 * matched Remote-Reader (Spec §2.2.2.4.2.x).
 *
 * # Safety
 * `dw` valide; `out_handles[0..cap]` writeable; `out_count` valide.
 */
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.
 * Liefert die `SubscriptionBuiltinTopicData` zu einem matched
 * Reader, gewonnen aus dem BuiltinSubscriber-SEDP-Cache.
 *
 * # Safety
 * `dw` und `out` valide.
 */
int zerodds_dw_get_matched_subscription_data(struct zerodds_ZeroDdsDataWriter *dw,
                                             uint64_t handle,
                                             struct zerodds_ZeroDdsSubscriptionBuiltinTopicData *out);

/**
 * `loan_message` — Zero-Copy-Loan via Heap-Box (Vendor-Variante).
 * Allokiert einen Box<[u8]>, leakt den Pointer; Caller schreibt in
 * den Buffer und ruft `commit_loan` (sendet via write_user_sample)
 * oder `discard_loan` (gibt Buffer frei ohne zu senden).
 *
 * **Vendor-Decision (Spec §2.2.2.4.2 Loan-API + Vendor-Spec
 * `zerodds-flatdata-1.0.md` §4):** Echtes Iceoryx-SHM-Zero-Copy
 * erfordert separate `zerodds-flatdata`-Iceoryx-Backend-Wireup;
 * die hier exponierte Heap-Loan-Variante erfuellt das DDS-Spec-
 * Vertragsbild (Caller schreibt in den Buffer, dann commit/discard)
 * ohne SHM-Optimierung. Die echte SHM-Loan ist transparent ueber den
 * `zerodds-flatdata`-Iceoryx-Backend wenn dieser Aktiv ist.
 *
 * # Safety
 * Alle Pointers valide; `len > 0`.
 */
int zerodds_dw_loan_message(struct zerodds_ZeroDdsDataWriter *dw,
                            uintptr_t len,
                            uint8_t **out_ptr,
                            uintptr_t *out_len);

/**
 * `commit_loan` — schreibt den Loan-Buffer als Sample und gibt den
 * Buffer frei.
 *
 * # Safety
 * `dw`, `ptr` valide; `(ptr, len)` aus `loan_message`.
 */
int zerodds_dw_commit_loan(struct zerodds_ZeroDdsDataWriter *dw, uint8_t *ptr, uintptr_t len);

/**
 * `discard_loan` — gibt den Loan-Buffer frei ohne zu senden.
 *
 * # Safety
 * `dw`, `ptr` valide; `(ptr, len)` aus `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: liefert nur Samples
 * dieser Instance.
 *
 * # Safety
 * `dr`, `out` valide.
 */
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` valide.
 */
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: liefert
 * Samples der naechsten Instance > prev_handle.
 *
 * # Safety
 * `dr`, `out` valide.
 */
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` valide.
 */
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: liefert nur Samples die
 * zur Condition-State-Mask passen (ReadCondition.sample_states/
 * view_states/instance_states).
 *
 * # Safety
 * `dr`, `out` valide; `cond` ist eine ReadCondition oder 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]` valide; `out_handle` valide.
 */
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]` valide.
 */
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 ohne Wait.
 *
 * # Safety
 * `dr` valide.
 */
int zerodds_dr_wait_for_historical_data(struct zerodds_ZeroDdsDataReader *dr,
                                        int32_t _timeout_sec,
                                        uint32_t _timeout_nanosec);

/**
 * `get_matched_publications` — Liste der `InstanceHandle`s aller
 * matched Remote-Writer (Spec §2.2.2.5.x).
 *
 * # Safety
 * `dr` valide; `out_handles[0..cap]` writeable; `out_count` valide.
 */
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.
 * Liefert `PublicationBuiltinTopicData` aus dem BuiltinSubscriber-Cache.
 *
 * # Safety
 * `dr`, `out` valide.
 */
int zerodds_dr_get_matched_publication_data(struct zerodds_ZeroDdsDataReader *dr,
                                            uint64_t handle,
                                            struct zerodds_ZeroDdsPublicationBuiltinTopicData *out);

/**
 * Get-Singleton: liefert den globalen Factory-Pointer. Niemals NULL.
 * Caller darf den Pointer **nicht** freigeben.
 */
const struct zerodds_ZeroDdsDomainParticipantFactory *zerodds_dpf_get_instance(void);

/**
 * Erzeugt einen neuen DomainParticipant.
 *
 * # Safety
 * `f` muss aus `zerodds_dpf_get_instance` stammen oder NULL sein.
 * `qos` darf NULL sein (default).
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_dpf_create_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                                                        uint32_t domain_id,
                                                                        const struct zerodds_ZeroDdsDomainParticipantQos *qos);

/**
 * Loescht einen DomainParticipant.
 *
 * # Safety
 * `f` und `p` muessen valide Handles sein. `p` darf nicht zum
 * Zeitpunkt des Aufrufs noch enthaltene Entities (Topics, Publisher,
 * Subscriber) haben — Caller muss `delete_contained_entities` rufen.
 */
int zerodds_dpf_delete_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                   struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Findet einen aktiven Participant zu der gegebenen Domain-ID. Liefert
 * NULL wenn keiner existiert.
 *
 * # Safety
 * `f` muss valide sein.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_dpf_lookup_participant(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                                                        uint32_t domain_id);

/**
 * Get-Default-Participant-QoS via Pass-Through-Pointer auf einen
 * `Arc<...>`-internen Snapshot. Caller darf den Pointer nur lesen,
 * nicht freigeben (statische Lifetime der Singleton-Factory).
 *
 * In dieser RC1-Surface-Form wird die Default-QoS als opaker
 * `Arc<DomainParticipantQos>` geliefert — die volle Field-getter/setter
 * kommt mit den `qos.rs`-Strukturen in Folge-Pass.
 *
 * # Safety
 * `f` valide.
 */
int zerodds_dpf_set_default_participant_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                            const struct zerodds_ZeroDdsDomainParticipantQos *qos);

/**
 * Gibt eine Kopie der aktuellen Default-Participant-QoS in `out` zurueck.
 * Solange die `zerodds_DomainParticipantQos`-Struktur nicht in der
 * `qos.rs`-Schicht definiert ist, ist `out` ein opaker `void*`.
 *
 * # Safety
 * `f` valide; `out` darf NULL sein (no-op).
 */
int zerodds_dpf_get_default_participant_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                                            struct zerodds_ZeroDdsDomainParticipantQos *out);

/**
 * Factory-eigene QoS setzen (Spec §2.2.2.2.2.6).
 *
 * # Safety
 * `f` valide; `qos` darf NULL sein (Reset).
 */
int zerodds_dpf_set_qos(const struct zerodds_ZeroDdsDomainParticipantFactory *f,
                        const struct zerodds_ZeroDdsDomainParticipantFactoryQos *qos);

/**
 * Factory-eigene QoS lesen.
 *
 * # Safety
 * `f`, `out` valide.
 */
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);

/**
 * Pollt alle registrierten Listener und feuert Callbacks bei Status-
 * Counter-Delta. Return-Wert: Anzahl gefeuerter Callbacks.
 *
 * # Safety
 * Caller muss garantieren dass alle in der Registry registrierten Entity-
 * Pointer und Listener-Pointer noch valide sind (nicht ueber `*_destroy`
 * freigegeben, ohne `set_listener(NULL)` davor).
 */
uintptr_t zerodds_poll_listeners(void);

/**
 * Erzeugt ein Topic. Liefert NULL bei NULL-Argumenten oder Topic-Name-
 * Konflikt mit anderem Type.
 *
 * # Safety
 * `p`, `name`, `type_name` muessen valide sein. `qos` darf NULL sein
 * (Default aus `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);

/**
 * Loescht ein Topic.
 *
 * # Safety
 * `p` und `t` muessen valide Handles sein und zueinander gehoeren.
 */
int zerodds_dp_delete_topic(struct zerodds_ZeroDdsDomainParticipant *p,
                            struct zerodds_ZeroDdsTopic *t);

/**
 * Findet ein bereits angelegtes Topic via Name. Liefert NULL wenn keins.
 *
 * # Safety
 * `p`, `name` valide.
 */
struct zerodds_ZeroDdsTopic *zerodds_dp_find_topic(struct zerodds_ZeroDdsDomainParticipant *p,
                                                   const char *name);

/**
 * Erzeugt einen Publisher.
 *
 * # Safety
 * `p` valide; `qos` darf NULL sein.
 */
struct zerodds_ZeroDdsPublisher *zerodds_dp_create_publisher(struct zerodds_ZeroDdsDomainParticipant *p,
                                                             const struct zerodds_ZeroDdsPublisherQos *qos);

/**
 * Loescht einen Publisher.
 *
 * # Safety
 * Beide Handles valide; Publisher darf keine DataWriter mehr enthalten.
 */
int zerodds_dp_delete_publisher(struct zerodds_ZeroDdsDomainParticipant *p,
                                struct zerodds_ZeroDdsPublisher *pubh);

/**
 * Erzeugt einen Subscriber.
 *
 * # Safety
 * `p` valide; `qos` darf NULL sein.
 */
struct zerodds_ZeroDdsSubscriber *zerodds_dp_create_subscriber(struct zerodds_ZeroDdsDomainParticipant *p,
                                                               const zerodds_ZeroDdsSubscriberQos *qos);

/**
 * Loescht einen Subscriber.
 *
 * # Safety
 * Beide Handles valide; Subscriber darf keine DataReader mehr halten.
 */
int zerodds_dp_delete_subscriber(struct zerodds_ZeroDdsDomainParticipant *p,
                                 struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Erzeugt ein ContentFilteredTopic.
 *
 * # Safety
 * `p`, `name`, `related`, `filter_expression` valide.
 */
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);

/**
 * Loescht ein ContentFilteredTopic.
 *
 * # Safety
 * Beide Handles valide.
 */
int zerodds_dp_delete_contentfilteredtopic(struct zerodds_ZeroDdsDomainParticipant *p,
                                           struct zerodds_ZeroDdsContentFilteredTopic *cft);

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

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

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

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

/**
 * Domain-ID des Participant.
 *
 * # Safety
 * `p` valide.
 */
uint32_t zerodds_dp_get_domain_id(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Liveliness fuer alle vom Participant gehaltenen MANUAL_BY_PARTICIPANT-
 * Writers asserten.
 *
 * # Safety
 * `p` valide.
 */
int zerodds_dp_assert_liveliness(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Loescht alle vom Participant gehaltenen Topics, Publisher, Subscriber
 * rekursiv (Spec §2.2.2.2.1.10).
 *
 * # Safety
 * `p` valide.
 */
int zerodds_dp_delete_contained_entities(struct zerodds_ZeroDdsDomainParticipant *p);

/**
 * Prueft ob ein InstanceHandle zu einer Entity in diesem Participant
 * gehoert (Spec §2.2.2.2.1.11).
 *
 * # Safety
 * `p` valide.
 */
int zerodds_dp_contains_entity(struct zerodds_ZeroDdsDomainParticipant *p, uint64_t handle);

/**
 * Liefert die InstanceHandles aller entdeckten Remote-Participants.
 * `out_handles[0..*out_count]` werden geschrieben, max `cap`.
 *
 * # Safety
 * `p`, `out_handles`, `out_count` valide; `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);

/**
 * Liefert den Owning-Participant.
 *
 * # Safety
 * `pub_` valide.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_pub_get_participant(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * Suspend publications (Spec §2.2.2.4.1.10). Setzt Flag — der
 * Hot-Path queued Writes statt sie zu senden, bis `resume_publications`.
 *
 * # Safety
 * `pub_` valide.
 */
int zerodds_pub_suspend_publications(struct zerodds_ZeroDdsPublisher *pub_);

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

/**
 * begin_coherent_changes (Spec §2.2.2.4.1.12). Im RC1 ein No-Bracket-
 * Marker — spec-konformer Tracker auf Pub-Ebene; CoherentSet-
 * Ergebnis-Wire-Frames lebt auf Writer-Ebene und greift unabhaengig.
 *
 * # Safety
 * `pub_` valide.
 */
int zerodds_pub_begin_coherent_changes(struct zerodds_ZeroDdsPublisher *pub_);

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

/**
 * wait_for_acknowledgments(timeout_ms) — wartet bis alle DWs akkied
 * sind oder Timeout schlaegt.
 *
 * # Safety
 * `pub_` valide.
 */
int zerodds_pub_wait_for_acknowledgments(struct zerodds_ZeroDdsPublisher *pub_,
                                         uint64_t timeout_ms);

/**
 * Erzeugt einen DataWriter ueber das Topic.
 *
 * # Safety
 * `pub_`, `topic` valide; `qos` darf NULL sein (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);

/**
 * Loescht einen DataWriter.
 *
 * # Safety
 * `pub_`, `dw` valide und zugehoerig.
 */
int zerodds_pub_delete_datawriter(struct zerodds_ZeroDdsPublisher *pub_,
                                  struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Liefert den DataWriter zu einem Topic-Namen, oder NULL.
 *
 * # Safety
 * `pub_`, `topic_name` valide.
 */
struct zerodds_ZeroDdsDataWriter *zerodds_pub_lookup_datawriter(struct zerodds_ZeroDdsPublisher *pub_,
                                                                const char *topic_name);

/**
 * Loescht alle vom Publisher gehaltenen DataWriter.
 *
 * # Safety
 * `pub_` valide.
 */
int zerodds_pub_delete_contained_entities(struct zerodds_ZeroDdsPublisher *pub_);

/**
 * Liefert das Topic.
 *
 * # Safety
 * `dw` valide.
 */
struct zerodds_ZeroDdsTopic *zerodds_dw_get_topic(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Liefert den Publisher.
 *
 * # Safety
 * `dw` valide.
 */
struct zerodds_ZeroDdsPublisher *zerodds_dw_get_publisher(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Schreibt einen vorgefertigten CDR-Payload (Caller serialisiert via
 * idl-Codegen oder DynamicData). Das Encap-Header-Prefix wird vom
 * Runtime hinzugefuegt.
 *
 * # Safety
 * `dw`, `payload[0..len]` valide. `handle` ist Spec-Pflicht-Param der
 * die Instance kennzeichnet — `0` = HANDLE_NIL = "Writer rechnet aus".
 */
int zerodds_dw_write(struct zerodds_ZeroDdsDataWriter *dw,
                     const uint8_t *payload,
                     uintptr_t len,
                     uint64_t _handle);

/**
 * Schreibt mit Source-Timestamp. RC1-Surface: leitet auf `write` durch
 * — Source-Timestamp landet in der zukuenftigen Inline-QoS-Implementation.
 *
 * # Safety
 * Wie `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: emittiert ein DISPOSED-Lifecycle-Marker fuer die Instance.
 *
 * # Safety
 * `dw` valide; `key_hash[0..16]` lesbar. `handle` informational.
 */
int zerodds_dw_dispose(struct zerodds_ZeroDdsDataWriter *dw,
                       const uint8_t *key_hash,
                       uint64_t _handle);

/**
 * Wartet bis alle aktuell ausstehenden Writes ackd sind oder Timeout.
 *
 * # Safety
 * `dw` valide.
 */
int zerodds_dw_wait_for_acknowledgments(struct zerodds_ZeroDdsDataWriter *dw, uint64_t timeout_ms);

/**
 * Liveliness fuer diesen Writer manuell asserten.
 *
 * # Safety
 * `dw` valide.
 */
int zerodds_dw_assert_liveliness(struct zerodds_ZeroDdsDataWriter *dw);

/**
 * Wartet bis mindestens `min` matched Subscriptions vorhanden sind oder Timeout.
 *
 * # Safety
 * `dw` valide.
 */
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` und `out` valide.
 */
int zerodds_dw_get_liveliness_lost_status(struct zerodds_ZeroDdsDataWriter *dw,
                                          struct zerodds_ZeroDdsLivelinessLostStatus *out);

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

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

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

/**
 * Liefert den Owning-Participant.
 *
 * # Safety
 * `sub` valide.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_sub_get_participant(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * `begin_access` (Spec §2.2.2.5.1.13). RC1: No-op-Marker fuer
 * Coherent-Sets — die echten Set-Boundaries liegen am Reader-Wire-Pfad.
 *
 * # Safety
 * `sub` valide.
 */
int zerodds_sub_begin_access(struct zerodds_ZeroDdsSubscriber *sub);

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

/**
 * Liefert die Liste aktiver DataReader.
 *
 * # Safety
 * `sub`, `out`, `out_count` valide.
 */
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 — Listener-Bubble-Up
 * laeuft per-Reader, der Subscriber-Aggregator wird in WP "Listeners-FFI" wired.
 *
 * # Safety
 * `sub` valide.
 */
int zerodds_sub_notify_datareaders(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Erzeugt einen DataReader.
 *
 * # Safety
 * `sub`, `topic` valide; `qos` darf NULL sein.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_create_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                                                struct zerodds_ZeroDdsTopic *topic,
                                                                const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * Erzeugt einen DataReader auf einem ContentFilteredTopic.
 * Bei jedem `take`/`read` wird die Filter-Expression evaluiert
 * (Spec §2.2.2.3.3 + §2.2.2.5.2.5).
 *
 * # Safety
 * `sub`, `cft` valide; `qos` darf NULL sein.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_create_datareader_with_cft(struct zerodds_ZeroDdsSubscriber *sub,
                                                                         struct zerodds_ZeroDdsContentFilteredTopic *cft,
                                                                         const struct zerodds_ZeroDdsDataReaderQos *qos);

/**
 * Loescht einen DataReader.
 *
 * # Safety
 * `sub`, `dr` valide und zugehoerig.
 */
int zerodds_sub_delete_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                  struct zerodds_ZeroDdsDataReader *dr);

/**
 * Lookup-DataReader by Topic-Name.
 *
 * # Safety
 * `sub`, `topic_name` valide.
 */
struct zerodds_ZeroDdsDataReader *zerodds_sub_lookup_datareader(struct zerodds_ZeroDdsSubscriber *sub,
                                                                const char *topic_name);

/**
 * Loescht alle vom Subscriber gehaltenen DataReader.
 *
 * # Safety
 * `sub` valide.
 */
int zerodds_sub_delete_contained_entities(struct zerodds_ZeroDdsSubscriber *sub);

/**
 * Liefert das TopicDescription-Handle (im RC1: Topic-Pointer).
 *
 * # Safety
 * `dr` valide.
 */
struct zerodds_ZeroDdsTopic *zerodds_dr_get_topicdescription(struct zerodds_ZeroDdsDataReader *dr);

/**
 * Liefert den Subscriber.
 *
 * # Safety
 * `dr` valide.
 */
struct zerodds_ZeroDdsSubscriber *zerodds_dr_get_subscriber(struct zerodds_ZeroDdsDataReader *dr);

/**
 * Take: konsumiert Samples aus Cache + Channel (Spec §2.2.2.5.3).
 * Geht durch read_cache (Sample-State READ + NOT_READ) und Channel
 * (Sample-State NOT_READ), entfernt alle gelieferten Samples.
 *
 * # Safety
 * `dr`, `out` valide.
 */
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 Variante von Take (Spec §2.2.2.5.3).
 * Liefert Samples aus Cache + Channel, aber ALLE bleiben anschliessend
 * im Read-Cache mit Sample-State = READ.
 *
 * # Safety
 * `dr`, `out` valide.
 */
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` valide.
 */
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. Identisch zu take_next_sample im RC1.
 *
 * # Safety
 * Wie `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);

/**
 * Gibt geliehene Sample-Buffer zurueck.
 *
 * # Safety
 * `arr` muss aus einem vorherigen `zerodds_dr_take`/`read` stammen,
 * `loan_token` muss noch gueltig sein.
 */
int zerodds_dr_return_loan(struct zerodds_ZeroDdsDataReader *_dr,
                           struct zerodds_ZeroDdsSampleArray *arr);

/**
 * Wartet bis `min` matched Publications oder Timeout.
 *
 * # Safety
 * `dr` valide.
 */
int zerodds_dr_wait_for_matched(struct zerodds_ZeroDdsDataReader *dr,
                                int32_t min,
                                uint64_t timeout_ms);

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

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

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

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

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

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

/**
 * Liefert den Topic-Namen als heap-allokierten C-String. Caller muss
 * `zerodds_string_free` rufen.
 *
 * # Safety
 * `t` valide.
 */
char *zerodds_topic_get_name(struct zerodds_ZeroDdsTopic *t);

/**
 * Liefert den Topic-Type-Namen. Caller muss `zerodds_string_free` rufen.
 *
 * # Safety
 * `t` valide.
 */
char *zerodds_topic_get_type_name(struct zerodds_ZeroDdsTopic *t);

/**
 * Liefert den Owning-Participant.
 *
 * # Safety
 * `t` valide.
 */
struct zerodds_ZeroDdsDomainParticipant *zerodds_topic_get_participant(struct zerodds_ZeroDdsTopic *t);

/**
 * Gibt einen vorher von `zerodds_topic_get_*` allokierten C-String frei.
 *
 * # Safety
 * `s` muss aus einer `zerodds_*_get_*`-Funktion stammen, die einen
 * `*mut c_char` per `CString::into_raw` produziert.
 */
void zerodds_string_free(char *s);

/**
 * Get-QoS in `out` (Spec §2.2.2.3.2.x).
 * `out` ist `*mut ZeroDdsTopicQos` mit Caller-supplied Buffer fuer
 * `topic_data.value` (variable Laenge).
 *
 * # Safety
 * `t`, `out` valide.
 */
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` valide.
 */
int zerodds_topic_set_qos(struct zerodds_ZeroDdsTopic *t,
                          const struct zerodds_ZeroDdsTopicQos *qos);

/**
 * Liefert den InconsistentTopicStatus.
 *
 * # Safety
 * `t` und `out` valide.
 */
int zerodds_topic_get_inconsistent_topic_status(struct zerodds_ZeroDdsTopic *t,
                                                struct zerodds_ZeroDdsInconsistentTopicStatus *out);

/**
 * Erzeugt ein typisiertes Topic-Handle. Speichert die TypeSupport-
 * Tabelle so dass Writer/Reader-Operationen darauf zugreifen koennen.
 *
 * `out_topic` muss non-NULL sein und wird auf den neu allokierten
 * Topic-Handle gesetzt. Caller MUSS spaeter
 * `zerodds_topic_destroy_typed` aufrufen.
 *
 * # Safety
 * `participant`/`topic_name`/`type_support`/`out_topic` muessen valide
 * Pointer sein. `topic_name` muss NUL-terminiert sein. `type_support`
 * MUSS auf eine statische Tabelle mit lebenden Function-Pointern zeigen.
 */
int zerodds_topic_create_typed(struct zerodds_ZeroDdsRuntime *participant,
                               const char *topic_name,
                               const struct zerodds_ZeroDdsTypeSupport *type_support,
                               struct zerodds_ZeroDdsTopic **out_topic);

/**
 * Zerstoert ein Topic-Handle. NULL-safe.
 *
 * # Safety
 * `topic` muss aus `zerodds_topic_create_typed` stammen oder NULL sein.
 */
void zerodds_topic_destroy_typed(struct zerodds_ZeroDdsTopic *topic);

/**
 * Standalone-Encoder. Ruft `ts.encode(sample, out_buf, out_cap, out_len)`
 * und reicht den Return-Code durch.
 *
 * `out_buf=NULL` mit `out_cap=0` ist Size-Probe: der Codegen-Encoder
 * MUSS `out_len` auf die benoetigte Groesse setzen und
 * `BUFFER_TOO_SMALL` zurueckgeben.
 *
 * # Safety
 * `ts`, `sample`, `out_len` muessen valide Pointer sein. `out_buf` darf
 * NULL sein wenn `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. Ruft `ts.decode(buf, len, out_sample)`.
 *
 * # Safety
 * `ts`/`buf`/`out_sample` valid; `buf` muss `len` Bytes lesbar sein;
 * `out_sample` muss zero-initialized auf den Sprach-Type zeigen.
 */
int zerodds_xcdr2_decode(const struct zerodds_ZeroDdsTypeSupport *ts,
                         const uint8_t *buf,
                         uintptr_t len,
                         void *out_sample);

/**
 * Schreibt einen typisierten Sample. Encodiert via
 * `ts.encode` in einen internen Heap-Buffer und leitet die Bytes an
 * `zerodds_writer_write` weiter.
 *
 * Strategie:
 * 1. Size-Probe (`out_buf=NULL`).
 * 2. Heap-Buffer der probed Groesse allokieren.
 * 3. Echtes Encode rein.
 * 4. `zerodds_writer_write(writer, bytes, len)`.
 *
 * # Safety
 * `writer`/`ts`/`sample` valid; vgl. `zerodds_writer_write` und
 * `zerodds_xcdr2_encode`.
 */
int zerodds_writer_write_typed(struct zerodds_ZeroDdsWriter *writer,
                               const struct zerodds_ZeroDdsTypeSupport *ts,
                               const void *sample);

/**
 * Liest einen typisierten Sample. Holt Bytes via `zerodds_reader_take`
 * und decodiert sie via `ts.decode` in `out_sample`.
 *
 * `out_info` ist aktuell unbenutzt (Reserved fuer Sample-Info-Spec-
 * Rollout); MUSS NULL sein oder zeigt auf einen Caller-allokierten
 * `zerodds_sample_info_t` der mit Default-Werten befuellt wird.
 *
 * Liefert:
 * - 0 (Ok) wenn ein Sample erfolgreich decoded wurde.
 * - `NoData` (-7) wenn der Reader leer ist.
 * - andere negative Codes bei Decoder-Fehler.
 *
 * # Safety
 * `reader`/`ts`/`out_sample` valide. `out_info` NULL oder valide.
 */
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 */