Add SignalLevelAgent

Author: abezukor

examples/monitor_signal_strength.rs

@@ -0,0 +1,41 @@
+use clap::Parser;
+use iwdrs::station::SignalLevelAgent;
+
+#[derive(Debug, Parser)]
+/// Connect to a Wifi Network given a SSID and optionally a password.
+struct Args {
+    #[clap(allow_hyphen_values = true)]
+    levels: Vec<i16>,
+}
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    let Args { levels } = Args::parse();
+
+    let session = iwdrs::session::Session::new().await.unwrap();
+
+    let station = session.stations().pop().unwrap();
+
+    station
+        .register_signal_level_agent(levels, Agent {})
+        .await
+        .unwrap();
+
+    std::future::pending::<()>().await;
+}
+
+struct Agent {}
+
+impl SignalLevelAgent for Agent {
+    fn changed(
+        &self,
+        _station: &iwdrs::station::Station,
+        signal_level: impl std::ops::RangeBounds<i16>,
+    ) {
+        println!(
+            "Wifi Signal Strength Min {:?} Max {:?}",
+            signal_level.start_bound(),
+            signal_level.end_bound()
+        )
+    }
+}

src/station.rs

@@ -1,8 +1,13 @@
-use std::{collections::HashMap, sync::Arc};
+use std::{
+    cmp::Reverse,
+    collections::HashMap,
+    ops::{Bound, RangeBounds},
+    sync::Arc,
+};
 
 use zvariant::{OwnedObjectPath, Value};
 
-use zbus::{Connection, Proxy};
+use zbus::{Connection, Proxy, interface};
 
 use crate::{
     error::{
@@ -94,6 +99,39 @@ impl Station {
 
         Ok(networks)
     }
+
+    /// Register the agent object to receive signal strength level change notifications on the provided agent.
+    /// The "levels" parameters decides the thresholds in dBm that will generate a call to the
+    /// [`SignalLevelAgent::changed`] method whenever current RSSI crosses any of the values.  The number and distance between
+    /// requested threshold values is a compromise between resolution and the frequency of system wakeups and
+    /// context-switches that are going to be occurring to update the client's signal meter.  Only one agent
+    /// can be registered at any time.
+    pub async fn register_signal_level_agent(
+        &self,
+        mut levels: Vec<i16>,
+        agent: impl SignalLevelAgent,
+    ) -> zbus::Result<()> {
+        // Signal level boundaries should be sorted
+        levels.sort_by_key(|signal_level| Reverse(*signal_level));
+
+        let proxy = self.proxy().await?;
+
+        let interface = SignalLevelInterface {
+            agent,
+            connection: self.connection.clone(),
+            levels: levels.clone(),
+        };
+
+        self.connection
+            .object_server()
+            .at(self.dbus_path.clone(), interface)
+            .await?;
+
+        proxy
+            .call_method("RegisterSignalLevelAgent", &(&self.dbus_path, levels))
+            .await?;
+        Ok(())
+    }
 }
 
 impl StationDiagnostics {
@@ -134,3 +172,56 @@ impl StationDiagnostics {
         Ok(body)
     }
 }
+
+pub trait SignalLevelAgent: Send + Sync + 'static {
+    /// This method gets called when the service daemon unregisters the agent. An agent can use it to do
+    /// cleanup tasks. There is no need to unregister the agent, because when this method gets called it has
+    /// already been unregistered.
+    fn release(&self) {}
+
+    fn changed(&self, station: &Station, signal_level: impl RangeBounds<i16>);
+}
+
+pub struct SignalLevelInterface<A> {
+    agent: A,
+    connection: Arc<Connection>,
+    levels: Vec<i16>,
+}
+
+#[interface(name = "net.connman.iwd.SignalLevelAgent")]
+impl<A: SignalLevelAgent> SignalLevelInterface<A> {
+    #[zbus(name = "Release")]
+    fn release(&self) {
+        self.agent.release();
+    }
+
+    /// This method gets called when the signal strength measurement for the device's connected network changes
+    /// enough to go from one level to another out of the N ranges defined by the array of (N-1) threshold values
+    /// passed to RegisterSignalLevelAgent().  It also gets registered.  The level parameter is in the range from 0
+    /// called immediately after the signal level agent is to N, 0 being the strongest signal or above the first
+    /// threshold value in the array, and N being the weakest and below the last threshold value.  For example if
+    /// RegisterSignalLevelAgent was called with the array [-40, -50, -60], the 'level' parameter of 0 would mean signal
+    /// is received at -40 or more dBm and 3 would mean below -60 dBm and might correspond to 1 out of 4 bars on a UI
+    /// signal meter.
+    #[zbus(name = "Changed")]
+    fn changed(&self, station_path: OwnedObjectPath, level_idx: u8) {
+        let station = Station {
+            connection: self.connection.clone(),
+            dbus_path: station_path,
+        };
+
+        let level_idx = usize::from(level_idx);
+        let max_strength = self
+            .levels
+            .get(level_idx - 1)
+            .map(|level| Bound::Excluded(*level))
+            .unwrap_or(Bound::Unbounded);
+        let min_strength = self
+            .levels
+            .get(level_idx)
+            .map(|level| Bound::Included(*level))
+            .unwrap_or(Bound::Unbounded);
+
+        self.agent.changed(&station, (min_strength, max_strength))
+    }
+}