Struct MacHandle 

pub struct MacHandle<'a, P: Platform, const IDENTITIES: usize = DEFAULT_IDENTITIES, const PEERS: usize = DEFAULT_PEERS, const CHANNELS: usize = DEFAULT_CHANNELS, const ACKS: usize = DEFAULT_ACKS, const TX: usize = DEFAULT_TX, const FRAME: usize = DEFAULT_FRAME, const DUP: usize = DEFAULT_DUP, const RN: usize = DEFAULT_CHANNEL_REPLAY, const HN: usize = DEFAULT_CHANNEL_HINT_REPLAY> { /* private fields */ }

Lightweight, cloneable handle for queuing MAC operations against shared state.

The handle borrows an [AsyncRefCell] that owns the underlying coordinator. Every operation takes the cell asynchronously: if another caller currently holds the coordinator (for example, the long-running run() loop that is waiting on the radio), operations wait rather than failing.

Implementations

impl<'a, P: Platform, const IDENTITIES: usize, const PEERS: usize, const CHANNELS: usize, const ACKS: usize, const TX: usize, const FRAME: usize, const DUP: usize, const RN: usize, const HN: usize> MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP, RN, HN>

pub fn new( mac: &'a AsyncRefCell<Mac<P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP, RN, HN>>, ) -> Self

Creates a cloneable handle backed by shared coordinator state.

pub async fn counters(&self) -> MacCounters

Cumulative frame tallies from the shared coordinator.

pub async fn add_identity( &self, identity: P::Identity, ) -> Result<LocalIdentityId, CapacityError>

Registers a local identity with the shared coordinator.

pub async fn load_persisted_counter( &self, id: LocalIdentityId, ) -> Result<u32, CounterPersistenceError<<P::CounterStore as CounterStore>::Error>>

Load the persisted frame-counter boundary for one identity.

pub async fn service_counter_persistence( &self, ) -> Result<usize, <P::CounterStore as CounterStore>::Error>

Persist all currently scheduled frame-counter reservations.

pub async fn load_all_persisted_rx_counters( &self, ) -> Result<usize, <P::CounterStore as CounterStore>::Error>

Load persisted RX counter boundaries for all registered peers from durable storage, storing them in each peer’s [PeerInfo::initial_rx_counter].

Call this once at boot, after all known peers have been registered with add_peer, and before the first call to next_event. When pairwise keys are later derived for a peer, the replay window is automatically initialised to the loaded boundary.

pub async fn add_peer(&self, key: PublicKey) -> Result<PeerId, AddPeerError>

Registers or refreshes a remote peer in the shared registry.

pub async fn remove_peer(&self, key: &PublicKey) -> bool

Removes a registered peer and its per-peer transport state, reporting whether the peer was registered. Persisted RX counter boundaries are retained so replay protection survives a later re-add.

pub async fn ensure_transient_peer(&self, key: &PublicKey) -> bool

Ensures key is registered at least transiently (unpinned, LRU-evictable), so an explicit reply to a stranger has a slot to send through. Returns whether a slot is held.

pub async fn add_channel(&self, key: ChannelKey) -> Result<(), CapacityError>

Adds or updates a shared channel and derives its multicast keys.

pub async fn remove_channel(&self, key: &ChannelKey) -> bool

Removes a previously added channel by its exact key. Returns whether a channel was removed.

pub async fn add_named_channel(&self, name: &str) -> Result<(), AddChannelError>

Adds or updates a named channel using the coordinator’s channel-key derivation.

The name is canonicalized (ASCII lowercase fold) before derivation.

pub async fn auto_register_full_key_peers(&self) -> bool

Return whether inbound secure packets carrying a full source key may auto-register peers.

pub async fn set_auto_register_full_key_peers(&self, enabled: bool)

Enable or disable inbound full-key peer auto-registration.

pub async fn repeater_enabled(&self) -> bool

Whether the MAC autonomously forwards overheard routable frames.

pub async fn set_repeater_enabled(&self, enabled: bool)

Enable or disable autonomous repeater forwarding. Only the master enabled switch is touched; every other [RepeaterConfig] field (regions, RSSI/SNR gates, contention tuning) keeps its current value. Toggling at runtime is safe: forwarding simply starts or stops honoring newly received frames.

pub async fn set_repeater_policy( &self, regions: &[[u8; 2]], default_region: Option<[u8; 2]>, min_rssi: Option<i16>, min_snr: Option<i8>, ) -> usize

Replace the forwarding policy applied to flood-forwarded frames.

All four values are set together, since they are configured together by whoever administers the repeater; passing an empty regions slice or None clears that gate rather than leaving the previous value in place. The master enabled switch, the flood-contention tuning, and the amateur-radio fields are deliberately untouched — those are separate concerns with their own accessors.

Region codes beyond the configured capacity are ignored; callers that need to know should check the returned count of codes actually stored.

pub async fn install_pairwise_keys_advanced( &self, identity_id: LocalIdentityId, peer_id: PeerId, pairwise_keys: PairwiseKeys, ) -> Result<Option<PeerCryptoState>, SendError>

Installs pairwise transport keys for one local identity and remote peer.

Safety (logical)

Installing wrong keys will silently corrupt the session. This method is deliberately gated behind the unsafe-advanced feature. Prefer going through the node-layer PFS session manager instead.

pub async fn send_broadcast( &self, from: LocalIdentityId, payload: &[u8], options: &SendOptions, ) -> Result<SendReceipt, SendError>

Enqueues a broadcast frame for transmission.

pub async fn send_multicast( &self, from: LocalIdentityId, channel: &ChannelId, payload: &[u8], options: &SendOptions, ) -> Result<SendReceipt, SendError>

Enqueues a multicast frame for transmission.

pub async fn send_unicast( &self, from: LocalIdentityId, dst: &PublicKey, payload: &[u8], options: &SendOptions, ) -> Result<Option<SendReceipt>, SendError>

Enqueues a unicast frame for transmission.

pub async fn send_blind_unicast( &self, from: LocalIdentityId, dst: &PublicKey, channel: &ChannelId, payload: &[u8], options: &SendOptions, ) -> Result<Option<SendReceipt>, SendError>

Enqueues a blind-unicast frame for transmission.

pub async fn next_event( &self, on_event: impl FnMut(LocalIdentityId, MacEventRef<'_>), ) -> Result<(), MacError<<P::Radio as Radio>::Error>>

Drive the shared MAC until one wake cycle completes and invoke on_event for emitted events.

The exclusive borrow on the shared coordinator is released between every internal phase so that other handles (CLI sends, UI queries, counter-persistence services) can interleave their own async work while this driver is waiting on the radio or a timer.

pub async fn run( &self, on_event: impl FnMut(LocalIdentityId, MacEventRef<'_>), ) -> Result<(), MacError<<P::Radio as Radio>::Error>>

Drive the shared MAC forever, invoking on_event for delivered events.

This is the preferred long-lived driver API for standalone MAC-backed tasks.

pub async fn run_quiet( &self, ) -> Result<(), MacError<<P::Radio as Radio>::Error>>

Drive the shared MAC forever while ignoring emitted events.

pub async fn fill_random(&self, dest: &mut [u8])

Fills a caller-provided buffer with random bytes from the shared coordinator RNG.

pub async fn now_ms(&self) -> u64

Returns the current coordinator clock time in milliseconds.

pub async fn register_ephemeral( &self, parent: LocalIdentityId, identity: SoftwareIdentity, ) -> Result<LocalIdentityId, CapacityError>

Registers an ephemeral software identity with the shared coordinator.

pub async fn remove_ephemeral(&self, id: LocalIdentityId) -> bool

Removes a previously registered ephemeral identity.

pub async fn cancel_pending_ack( &self, identity_id: LocalIdentityId, receipt: SendReceipt, ) -> bool

Cancel a pending ACK-requested send, stopping retransmissions.

Returns true if the pending ACK was found and removed.

pub async fn frame_counter(&self, id: LocalIdentityId) -> Option<u32>

Return the live TX frame counter for one identity, if registered.

pub async fn persisted_frame_counter(&self, id: LocalIdentityId) -> Option<u32>

Return the persisted TX frame-counter boundary for one identity, if registered.

pub async fn for_each_peer(&self, f: &mut dyn FnMut(PublicKey))

Invoke f for every peer currently registered in the shared registry.

This covers all known peers, not just those with an active crypto session.

pub async fn peer_route(&self, peer: &PublicKey) -> Option<CachedRoute>

Return the route currently cached for peer, if the peer is registered and a route has been learned for it.

pub async fn clear_peer_route(&self, peer: &PublicKey) -> bool

Forget the route cached for peer, returning whether one was held.

pub async fn for_each_peer_counter( &self, id: LocalIdentityId, f: &mut dyn FnMut(PublicKey, u32, u32), )

Invoke f for each peer with an established crypto state for id, passing the peer’s public key, last-accepted RX counter, and persisted RX boundary.

Trait Implementations

impl<'a, P: Platform, const IDENTITIES: usize, const PEERS: usize, const CHANNELS: usize, const ACKS: usize, const TX: usize, const FRAME: usize, const DUP: usize, const RN: usize, const HN: usize> Clone for MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP, RN, HN>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, P: Platform, const IDENTITIES: usize, const PEERS: usize, const CHANNELS: usize, const ACKS: usize, const TX: usize, const FRAME: usize, const DUP: usize, const RN: usize, const HN: usize> Copy for MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP, RN, HN>