From e5419456f478d61e40620659ac4ed6db1aa25056 Mon Sep 17 00:00:00 2001 From: Martin Dobrev Date: Wed, 26 Aug 2026 16:51:31 +0100 Subject: [PATCH] AnnounceHandler: optional packet-carrying callback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a second virtual received_announce(destination_hash, identity, app_data, packet) that Transport now calls; its default forwards to the classic three-argument callback, so existing handlers are unaffected. Handlers that override the new form get the announce packet: receiving interface, hop count, RSSI/SNR and transport id — enough to build neighbour lists without re-parsing and re-verifying the raw packet. --- README.md | 19 +++++++++++++++++++ src/microReticulum/Transport.cpp | 3 ++- src/microReticulum/Transport.h | 9 +++++++++ 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 96629e3c..d196c95f 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,25 @@ Also note the following preprocessor directives used to tune `microStore::FileSt `-DRNS_PATH_TABLE_SEGMENT_COUNT`: Maximum number of segment files to rotate (minimum of 3) Appropriate settings should be selected to match the storage and memory resources available on the target platform. +## Announce Handlers + +Applications receive announces by registering a subclass of `RNS::AnnounceHandler` with `RNS::Transport::register_announce_handler()`. Override either callback: + +```cpp +class MyHandler : public RNS::AnnounceHandler { +public: + // Basic form: destination hash, announced identity and app data. + void received_announce(const RNS::Bytes& destination_hash, const RNS::Identity& announced_identity, const RNS::Bytes& app_data) override; + + // Extended form: additionally receives the announce packet, giving access to + // packet.receiving_interface(), packet.hops(), packet.rssi() and packet.snr(). + // The default implementation forwards to the basic form. + void received_announce(const RNS::Bytes& destination_hash, const RNS::Identity& announced_identity, const RNS::Bytes& app_data, const RNS::Packet& packet) override; +}; +``` + +Pass an aspect filter such as `"lxmf.delivery"` to the `AnnounceHandler` constructor to receive only announces for that destination name, or `nullptr` for all announces. + ## Provisioning microReticulum ships an optional schema-driven configuration subsystem under `src/microReticulum/Provisioning/`. It maintains a registry of namespaces and fields, holds a "working" config in RAM plus a "draft" overlay for pending edits, and (when filesystem support is enabled) persists committed values atomically to flash. Apps frame and transport MsgPack request/response payloads using their preferred link (KISS, BLE GATT, Web Serial, etc.); the library handles everything from the engine inward. diff --git a/src/microReticulum/Transport.cpp b/src/microReticulum/Transport.cpp index 89b5238b..12212c23 100644 --- a/src/microReticulum/Transport.cpp +++ b/src/microReticulum/Transport.cpp @@ -2726,7 +2726,8 @@ TRACEF("path_announce_emitted=%lu", path_announce_emitted); handler->received_announce( packet.destination_hash(), announce_identity, - Identity::recall_app_data(packet.destination_hash()) + Identity::recall_app_data(packet.destination_hash()), + packet ); } } diff --git a/src/microReticulum/Transport.h b/src/microReticulum/Transport.h index 4ce06bd6..aaf6af1f 100644 --- a/src/microReticulum/Transport.h +++ b/src/microReticulum/Transport.h @@ -66,6 +66,15 @@ namespace RNS { // configured aspect filter. Filters must be specific, // and cannot use wildcards. virtual void received_announce(const Bytes& destination_hash, const Identity& announced_identity, const Bytes& app_data) = 0; + // Richer variant with the announce packet itself: receiving interface + // (packet.receiving_interface()), hop count (packet.hops()), signal + // stats (packet.rssi()/snr()), transport id. Defaults to the classic + // callback so existing handlers keep working; override this one to + // get the metadata. + virtual void received_announce(const Bytes& destination_hash, const Identity& announced_identity, const Bytes& app_data, const Packet& packet) { + (void)packet; + received_announce(destination_hash, announced_identity, app_data); + } std::string& aspect_filter() { return _aspect_filter; } private: std::string _aspect_filter;