feat: high level ModemManager API

mmrs/CHANGELOG.md

@@ -6,9 +6,13 @@ All notable changes to the `mmrs` crate will be documented in this file.
 
 ### Added
 
+- High-level `ModemManager` entry point with modem enumeration, primary-modem
+  connection helpers, SIM PIN operations, signal queries, and per-modem
+  `ModemScope` support (#402).
+- `ConnectionStatus` snapshot model for `ModemManager::status` and
+  `ModemScope::status` (#402).
 - Public model types for the ModemManager domain under `mmrs::models`:
   `Modem`, `ModemState`, `AccessTechnology`, `Sim`, `SimLockState`,
   `Bearer`, `BearerConfig`, `BearerStats`, `Ip4Config`, `IpType`,
   `ModemError`, and the `Result` alias. All public structs and enums are
   `#[non_exhaustive]`; `BearerConfig` ships with `with_*` builder methods.
-

mmrs/src/api/mod.rs

@@ -1,7 +1,11 @@
 //! Public-facing API surface for the `mmrs` crate.
 //!
-//! Currently exposes the [`models`] sub-module; higher-level helpers
-//! (entry-point `ModemManager` struct, builders, etc.) will land here as
-//! the crate grows.
+//! Exposes the high-level [`ModemManager`] entry point, scoped
+//! [`ModemScope`] operations, and the [`models`] sub-module.
 
 pub mod models;
+mod modem_manager;
+mod modem_scope;
+
+pub use modem_manager::ModemManager;
+pub use modem_scope::ModemScope;

mmrs/src/api/models/error.rs

@@ -32,6 +32,10 @@ pub enum ModemError {
     #[error("d-bus error: {0}")]
     Dbus(#[from] zbus::Error),
 
+    /// A standard freedesktop.org D-Bus interface operation failed.
+    #[error("d-bus fdo error: {0}")]
+    DbusFdo(#[from] zbus::fdo::Error),
+
     /// A D-Bus operation failed, with context about what was being attempted.
     #[error("{context}: {source}")]
     DbusOperation {

mmrs/src/api/models/mod.rs

@@ -16,5 +16,5 @@ mod sim;
 
 pub use bearer::{Bearer, BearerConfig, BearerStats, Ip4Config, IpType};
 pub use error::{ModemError, Result};
-pub use modem::{AccessTechnology, Modem, ModemState};
+pub use modem::{AccessTechnology, ConnectionStatus, Modem, ModemState};
 pub use sim::{Sim, SimLockState};

mmrs/src/api/models/modem.rs

@@ -496,6 +496,29 @@ pub struct Modem {
     pub bearer_paths: Vec<String>,
 }
 
+/// Snapshot of a modem's current packet-data connection status.
+///
+/// Produced by [`crate::ModemManager::status`] and
+/// [`crate::ModemScope::status`]. It combines the fields most callers need
+/// when deciding whether a modem is ready, connected, and using a usable radio
+/// technology.
+#[non_exhaustive]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConnectionStatus {
+    /// D-Bus object path of the modem this status belongs to.
+    pub modem_path: String,
+    /// Current modem state.
+    pub state: ModemState,
+    /// Whether the modem currently has an active packet-data bearer.
+    pub connected: bool,
+    /// Current radio access technology bitmask.
+    pub access_technology: AccessTechnology,
+    /// Signal quality percentage when ModemManager reports it.
+    pub signal_quality: Option<u32>,
+    /// D-Bus object paths of bearers owned by this modem.
+    pub bearer_paths: Vec<String>,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;