react-native-queue-player 1.0.0

package/android/src/main/cpp/airplay2_rtsp.h

@@ -0,0 +1,90 @@
+/**
+ * Blocking RTSP client for AirPlay 2.
+ *
+ * Simple TCP-based RTSP/1.0 client with CSeq auto-increment.
+ * Supports plaintext and encrypted (ChaCha20-Poly1305) control
+ * channel modes.  All I/O is blocking — runs on a background thread.
+ */
+#ifndef AIRPLAY2_RTSP_H
+#define AIRPLAY2_RTSP_H
+
+#include "airplay2_session.h"
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Response from an RTSP request. */
+typedef struct {
+    int status;             /* HTTP-style status code (200, 401, etc.) */
+    char *content_type;     /* Content-Type header value (heap, may be NULL) */
+    uint8_t *body;          /* Response body (heap, may be NULL) */
+    size_t body_len;        /* Response body length */
+} ap2_rtsp_response_t;
+
+/**
+ * Connect the RTSP TCP socket to the receiver.
+ * Sets session->rtsp_fd on success.
+ * @return 0 on success, -1 on failure
+ */
+int ap2_rtsp_connect(ap2_session_t *session);
+
+/**
+ * Send an RTSP request with optional extra headers and read the response.
+ * Auto-increments session->cseq.  If session->encrypted is set,
+ * the request/response are wrapped in ChaCha20-Poly1305 frames.
+ *
+ * @param session       Session with connected rtsp_fd
+ * @param method        RTSP method ("GET", "POST", "SETUP", etc.)
+ * @param path          Request path ("/info", "/pair-setup", etc.)
+ * @param ct            Content-Type for request body (NULL if no body)
+ * @param body          Request body bytes (NULL if no body)
+ * @param body_len      Request body length
+ * @param extra_headers NULL or "Header: value\r\n..." string appended before \r\n
+ * @param resp          OUT: response struct (caller must call ap2_rtsp_response_free)
+ * @return 0 on success, -1 on network/parse error
+ */
+int ap2_rtsp_request_ex(ap2_session_t *session,
+                        const char *method, const char *path,
+                        const char *ct, const uint8_t *body, size_t body_len,
+                        const char *extra_headers,
+                        ap2_rtsp_response_t *resp);
+
+/**
+ * Convenience wrapper — calls ap2_rtsp_request_ex with extra_headers=NULL.
+ */
+int ap2_rtsp_request(ap2_session_t *session,
+                     const char *method, const char *path,
+                     const char *ct, const uint8_t *body, size_t body_len,
+                     ap2_rtsp_response_t *resp);
+
+/**
+ * Like ap2_rtsp_request but overrides the RTSP socket receive timeout
+ * for this call only. Used by paths that must not hang the calling
+ * thread when the receiver is unreachable (e.g. /feedback keep-alive).
+ *
+ * @param timeout_sec socket receive timeout in seconds (0 = leave alone)
+ */
+int ap2_rtsp_request_tmo(ap2_session_t *session,
+                         const char *method, const char *path,
+                         const char *ct, const uint8_t *body, size_t body_len,
+                         int timeout_sec,
+                         ap2_rtsp_response_t *resp);
+
+/**
+ * Free response fields (content_type, body).
+ */
+void ap2_rtsp_response_free(ap2_rtsp_response_t *resp);
+
+/**
+ * Close the RTSP connection.
+ */
+void ap2_rtsp_close(ap2_session_t *session);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* AIRPLAY2_RTSP_H */

package/android/src/main/cpp/airplay2_session.c

@@ -0,0 +1,196 @@
+/**
+ * AirPlay 2 session lifecycle — create / destroy.
+ */
+
+#include "airplay2_session.h"
+#include "airplay2_filelog.h"
+
+/* File-logging globals — single definition, declared extern in airplay2_filelog.h. */
+FILE *g_ap2_logfile = NULL;
+pthread_mutex_t g_ap2_logfile_mutex = PTHREAD_MUTEX_INITIALIZER;
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <time.h>
+#include <sodium.h>
+
+/* Generate a random UUID v4. */
+static void make_uuid(char out[37]) {
+    uint8_t b[16];
+    /* Simple PRNG seed — good enough for session IDs. */
+    for (int i = 0; i < 16; i++) b[i] = (uint8_t)(rand() & 0xff);
+    b[6] = (b[6] & 0x0f) | 0x40;  /* version 4 */
+    b[8] = (b[8] & 0x3f) | 0x80;  /* variant 1 */
+    snprintf(out, 37,
+        "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x",
+        b[0],b[1],b[2],b[3], b[4],b[5], b[6],b[7],
+        b[8],b[9], b[10],b[11],b[12],b[13],b[14],b[15]);
+}
+
+ap2_session_t *ap2_session_create(const char *host, int port,
+                                  int sample_rate, int sample_size,
+                                  int channels, float volume) {
+    /* Idempotent — safe to call multiple times.  Must happen before any
+     * libsodium crypto (Ed25519, X25519, randombytes_buf). */
+    if (sodium_init() < -1) return NULL;
+
+    ap2_session_t *s = (ap2_session_t *)calloc(1, sizeof(*s));
+    if (!s) return NULL;
+
+    /* Seed PRNG once per session — ensures random RTP fields, UUIDs, etc.
+     * XOR with pointer address for extra entropy between sessions. */
+    srand((unsigned)(time(NULL) ^ (uintptr_t)s));
+
+    /* Network — all sockets invalid until connect. */
+    s->rtsp_fd       = -1;
+    s->data_fd       = -1;
+    s->control_fd    = -1;
+    s->event_fd      = -1;
+    s->ptp_event_fd  = -1;
+    s->ptp_general_fd = -1;
+    s->timing_fd     = -1;
+
+    if (host) {
+        strncpy(s->host, host, sizeof(s->host) - 1);
+    }
+    s->rtsp_port = port;
+
+    /* State machine. */
+    s->state = AP2_STATE_INIT;
+    pthread_mutex_init(&s->mutex, NULL);
+
+    /* Audio format. */
+    s->sample_rate = sample_rate > 0 ? sample_rate : AP2_DEFAULT_SAMPLE_RATE;
+    s->sample_size = sample_size > 0 ? sample_size : AP2_DEFAULT_SAMPLE_SIZE;
+    s->channels    = channels > 0    ? channels    : AP2_DEFAULT_CHANNELS;
+    s->spf         = AP2_DEFAULT_SPF;
+    s->volume      = volume;
+
+    /* Ring buffer. */
+    int chunk_bytes = AP2_CHUNK_BYTES(s);
+    s->ring_size = chunk_bytes * AP2_DEFAULT_RING_CHUNKS;
+    s->ring = (uint8_t *)calloc(1, s->ring_size);
+    if (!s->ring) {
+        pthread_mutex_destroy(&s->mutex);
+        free(s);
+        return NULL;
+    }
+    pthread_mutex_init(&s->ring_mutex, NULL);
+
+    /* DACP-ID / Client-Instance — 16-char uppercase hex.
+     * Active-Remote — 32-bit decimal. Per OwnTone airplay.c:919-926. */
+    {
+        uint8_t id_bytes[8];
+        randombytes_buf(id_bytes, sizeof(id_bytes));
+        for (int i = 0; i < 8; i++)
+            snprintf(s->dacp_id + i * 2, 3, "%02X", id_bytes[i]);
+        uint32_t ar;
+        randombytes_buf(&ar, sizeof(ar));
+        s->active_remote = ar ? ar : 1;
+    }
+
+    /* Session UUID. */
+    make_uuid(s->session_uuid);
+
+    /* Random SSRC. */
+    s->ssrc = (uint32_t)rand();
+
+    /* Random initial RTP timestamp and sequence number (per OwnTone).
+     * Avoids wrap-around in the first RTCP sync packet. */
+    s->rtp_timestamp = (uint32_t)rand();
+    s->rtp_seq = (uint16_t)(rand() & 0xFFFF);
+
+    /* PTP clock ID — random 64-bit identifier for timing sync. */
+    s->ptp_clock_id = ((uint64_t)rand() << 32) | (uint64_t)rand();
+
+    /* Random RTSP session ID — per OwnTone airplay.c:1535.
+     * Used in the RTSP URL: rtsp://<host>/<session_id>. */
+    s->session_id = (uint32_t)rand();
+    snprintf(s->session_url, sizeof(s->session_url),
+             "rtsp://%s/%u", s->host, s->session_id);
+
+    /* Default to NTP timing — works on Android without privileged ports.
+     * PTP requires binding to 319/320 which Android blocks. */
+    s->use_ntp = 1;
+
+    return s;
+}
+
+static void close_fd(int *fd) {
+    if (*fd >= 0) {
+        close(*fd);
+        *fd = -1;
+    }
+}
+
+void ap2_session_destroy(ap2_session_t **pp) {
+    if (!pp || !*pp) return;
+    ap2_session_t *s = *pp;
+
+    /* Stop drain thread if running. */
+    if (s->drain_running > 0) {
+        s->drain_running = -1;
+        pthread_join(s->drain_thread, NULL);
+    }
+
+    /* Stop PTP thread if running. */
+    if (s->ptp_running) {
+        s->ptp_running = 0;
+        pthread_join(s->ptp_thread, NULL);
+    }
+
+    /* Stop NTP timing thread if running. */
+    if (s->timing_running) {
+        s->timing_running = 0;
+        pthread_join(s->timing_thread, NULL);
+    }
+
+    /* Close all sockets. */
+    close_fd(&s->rtsp_fd);
+    close_fd(&s->data_fd);
+    close_fd(&s->control_fd);
+    close_fd(&s->event_fd);
+    /* PTP may share one socket (ClockPorts mode). Avoid double-close. */
+    if (s->ptp_general_fd == s->ptp_event_fd)
+        s->ptp_general_fd = -1;
+    close_fd(&s->ptp_event_fd);
+    close_fd(&s->ptp_general_fd);
+    close_fd(&s->timing_fd);
+
+    /* Free ring buffer. */
+    free(s->ring);
+    s->ring = NULL;
+
+    /* Destroy mutexes. */
+    pthread_mutex_destroy(&s->ring_mutex);
+    pthread_mutex_destroy(&s->mutex);
+
+    /* Zero sensitive key material. */
+    memset(s->shared_secret, 0, sizeof(s->shared_secret));
+    memset(s->write_key, 0, sizeof(s->write_key));
+    memset(s->read_key, 0, sizeof(s->read_key));
+    memset(s->audio_key, 0, sizeof(s->audio_key));
+    memset(s->ed25519_sk, 0, sizeof(s->ed25519_sk));
+    memset(s->password, 0, sizeof(s->password));
+
+    free(s);
+    *pp = NULL;
+}
+
+const char *ap2_state_name(enum ap2_state st) {
+    switch (st) {
+        case AP2_STATE_INIT:          return "INIT";
+        case AP2_STATE_INFO:          return "INFO";
+        case AP2_STATE_AUTH_SETUP:    return "AUTH_SETUP";
+        case AP2_STATE_PAIR:          return "PAIR";
+        case AP2_STATE_ENCRYPTED:     return "ENCRYPTED";
+        case AP2_STATE_SETUP_SESSION: return "SETUP_SESSION";
+        case AP2_STATE_SETUP_STREAM:  return "SETUP_STREAM";
+        case AP2_STATE_RECORD:        return "RECORD";
+        case AP2_STATE_STREAMING:     return "STREAMING";
+        case AP2_STATE_TEARDOWN:      return "TEARDOWN";
+        default:                      return "UNKNOWN";
+    }
+}

package/android/src/main/cpp/airplay2_session.h

@@ -0,0 +1,197 @@
+/**
+ * AirPlay 2 session — per-session state with no global singletons.
+ *
+ * Every field is owned by one session. Creating a new session allocates
+ * a fresh struct; destroying it frees everything. This is the
+ * fundamental fix for the libraop singleton mutex bug.
+ */
+#ifndef AIRPLAY2_SESSION_H
+#define AIRPLAY2_SESSION_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <pthread.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Session state machine. */
+enum ap2_state {
+    AP2_STATE_INIT = 0,
+    AP2_STATE_INFO,
+    AP2_STATE_AUTH_SETUP,
+    AP2_STATE_PAIR,
+    AP2_STATE_ENCRYPTED,
+    AP2_STATE_SETUP_SESSION,
+    AP2_STATE_SETUP_STREAM,
+    AP2_STATE_RECORD,
+    AP2_STATE_STREAMING,
+    AP2_STATE_TEARDOWN,
+};
+
+/* Auth mode — determined by statusFlags from GET /info. */
+enum ap2_auth_mode {
+    AP2_AUTH_TRANSIENT = 0,   /* No security flags → SRP "3939" */
+    AP2_AUTH_PIN       = 1,   /* ONE_TIME_PAIRING or PIN_REQUIRED → device displays PIN */
+    AP2_AUTH_PASSWORD  = 2,   /* PASSWORD_REQUIRED → user-configured arbitrary string */
+};
+
+/* Forward-declare the ALAC codec handle. */
+struct alac_codec_s;
+
+/**
+ * Per-session struct. No field survives across sessions.
+ * Thread safety: callers must hold `mutex` when touching ring buffer
+ * or state fields from multiple threads.
+ */
+typedef struct ap2_session {
+    /* ---- Network ---- */
+    int rtsp_fd;            /* RTSP TCP socket                */
+    int data_fd;            /* Audio UDP socket (realtime)    */
+    int control_fd;         /* RTCP UDP socket (control)      */
+    int event_fd;           /* Event channel TCP socket       */
+    int ptp_event_fd;       /* PTP UDP socket (port 319)      */
+    int ptp_general_fd;     /* PTP UDP socket (port 320)      */
+    char host[256];
+    int rtsp_port;
+    int data_port;          /* Receiver's audio data port     */
+    int control_port;       /* Receiver's RTCP control port   */
+    int event_port;         /* Receiver's event port          */
+    int ptp_port;           /* Receiver's PTP port (from ClockPorts) */
+
+    /* ---- State machine ---- */
+    enum ap2_state state;
+    pthread_mutex_t mutex;  /* Per-session, NOT global        */
+
+    /* ---- Crypto keys (per-session) ---- */
+    uint8_t shared_secret[64];
+    uint8_t write_key[32];  /* Control channel encrypt key    */
+    uint8_t read_key[32];   /* Control channel decrypt key    */
+    uint8_t audio_key[32];  /* shk for audio encryption       */
+    uint64_t write_nonce;   /* Control channel nonce counter  */
+    uint64_t read_nonce;
+    uint8_t ed25519_sk[64]; /* Long-term signing key          */
+    uint8_t ed25519_pk[32]; /* Long-term public key           */
+    uint8_t server_pk[32];  /* Server's Ed25519 public key    */
+
+    /* ---- Session identifiers ---- */
+    char session_uuid[37];
+    char device_id[18];     /* Receiver MAC                   */
+    uint32_t ssrc;          /* RTP SSRC                       */
+    uint32_t stream_conn_id; /* streamConnectionID for SETUP   */
+    uint32_t session_id;    /* Random RTSP session ID         */
+    char session_url[128];  /* rtsp://<host>/<session_id>     */
+
+    /* ---- Audio pipeline (per-session ring buffer) ---- */
+    uint8_t *ring;
+    size_t ring_size;
+    size_t write_pos;       /* Monotonically increasing       */
+    size_t read_pos;        /* Monotonically increasing       */
+    pthread_mutex_t ring_mutex;
+    pthread_t drain_thread;
+    volatile int drain_running; /* 1=running, 0=paused, -1=stop */
+
+    /* Set to 1 by the drain thread when the receiver stops responding
+     * to /feedback keep-alives (WiFi loss, receiver power-off, etc.).
+     * Callers should skip RTSP TEARDOWN and just close sockets. */
+    volatile int session_dead;
+    int consecutive_feedback_failures;
+
+    /* ---- RTP state ---- */
+    uint16_t rtp_seq;
+    uint32_t rtp_timestamp;
+    uint64_t bytes_sent;
+
+    /* ---- ALAC encoder (per-session) ---- */
+    struct alac_codec_s *alac;
+
+    /* ---- PTP state ---- */
+    uint64_t ptp_clock_id;  /* Our PTP clock identifier        */
+    uint32_t sync_counter;  /* Samples since last sync packet  */
+    uint32_t feedback_counter; /* Samples since last /feedback  */
+    pthread_t ptp_thread;
+    volatile int ptp_running;
+    int64_t ptp_offset_ns;  /* Local clock → PTP master offset */
+
+    /* ---- NTP timing state ---- */
+    int timing_fd;          /* NTP timing UDP socket           */
+    int timing_port;        /* Our NTP timing port             */
+    pthread_t timing_thread;
+    volatile int timing_running;
+    int use_ntp;            /* 1=NTP timing, 0=PTP timing      */
+
+    /* ---- RTSP CSeq ---- */
+    int cseq;
+
+    /* ---- Flags ---- */
+    int pairing_required;
+    int transient_ok;
+    int has_auth_key;
+    int encrypted;          /* 1 after pair-verify completes  */
+    int has_control_keys;   /* 1 when write_key/read_key are derived but encrypted=0 */
+    int pin_required;       /* statusFlags bit 3              */
+    int one_time_pairing;   /* statusFlags bit 9              */
+    int password_required;  /* statusFlags bit 7              */
+    int auth_mode;          /* AP2_AUTH_* enum                */
+
+    /* ---- HTTP Digest auth (for password-protected receivers) ---- */
+    char realm[128];
+    char nonce[256];
+    char password[128];
+    int has_digest_auth;    /* 1 after 401 response parsed    */
+
+    /* ---- Device identity ---- */
+    char device_name[128];  /* Sent as X-Apple-Client-Name    */
+    char dacp_id[17];       /* 16-char hex, sent as DACP-ID + Client-Instance */
+    uint32_t active_remote; /* Sent as Active-Remote (decimal) */
+
+    /* ---- Audio format constants ---- */
+    int sample_rate;
+    int sample_size;
+    int channels;
+    int spf;                /* Samples per frame (352)        */
+    float volume;
+} ap2_session_t;
+
+/* Ring buffer constants. */
+#define AP2_DEFAULT_SPF         352
+#define AP2_DEFAULT_SAMPLE_RATE 44100
+#define AP2_DEFAULT_SAMPLE_SIZE 16
+#define AP2_DEFAULT_CHANNELS    2
+#define AP2_CHUNK_BYTES(s) ((s)->spf * (s)->channels * ((s)->sample_size / 8))
+#define AP2_DEFAULT_RING_CHUNKS 128
+
+/**
+ * Allocate and zero-initialise a session.  All sockets set to -1,
+ * mutexes initialised.  Returns NULL on allocation failure.
+ */
+ap2_session_t *ap2_session_create(const char *host, int port,
+                                  int sample_rate, int sample_size,
+                                  int channels, float volume);
+
+/**
+ * Tear down everything: join threads, close sockets, free ring buffer
+ * and ALAC encoder, destroy mutexes.  Safe to call on a partially
+ * initialised session.  Sets the pointer to NULL via the double-pointer.
+ */
+void ap2_session_destroy(ap2_session_t **session);
+
+/**
+ * Return a human-readable label for a state enum value.
+ */
+const char *ap2_state_name(enum ap2_state s);
+
+/**
+ * Upcall from native → Kotlin when the drain thread determines the session
+ * is dead (e.g. repeated /feedback failures).  Implemented in airplay2_jni.cpp;
+ * declared here so it can be called from audio/control .c files.
+ * @param reason  1 = feedback timeout (more codes may be added later)
+ */
+void ap2_notify_session_died(ap2_session_t *s, int reason);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* AIRPLAY2_SESSION_H */

package/android/src/main/cpp/airplay2_tlv.c

@@ -0,0 +1,135 @@
+/**
+ * TLV8 encoding/decoding for AirPlay 2 pairing messages.
+ */
+
+#include "airplay2_tlv.h"
+#include <stdlib.h>
+#include <string.h>
+
+ap2_tlv_t *ap2_tlv_new(uint8_t tag, const uint8_t *value, size_t length) {
+    ap2_tlv_t *t = (ap2_tlv_t *)calloc(1, sizeof(*t));
+    if (!t) return NULL;
+    t->tag = tag;
+    t->length = length;
+    if (length > 0 && value) {
+        t->value = (uint8_t *)malloc(length);
+        if (!t->value) { free(t); return NULL; }
+        memcpy(t->value, value, length);
+    }
+    return t;
+}
+
+ap2_tlv_t *ap2_tlv_append(ap2_tlv_t *list, ap2_tlv_t *entry) {
+    if (!entry) return list;
+    if (!list) return entry;
+    ap2_tlv_t *tail = list;
+    while (tail->next) tail = tail->next;
+    tail->next = entry;
+    return list;
+}
+
+void ap2_tlv_free(ap2_tlv_t *list) {
+    while (list) {
+        ap2_tlv_t *next = list->next;
+        free(list->value);
+        free(list);
+        list = next;
+    }
+}
+
+ap2_tlv_t *ap2_tlv_find(ap2_tlv_t *list, uint8_t tag) {
+    while (list) {
+        if (list->tag == tag) return list;
+        list = list->next;
+    }
+    return NULL;
+}
+
+int ap2_tlv_encode(const ap2_tlv_t *list, uint8_t **out_buf, size_t *out_len) {
+    /* First pass: compute total output size. */
+    size_t total = 0;
+    for (const ap2_tlv_t *t = list; t; t = t->next) {
+        if (t->length == 0) {
+            total += 2; /* tag + length=0 */
+        } else {
+            /* Number of 255-byte fragments + possible remainder. */
+            size_t full = t->length / 255;
+            size_t rem = t->length % 255;
+            total += full * (2 + 255);
+            if (rem > 0) total += 2 + rem;
+        }
+    }
+
+    uint8_t *buf = (uint8_t *)malloc(total);
+    if (!buf) return -1;
+
+    /* Second pass: write. */
+    size_t pos = 0;
+    for (const ap2_tlv_t *t = list; t; t = t->next) {
+        size_t remaining = t->length;
+        size_t offset = 0;
+
+        if (remaining == 0) {
+            buf[pos++] = t->tag;
+            buf[pos++] = 0;
+            continue;
+        }
+
+        while (remaining > 0) {
+            size_t chunk = remaining > 255 ? 255 : remaining;
+            buf[pos++] = t->tag;
+            buf[pos++] = (uint8_t)chunk;
+            if (t->value) memcpy(buf + pos, t->value + offset, chunk);
+            pos += chunk;
+            offset += chunk;
+            remaining -= chunk;
+        }
+    }
+
+    *out_buf = buf;
+    *out_len = total;
+    return 0;
+}
+
+ap2_tlv_t *ap2_tlv_decode(const uint8_t *data, size_t len) {
+    ap2_tlv_t *head = NULL;
+    size_t pos = 0;
+
+    while (pos + 2 <= len) {
+        uint8_t tag = data[pos];
+        uint8_t frag_len = data[pos + 1];
+        pos += 2;
+
+        if (pos + frag_len > len) {
+            ap2_tlv_free(head);
+            return NULL; /* Truncated */
+        }
+
+        /* Check if the previous entry has the same tag (fragmentation). */
+        ap2_tlv_t *prev = NULL;
+        if (head) {
+            ap2_tlv_t *t = head;
+            while (t->next) t = t->next;
+            if (t->tag == tag) prev = t;
+        }
+
+        if (prev) {
+            /* Extend the previous entry. */
+            size_t new_len = prev->length + frag_len;
+            uint8_t *new_val = (uint8_t *)realloc(prev->value, new_len);
+            if (!new_val) { ap2_tlv_free(head); return NULL; }
+            memcpy(new_val + prev->length, data + pos, frag_len);
+            prev->value = new_val;
+            prev->length = new_len;
+        } else {
+            /* New entry. */
+            ap2_tlv_t *entry = ap2_tlv_new(tag, data + pos, frag_len);
+            if (!entry) { ap2_tlv_free(head); return NULL; }
+            head = ap2_tlv_append(head, entry);
+        }
+
+        pos += frag_len;
+    }
+
+    return head;
+}

package/android/src/main/cpp/airplay2_tlv.h

@@ -0,0 +1,87 @@
+/**
+ * TLV8 encoding/decoding for AirPlay 2 pairing messages.
+ *
+ * Format: [1-byte tag][1-byte length (0-255)][0-255 bytes value]
+ * Values >255 bytes: fragmented across multiple consecutive entries
+ * with the same tag.  Decoder concatenates all consecutive same-tag
+ * entries.
+ */
+#ifndef AIRPLAY2_TLV_H
+#define AIRPLAY2_TLV_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Known TLV8 tags used in AirPlay 2 pairing. */
+#define AP2_TLV_METHOD       0x00
+#define AP2_TLV_IDENTIFIER   0x01
+#define AP2_TLV_SALT         0x02
+#define AP2_TLV_PUBLIC_KEY   0x03
+#define AP2_TLV_PROOF        0x04
+#define AP2_TLV_ENCRYPTED    0x05
+#define AP2_TLV_STATE        0x06
+#define AP2_TLV_ERROR        0x07
+#define AP2_TLV_SIGNATURE    0x0A
+#define AP2_TLV_FLAGS        0x13
+
+/* Decoded TLV entry (linked list). */
+typedef struct ap2_tlv {
+    uint8_t tag;
+    uint8_t *value;     /* Heap-allocated, concatenated from fragments. */
+    size_t length;
+    struct ap2_tlv *next;
+} ap2_tlv_t;
+
+/**
+ * Encode a list of TLV entries into a byte stream.
+ * Handles fragmentation for values >255 bytes.
+ *
+ * @param list      Linked list of TLV entries to encode
+ * @param out_buf   OUT: heap-allocated output buffer (caller frees)
+ * @param out_len   OUT: output length
+ * @return 0 on success
+ */
+int ap2_tlv_encode(const ap2_tlv_t *list, uint8_t **out_buf, size_t *out_len);
+
+/**
+ * Decode a TLV8 byte stream into a linked list.
+ * Concatenates consecutive same-tag fragments.
+ *
+ * @param data  Input TLV8 bytes
+ * @param len   Input length
+ * @return Linked list of decoded entries, or NULL on failure.
+ *         Caller must call ap2_tlv_free().
+ */
+ap2_tlv_t *ap2_tlv_decode(const uint8_t *data, size_t len);
+
+/**
+ * Find the first entry with the given tag.
+ * @return Pointer to entry, or NULL if not found.
+ */
+ap2_tlv_t *ap2_tlv_find(ap2_tlv_t *list, uint8_t tag);
+
+/**
+ * Create a single TLV entry (convenience for building encode lists).
+ * The value is copied.
+ */
+ap2_tlv_t *ap2_tlv_new(uint8_t tag, const uint8_t *value, size_t length);
+
+/**
+ * Append an entry to the end of a list.  Returns the new head.
+ */
+ap2_tlv_t *ap2_tlv_append(ap2_tlv_t *list, ap2_tlv_t *entry);
+
+/**
+ * Free a linked list of TLV entries.
+ */
+void ap2_tlv_free(ap2_tlv_t *list);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* AIRPLAY2_TLV_H */