xtc/include/xtc/xtc_backend.h

#ifndef XTC_BACKEND_H
#define XTC_BACKEND_H
#include "xtc_engine.h"
#ifdef __cplusplus
extern "C" {
#endif

typedef struct xtc_backend xtc_backend;
typedef enum { XTC_BACKEND_JACK = 1 } xtc_backend_kind;
typedef struct {
    xtc_backend_kind kind;
    const char *client_name; /* Borrowed for open only; nonempty. */
    size_t max_frames;       /* 1..65536, at least the server's current block. */
    size_t channel_count;    /* Currently must be 1. */
} xtc_backend_config;
typedef struct {
    unsigned int sample_rate;
    unsigned int buffer_frames;
    unsigned int xruns; /* Wraps modulo UINT_MAX + 1. */
    unsigned int processed_blocks;
    uint64_t sample_position; /* Successful callback frames; retained across stop/submit. */
    unsigned int submitted_revision, active_revision;
    int running;
    int server_lost;
    int sample_rate_changed; /* Sticky: close/reopen and resubmit to recover. */
    xtc_result process_result;
} xtc_backend_status;

/* All operations are serialized on one control thread. Public API contains
 * no JACK types. JACK is optional at build time (otherwise UNSUPPORTED).
 * Opens without starting a server, changing devices, or connecting ports.
 * Returns IO if server/client setup fails. On failure *out_backend is NULL,
 * except if cleanup itself fails: a non-NULL handle must be closed/retried;
 * only close is permitted on that partially initialized handle. */
xtc_result xtc_backend_open(const xtc_backend_config *config, xtc_backend **out_backend);
/* Stop/close establish callback quiescence before state can be destroyed.
 * On failure the handle remains owned by caller; retry close. NULL close OK. */
xtc_result xtc_backend_close(xtc_backend *backend);
xtc_result xtc_backend_start(xtc_backend *backend);
xtc_result xtc_backend_stop(xtc_backend *backend);
/* Stopped only; changes transport clock, not oscillator phase. */
xtc_result xtc_backend_seek(xtc_backend *backend, uint64_t sample);
/* Copies graph. While running, capacity means pending slot busy.
 * While stopped, transactionally replaces all retained plans (counters/revisions
 * restart); failed compilation leaves the previous engine intact. */
xtc_result xtc_backend_submit(xtc_backend *backend, const xtc_graph *graph);
void xtc_backend_collect(xtc_backend *backend);
/* Snapshot fields are individually coherent, not a transactional snapshot. */
xtc_result xtc_backend_get_status(const xtc_backend *backend, xtc_backend_status *out_status);
/* Borrowed names valid until close. Direction is the client's own port. */
xtc_result xtc_backend_port_name(const xtc_backend *backend, xtc_port_direction direction,
                                const char **out_name);
/* Enumerates available mono audio ports (devices and software routes). Visitor
 * receives a borrowed name valid only during call; return nonzero to stop.
 * Control-thread only. JACK NULL list means no matching ports. */
typedef int (*xtc_backend_port_visitor)(const char *name, void *context);
xtc_result xtc_backend_visit_ports(xtc_backend *backend, xtc_port_direction direction,
                                  xtc_backend_port_visitor visitor, void *context);
/* Connect/disconnect this client's port with a remote opposite-direction port.
 * own_direction INPUT receives remote output; OUTPUT sends to remote input.
 * Explicit user choice only; no automatic physical routing. */
xtc_result xtc_backend_connect(xtc_backend *backend, xtc_port_direction own_direction,
                              const char *remote_name);
xtc_result xtc_backend_disconnect(xtc_backend *backend, xtc_port_direction own_direction,
                                 const char *remote_name);
#ifdef __cplusplus
}
#endif
#endif