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> { /* 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> MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP>

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

Creates a cloneable handle backed by shared coordinator state.

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 add_peer(&self, key: PublicKey) -> Result<PeerId, CapacityError>

Registers or refreshes a remote peer in the shared registry.

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

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

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

Adds or updates a named channel using the coordinator’s channel-key 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 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.

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> Clone for MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP>

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> Copy for MacHandle<'a, P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP>