working on todo.md features

deps/udpsclient/udps_client.c

@@ -48,7 +48,7 @@
 #define UDPS_FRAG_MASK_BYTES (UDPS_MAX_FRAGMENTS / 8)
 
 /** Largest datagram we can receive, header included. */
-#define UDPS_RX_BUF_BYTES (65535 + 17)
+#define UDPS_RX_BUF_BYTES UDPS_MAX_DATAGRAM_BYTES
 
 /** An incomplete reassembly older than this is abandoned. */
 #define UDPS_SLOT_STALE_S 2.0
@@ -209,6 +209,9 @@ struct udps_client {
     udps_stats_t stats;
     char         err[256];
 
+    udps_datagram_cb datagram_cb;   /**< NULL until set; fires inside poll(). */
+    void            *datagram_user;
+
     udps_config_cb on_config;
     udps_data_cb   on_data;
     udps_event_cb  on_event;
@@ -1245,6 +1248,15 @@ static void copy_str(char *dst, size_t cap, const char *src) {
     dst[cap - 1u] = '\0';
 }
 
+void udps_client_set_datagram_cb(udps_client_t *client,
+                                 udps_datagram_cb cb, void *user) {
+    if (client == NULL) {
+        return;
+    }
+    client->datagram_cb   = cb;
+    client->datagram_user = user;
+}
+
 udps_client_t *udps_client_create(const udps_client_config_t *cfg) {
     udps_client_t *c;
 
@@ -1468,6 +1480,11 @@ int udps_client_poll(udps_client_t *c, int timeout_ms) {
             }
             drained++;
             c->last_data = now_mono();
+            /* The raw datagram, before anything reads out of rxbuf: this is the
+             * only place a malformed or duplicate datagram is still visible. */
+            if (c->datagram_cb != NULL) {
+                c->datagram_cb(c->rxbuf, (size_t)n, now_wall(), c->datagram_user);
+            }
             if ((size_t)n >= UDPS_HEADER_SIZE) {
                 handle_packet(c, c->rxbuf, (size_t)n);
             }

deps/udpsclient/udps_client.h

@@ -237,6 +237,20 @@ typedef void (*udps_data_cb)(const udps_frame_t *frame, void *user);
 /** Called on connection state changes and on recoverable errors. */
 typedef void (*udps_event_cb)(udps_event_t event, const char *detail, void *user);
 
+/**
+ * Largest datagram recv() can deliver on the client's socket, and therefore the
+ * most a raw-datagram observer ever sees in one call.
+ */
+#define UDPS_MAX_DATAGRAM_BYTES (65535 + 17)
+
+/** Called for every datagram as recv() returned it, before the magic check,
+ *  reassembly or resequencing: the bytes a capture has to store, and the only
+ *  place malformed or duplicate datagrams are still visible. Runs on the polling
+ *  thread, inside udps_client_poll(), like every other callback. `bytes` is
+ *  valid until the callback returns. */
+typedef void (*udps_datagram_cb)(const uint8_t *bytes, size_t len,
+                                 double recv_time, void *user);
+
 /**
  * @brief Transport configuration.
  *
@@ -286,6 +300,12 @@ void udps_client_set_callbacks(udps_client_t *client,
                                udps_event_cb  on_event,
                                void          *user);
 
+/** Installs the raw-datagram observer. Separate from
+ *  udps_client_set_callbacks(), whose signature has call sites and which a
+ *  capture hook is no reason to change. May be NULL. */
+void udps_client_set_datagram_cb(udps_client_t *client,
+                                 udps_datagram_cb cb, void *user);
+
 /**
  * @brief Drives the client: connects if needed, then waits for and processes
  *        packets for at most @p timeout_ms milliseconds.