AnnounceHandler: optional packet-carrying callback

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.

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
 										);
 									}
 								}

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;