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 a RefCell that owns the underlying coordinator, which keeps queuing and configuration operations lightweight while the main MAC run loop continues to own radio receive/transmit progression.

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 RefCell<Mac<P, IDENTITIES, PEERS, CHANNELS, ACKS, TX, FRAME, DUP>>, ) -> Self

Creates a cloneable handle backed by shared coordinator state.

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

Registers a local identity with the shared coordinator.

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

Load the persisted frame-counter boundary for one identity.

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

Persist all currently scheduled frame-counter reservations.

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

Registers or refreshes a remote peer in the shared registry.

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

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

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

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

pub fn auto_register_full_key_peers( &self, ) -> Result<bool, MacHandleError<Infallible>>

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

pub fn set_auto_register_full_key_peers( &self, enabled: bool, ) -> Result<(), MacHandleError<Infallible>>

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

pub fn install_pairwise_keys_advanced( &self, identity_id: LocalIdentityId, peer_id: PeerId, pairwise_keys: PairwiseKeys, ) -> Result<Option<PeerCryptoState>, MacHandleError<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, MacHandleError<SendError>>

Enqueues a broadcast frame for transmission.

Returns a SendReceipt for tracking transmission progress.

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

Enqueues a multicast frame for transmission.

Returns a SendReceipt for tracking transmission progress.

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

Enqueues a unicast frame for transmission.

Returns a SendReceipt when options.ack_requested is enabled.

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

Enqueues a blind-unicast frame for transmission.

Returns a SendReceipt when options.ack_requested is enabled.

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

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

pub async fn run( &self, on_event: impl FnMut(LocalIdentityId, MacEventRef<'_>), ) -> Result<(), MacHandleError<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. It keeps the wait policy inside the coordinator instead of requiring callers to hand-roll poll_cycle loops with arbitrary sleeps.

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

Drive the shared MAC forever while ignoring emitted events.

pub fn fill_random( &self, dest: &mut [u8], ) -> Result<(), MacHandleError<Infallible>>

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

pub fn now_ms(&self) -> Result<u64, MacHandleError<Infallible>>

Returns the current coordinator clock time in milliseconds.

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

Registers an ephemeral software identity with the shared coordinator.

This is primarily used by the node layer when a PFS session becomes active.

pub fn remove_ephemeral( &self, id: LocalIdentityId, ) -> Result<bool, MacHandleError<Infallible>>

Removes a previously registered ephemeral identity.

pub 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. Returns false if the send was not found or the coordinator was busy.

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>