File astutedds.h

File List > astutedds > c > astutedds.h

Go to the documentation of this file

//
// Copyright (c) 2026, Astute Systems PTY LTD
//
// This file is part of the Astute DDS developed by Astute Systems.
//
// See the commercial LICENSE file in the project root for full license details.
//
// @file astutedds.h
// @brief AstuteDDS C API — opaque-handle interface for FFI consumers.
//
// All DDS entities are exposed as opaque pointers.  The caller must never
// dereference them directly.  Lifetime rules mirror the DDS specification:
//
//   DomainParticipant  owns  Topic | Publisher | Subscriber
//   Publisher          owns  DataWriter
//   Subscriber         owns  DataReader
//
// Every create_* call must be matched by the corresponding delete_* call.
// Deleting a parent before its children is undefined behaviour.
//
#ifndef ASTUTEDDS_C_ASTUTEDDS_H
#define ASTUTEDDS_C_ASTUTEDDS_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

// ── Opaque handle types ───────────────────────────────────────────────────────

typedef struct AstuteDDS_Participant_s  *AstuteDDS_Participant;
typedef struct AstuteDDS_Topic_s        *AstuteDDS_Topic;
typedef struct AstuteDDS_Publisher_s    *AstuteDDS_Publisher;
typedef struct AstuteDDS_Subscriber_s   *AstuteDDS_Subscriber;
typedef struct AstuteDDS_DataWriter_s   *AstuteDDS_DataWriter;
typedef struct AstuteDDS_DataReader_s   *AstuteDDS_DataReader;

// ── Return codes ──────────────────────────────────────────────────────────────

typedef enum
{
    ASTUTEDDS_OK              = 0,
    ASTUTEDDS_ERROR           = 1,
    ASTUTEDDS_UNSUPPORTED     = 2,
    ASTUTEDDS_BAD_PARAM       = 3,
    ASTUTEDDS_PRECONDITION    = 4,
    ASTUTEDDS_OUT_OF_RESOURCES = 5,
    ASTUTEDDS_NOT_ENABLED     = 6,
    ASTUTEDDS_TIMEOUT         = 10,
    ASTUTEDDS_NO_DATA         = 11,
} AstuteDDS_ReturnCode;

// ── Reliability / History kind enums ─────────────────────────────────────────

typedef enum { ASTUTEDDS_BEST_EFFORT = 0, ASTUTEDDS_RELIABLE = 1 } AstuteDDS_Reliability;
typedef enum { ASTUTEDDS_KEEP_LAST = 0, ASTUTEDDS_KEEP_ALL = 1 } AstuteDDS_HistoryKind;
typedef enum { ASTUTEDDS_VOLATILE = 0, ASTUTEDDS_TRANSIENT_LOCAL = 1 } AstuteDDS_Durability;

// ── QoS structs ───────────────────────────────────────────────────────────────

typedef struct
{
    AstuteDDS_Reliability reliability;
    AstuteDDS_HistoryKind history_kind;
    int32_t               history_depth;
    AstuteDDS_Durability  durability;
} AstuteDDS_DataWriterQos;

typedef struct
{
    AstuteDDS_Reliability reliability;
    AstuteDDS_HistoryKind history_kind;
    int32_t               history_depth;
    AstuteDDS_Durability  durability;
} AstuteDDS_DataReaderQos;

// ── Sample received by DataReader ─────────────────────────────────────────────

typedef struct
{
    const uint8_t *data;    
    size_t         length;
    int            valid;   
} AstuteDDS_Sample;

// ── Default QoS helpers ───────────────────────────────────────────────────────

static inline AstuteDDS_DataWriterQos astutedds_default_datawriter_qos(void)
{
    AstuteDDS_DataWriterQos q;
    q.reliability  = ASTUTEDDS_RELIABLE;
    q.history_kind = ASTUTEDDS_KEEP_LAST;
    q.history_depth = 1;
    q.durability   = ASTUTEDDS_VOLATILE;
    return q;
}

static inline AstuteDDS_DataReaderQos astutedds_default_datareader_qos(void)
{
    AstuteDDS_DataReaderQos q;
    q.reliability  = ASTUTEDDS_RELIABLE;
    q.history_kind = ASTUTEDDS_KEEP_LAST;
    q.history_depth = 1;
    q.durability   = ASTUTEDDS_VOLATILE;
    return q;
}

// ── DomainParticipant ─────────────────────────────────────────────────────────

AstuteDDS_Participant astutedds_create_participant(uint32_t domain_id);

void astutedds_delete_participant(AstuteDDS_Participant p);

// ── Topic ────────────────────────────────────────────────────────────────────

AstuteDDS_Topic astutedds_create_topic(
    AstuteDDS_Participant p,
    const char           *topic_name,
    const char           *type_name);

void astutedds_delete_topic(AstuteDDS_Participant p, AstuteDDS_Topic t);

const char *astutedds_topic_name(AstuteDDS_Topic t);
const char *astutedds_topic_type_name(AstuteDDS_Topic t);

// ── Publisher ─────────────────────────────────────────────────────────────────

AstuteDDS_Publisher astutedds_create_publisher(AstuteDDS_Participant p);
void                astutedds_delete_publisher(AstuteDDS_Participant p, AstuteDDS_Publisher pub);

// ── DataWriter ────────────────────────────────────────────────────────────────

AstuteDDS_DataWriter astutedds_create_datawriter(
    AstuteDDS_Publisher         pub,
    AstuteDDS_Topic             topic,
    const AstuteDDS_DataWriterQos *qos);  
void astutedds_delete_datawriter(AstuteDDS_Publisher pub, AstuteDDS_DataWriter w);

AstuteDDS_ReturnCode astutedds_write(
    AstuteDDS_DataWriter w,
    const uint8_t        *data,
    size_t                len);

// ── Subscriber ───────────────────────────────────────────────────────────────

AstuteDDS_Subscriber astutedds_create_subscriber(AstuteDDS_Participant p);
void                 astutedds_delete_subscriber(AstuteDDS_Participant p, AstuteDDS_Subscriber sub);

// ── DataReader ────────────────────────────────────────────────────────────────

AstuteDDS_DataReader astutedds_create_datareader(
    AstuteDDS_Subscriber          sub,
    AstuteDDS_Topic               topic,
    const AstuteDDS_DataReaderQos *qos);  
void astutedds_delete_datareader(AstuteDDS_Subscriber sub, AstuteDDS_DataReader r);

AstuteDDS_ReturnCode astutedds_take_next(AstuteDDS_DataReader r, AstuteDDS_Sample *out);

size_t astutedds_unread_count(AstuteDDS_DataReader r);

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

#endif  // ASTUTEDDS_C_ASTUTEDDS_H