Struct CheckedConn 

pub struct CheckedConn<T: CheckedPermissions> { /* private fields */ }

A typed connection to a running KeyOS server.

CheckedConn<P> is the lower-level message sender used by the public API crates. Most application code should call a crate-specific wrapper such as BluetoothApi::enable_ble or SettingsApi::get_locale instead of sending raw message values directly. When adding a wrapper method, choose the send method that matches the message trait implemented by #[derive(Message)]:

Message trait	Send method	Use when
BlockingScalar	send_blocking_scalar or try_send_blocking_scalar	The message fits in scalar registers and returns a response.
Scalar	send_scalar, try_send_scalar, or send_scalar_nowait	The message fits in scalar registers and has no response.
BlockingArchive	send_blocking_archive or try_send_blocking_archive	The message is serialized with rkyv and returns a response.
Archive	send_archive, try_send_archive, or send_archive_nowait	The message is serialized with rkyv and has no response.
LendMut	lend_mut	The caller lends a mutable memory range to the server and waits for the server to finish with it.
Move	send_move, try_send_move, or send_move_nowait	The caller transfers ownership of a memory range to the server.
ScalarSubscription / ArchiveSubscription	subscribe_scalar or subscribe_archive	The caller registers its ServerContext to receive future events.

For normal system API wrappers, prefer the infallible methods when the target service is mandatory: delivery failure means the system service has crashed or disconnected, and the device should reboot rather than route unreachable error handling through every caller. Use try_* methods when the API intentionally exposes optional service availability, caller-recoverable transport failure, or explicit queue-full handling.

Implementations

impl<P: CheckedPermissions> CheckedConn<P>

pub fn try_connect() -> Option<Self>

Permission: none

Open a connection to the server based on the server name.

pub fn try_connect_with_timeout(timeout: Duration) -> Option<Self>

Permission: none

pub fn get_remote_pid(&self) -> PID

Permission: none

Get the remote process ID.

pub fn unchecked(&self) -> CheckedConn<WithAllPermissions<P>>

Permission: none

Get a version of this connection that does not do compile-time permission checking.

Use this only for infrastructure code that has already enforced permissions another way. Normal API wrappers should keep their P: MessageAllowed<M> bounds so missing permissions fail at compile time.

pub fn send_blocking_scalar<M>(&self, msg: M) -> M::Response

where M: BlockingScalar, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingScalar message and wait for its response.

Panics if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn try_send_blocking_scalar<M>(&self, msg: M) -> Result<M::Response, Error>

where M: BlockingScalar, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingScalar message and wait for its response.

Returns the underlying transport error if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn send_scalar_async<M, SR>(&self, msg: M, context: &mut ServerContext<SR>)

where M: BlockingScalar, P: MessageAllowed<M>, SR: BlockingScalarResponseHandler<M::Response>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingScalar message and handle its response later on the supplied ServerContext.

pub fn try_send_scalar_async<M, SR>( &self, msg: M, context: &mut ServerContext<SR>, ) -> Result<(), Error>

where M: BlockingScalar, P: MessageAllowed<M>, SR: BlockingScalarResponseHandler<M::Response>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingScalar message asynchronously, returning the transport error if the message cannot be queued.

pub fn send_scalar<M>(&self, msg: M)

where M: Scalar, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Scalar message.

Blocks if the message queue is full and panics if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn try_send_scalar<M>(&self, msg: M) -> Result<(), Error>

where M: Scalar, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Scalar message.

Blocks if the message queue is full and returns the delivery error if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn send_scalar_nowait<M>(&self, msg: M) -> Result<(), Error>

where M: Scalar, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Scalar message without waiting for queue space.

Returns an error if the queue is full or delivery otherwise fails. Can be used in an IRQ handler context.

pub fn send_blocking_archive<M>(&self, msg: M) -> M::Response

where M: BlockingArchive, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingArchive message and wait for its response.

Panics if the message cannot be delivered.

pub fn try_send_blocking_archive<M>(&self, msg: M) -> Result<M::Response, Error>

where M: BlockingArchive, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a BlockingArchive message and wait for its response.

Returns the underlying transport error if the message cannot be delivered or decoded.

pub fn try_send_archive<M>(&self, msg: M) -> Result<(), Error>

where M: Archive, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Archive message.

Blocks if the message queue is full and returns the delivery error if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn send_archive<M>(&self, msg: M)

where M: Archive, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Archive message.

Blocks if the message queue is full and panics if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn send_archive_nowait<M>(&self, msg: M) -> Result<(), Error>

where M: Archive, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a fire-and-forget Archive message without waiting for queue space.

Returns an error if the queue is full or delivery otherwise fails. Can be used in an IRQ handler context.

pub fn lend_mut<M>(&self, msg: M) -> M::Response

where M: LendMut, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a LendMut message and wait for the server to finish with the lent memory.

Use this for APIs that pass a [xous::MemoryRange] to a server for in-place reads or writes.

pub fn send_move<M>(&self, msg: M)

where M: Move, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a Move message, transferring ownership of its memory range.

Blocks if the message queue is full and panics if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn try_send_move<M>(&self, msg: M) -> Result<(), Error>

where M: Move, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a Move message, transferring ownership of its memory range.

Blocks if the message queue is full and returns the delivery error if the message cannot be delivered.

Warning: Cannot be used in an IRQ handler context.

pub fn send_move_nowait<M>(&self, msg: M) -> Result<(), Error>

where M: Move, P: MessageAllowed<M>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Send a Move message without waiting for queue space.

Returns an error if the queue is full or delivery otherwise fails. Can be used in an IRQ handler context.

pub fn subscribe_archive<M, SR>( &self, msg: M, context: &mut ServerContext<SR>, ) -> Result<(), M::Error>

where M: ArchiveSubscription + 'static, P: MessageAllowed<M>, SR: ArchiveEventHandler<M::Event>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Subscribe to archive events.

pub fn subscribe_archive_infallible<M, SR>( &self, msg: M, context: &mut ServerContext<SR>, )

where M: ArchiveSubscription<Error = Infallible> + 'static, P: MessageAllowed<M>, SR: ArchiveEventHandler<M::Event>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Subscribe to archive events (infallible version).

pub fn subscribe_scalar<M, SR>( &self, msg: M, context: &mut ServerContext<SR>, ) -> Result<(), M::Error>

where M: ScalarSubscription + 'static, P: MessageAllowed<M>, SR: ScalarEventHandler<M::Event>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Subscribe to scalar events.

pub fn subscribe_scalar_infallible<M, SR>( &self, msg: M, context: &mut ServerContext<SR>, )

where M: ScalarSubscription<Error = Infallible> + 'static, P: MessageAllowed<M>, SR: ScalarEventHandler<M::Event>,

Permission: TBD (MessageAllowed<M>)

Groups: TBD

Sender policy: TBD

Grant timing: TBD

Subscribe to scalar events (infallible version).

Trait Implementations

impl<T: Clone + CheckedPermissions> Clone for CheckedConn<T>

fn clone(&self) -> CheckedConn<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<P: CheckedPermissions> Debug for CheckedConn<P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P: CheckedPermissions> Default for CheckedConn<P>

fn default() -> Self

Returns the “default value” for a type.

impl<P: CheckedPermissions> From<u32> for CheckedConn<P>

fn from(cid: CID) -> Self

Converts to this type from the input type.