Chore(Docs): Add More Detailed Documentation

src/hotspot/mod.rs

@@ -1,32 +1,54 @@
 mod providers;
 
+use self::providers::prelude::HotspotConfig;
 use platforms::{WifiError, WifiInterface};
-use std::fmt;
+use std::{fmt, io};
 
+/// Error that might occur when interacting managing wireless hotspot.
 #[derive(Debug)]
 pub enum WifiHotspotError {
+  /// Failed to ceate wireless hotspot.
   CreationFailed,
+  /// Failed to stop wireless hotspot service. Try turning off
+  /// the wireless interface via ```wifi.turn_off()```.
+  FailedToStop(io::Error),
+  /// A wireless interface error occurred.
   Other { kind: WifiError },
 }
 
-/// Adds support for wifi hotspot functionality
+/// Wireless hotspot functionality for a wifi interface.
 pub trait WifiHotspot: fmt::Debug + WifiInterface {
-  /// Creates wifi hotspot service for host machine. This only creats the wifi network,
+  /// Creates wireless hotspot service for host machine. This only creates the wifi network,
   /// and isn't responsible for initiating the serving of the wifi network process.
   /// To begin serving the hotspot, use ```start_hotspot()```.
-  fn create_hotspot(ssid: &str, password: &str) -> Result<bool, WifiHotspotError> {
+  fn create_hotspot(
+    &mut self,
+    ssid: &str,
+    password: &str,
+    configuration: Option<&HotspotConfig>,
+  ) -> Result<bool, WifiHotspotError> {
+    let _a = ssid;
+    let _b = password;
+    let _c = configuration;
+
     unimplemented!();
   }
 
-  /// Start serving publicly an already created wifi hotspot.
+  /// Start serving publicly an already created wireless hotspot.
   fn start_hotspot() -> Result<bool, WifiHotspotError> {
     unimplemented!();
   }
 
-  /// Stop serving a wifi network.
+  /// Stop serving a wireless network.
   ///
-  /// > All users connected will automatically be disconnected.
-  fn stop_hotspot() -> Result<bool, WifiHotspotError> {
+  /// **NOTE: All users connected will automatically be disconnected.**
+  fn stop_hotspot(&mut self) -> Result<bool, WifiHotspotError> {
     unimplemented!();
   }
 }
+
+impl From<WifiError> for WifiHotspotError {
+  fn from(error: WifiError) -> Self {
+    WifiHotspotError::Other { kind: error }
+  }
+}

src/hotspot/providers/linux.rs

@@ -1,4 +1,141 @@
-use hotspot::WifiHotspot;
+use hotspot::{WifiHotspot, WifiHotspotError};
 use platforms::WiFi;
+use std::fmt;
+use std::process::Command;
 
-impl WifiHotspot for WiFi {}
+/// Name of the group upon which the hotspot would be created.
+/// This name must be fixed, in order to still interact with
+/// the same hotspot previosuly created.
+const HOTSPOT_GROUP: &'static str = "Hotspot";
+
+/// Configuration for a wireless hotspot.
+pub struct HotspotConfig {
+    /// The band tor broadcast network on.
+    band: Option<HotspotBand>,
+    /// The channel to broadcast network on.
+    channel: Option<Channel>,
+}
+
+#[derive(Debug)]
+/// Band type of wireless hotspot.
+pub enum HotspotBand {
+    /// Band `A`
+    A,
+    /// Band `BG`
+    Bg,
+}
+
+#[derive(Debug, Clone, Copy)]
+/// Channel to broadcast wireless hotspot on.
+pub enum Channel {
+    /// Channel 1
+    One = 1,
+    /// Channel 2
+    Two = 2,
+    /// Channel 3
+    Three = 3,
+    /// Channel 4
+    Four = 4,
+    /// Channel 5
+    Five = 5,
+    /// Channel 6
+    Six = 6,
+}
+
+/// Wireless hotspot functionality for a wifi interface.
+impl WifiHotspot for WiFi {
+    /// Creates wireless hotspot service for host machine. This only creats the wifi network,
+    /// and isn't responsible for initiating the serving of the wifi network process.
+    /// To begin serving the hotspot, use ```start_hotspot()```.
+    fn create_hotspot(
+        &mut self,
+        ssid: &str,
+        password: &str,
+        configuration: Option<&HotspotConfig>,
+    ) -> Result<bool, WifiHotspotError> {
+        let mut command = vec![
+            "device".to_string(),
+            "wifi".to_string(),
+            "ifname".to_string(),
+            self.interface.to_string(),
+            "hotspot".to_string(),
+            "con-name".to_string(),
+            HOTSPOT_GROUP.to_string(),
+            "ssid".to_string(),
+            ssid.to_string(),
+            "password".to_string(),
+            password.to_string(),
+        ];
+
+        let mut cmd = generate_command_param_from_config(configuration);
+        command.append(&mut cmd);
+
+        let output = Command::new("nmcli")
+            .args(&command)
+            .output()
+            .map_err(|_err| WifiHotspotError::CreationFailed)?;
+
+        Ok(String::from_utf8_lossy(&output.stdout)
+            .as_ref()
+            .contains("successfully activated"))
+    }
+
+    /// Start serving publicly an already created wireless hotspot.
+    fn start_hotspot() -> Result<bool, WifiHotspotError> {
+        let output = Command::new("nmcli")
+            .args(&["con", "up", HOTSPOT_GROUP])
+            .output()
+            .map_err(|err| WifiHotspotError::FailedToStop(err))?;
+
+        Ok(String::from_utf8_lossy(&output.stdout)
+            .as_ref()
+            .contains("Connection successfully activated"))
+    }
+
+    /// Stop serving a wireless network.
+    ///
+    /// **NOTE: All users connected will automatically be disconnected.**
+    fn stop_hotspot(&mut self) -> Result<bool, WifiHotspotError> {
+        let output = Command::new("nmcli")
+            .args(&["con", "down", HOTSPOT_GROUP])
+            .output()
+            .map_err(|err| WifiHotspotError::FailedToStop(err))?;
+
+        Ok(String::from_utf8_lossy(&output.stdout)
+            .as_ref()
+            .contains("Connection 'Hotspot' successfully deactivated"))
+    }
+}
+
+/// Generate vector values from a given config paramenters.
+fn generate_command_param_from_config(configuration: Option<&HotspotConfig>) -> Vec<String> {
+    let mut command = vec![];
+
+    if let Some(ref config) = configuration {
+        if let Some(ref band) = config.band {
+            let band = format!("{}", band);
+            let mut a = vec!["band".to_string(), band];
+            command.append(&mut a);
+        }
+
+        if let Some(channel) = config.channel {
+            let channel = format!("{}", channel as u8);
+            command.append(&mut vec!["channel".to_string(), channel]);
+        }
+    };
+
+    command
+}
+
+impl fmt::Display for HotspotBand {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(
+            f,
+            "{}",
+            match self {
+                HotspotBand::A => "a",
+                HotspotBand::Bg => "bg",
+            }
+        )
+    }
+}

src/hotspot/providers/mod.rs

@@ -6,3 +6,12 @@ mod linux;
 
 #[cfg(target_os = "osx")]
 mod osx;
+
+pub mod prelude {
+  #[cfg(target_os = "linux")]
+  pub use super::linux::*;
+  #[cfg(target_os = "osx")]
+  pub use super::osx::*;
+  #[cfg(target_os = "windows")]
+  pub use super::windows::*;
+}

src/hotspot/providers/osx.rs

@@ -1,5 +1,9 @@
-use connectivity::{Network, WifiConnectionError};
+use connectivity::{Connectivity, WifiConnectionError};
 use platforms::WiFi;
 use std::process::Command;
 
+/// Configuration for a wireless hotspot.
+pub struct HotspotConfig {}
+
+/// Wireless hotspot functionality for a wifi interface.
 impl WifiHotspot for WiFi {}

src/hotspot/providers/windows.rs

@@ -1,12 +1,32 @@
-use connectivity::handlers::NetworkXmlProfileHandler;
-use connectivity::{
-    Network, WifiConnectionError, WifiError, WifiHotspot, WifiHotspotError, WifiInterface,
-};
-use platforms::WiFi;
+use hotspot::{WifiHotspot, WifiHotspotError};
+use platforms::{WiFi, WifiError, WifiInterface};
 use std::process::Command;
 
+/// Configuration for a wireless hotspot.
+pub struct HotspotConfig {}
+
+impl WiFi {
+    /// Attempts to turn on a wireless networ if down.
+    fn try_turn_on_network_if_down() -> Result<(), WifiError> {
+        if !Self::is_wifi_enabled()? {
+            Self::turn_on().map_err(|err| WifiError::InterfaceFailedToOn)?;
+        }
+
+        Ok(())
+    }
+}
+
+/// Wireless hotspot functionality for a wifi interface.
 impl WifiHotspot for WiFi {
-    fn create_hotspot(ssid: &str, password: &str) -> Result<bool, WifiHotspotError> {
+    /// Creates wireless hotspot service for host machine. This only creats the wifi network,
+    /// and isn't responsible for initiating the serving of the wifi network process.
+    /// To begin serving the hotspot, use ```start_hotspot()```.
+    fn create_hotspot(
+        &mut self,
+        ssid: &str,
+        password: &str,
+        configuration: Option<&HotspotConfig>,
+    ) -> Result<bool, WifiHotspotError> {
         let output = Command::new("netsh")
             .args(&[
                 "wlan",
@@ -17,21 +37,14 @@ impl WifiHotspot for WiFi {
                 &format!("key={}", password),
             ])
             .output()
-            .map_err(|err| WifiHotspotError::CreationFailed)?;
+            .map_err(|_err| WifiHotspotError::CreationFailed)?;
 
-        Ok(String::from_utf8_lossy(&output.stdout)
+        if !String::from_utf8_lossy(&output.stdout)
             .as_ref()
-            .contains("successfully changed"))
-    }
+            .contains("successfully changed")
+        {}
 
-    fn start_hotspot() -> Result<bool, WifiHotspotError> {
-        if !Self::is_wifi_enabled() {
-            if !Self::turn_on().map_err(|err| WifiHotspotError::Other { kind: err })? {
-                return Err(WifiHotspotError::Other {
-                    kind: WifiError::InterfaceFailedToOn,
-                });
-            }
-        }
+        Self::try_turn_on_network_if_down()?;
 
         let output = Command::new("netsh")
             .args(&["wlan", "start", "hostednetwork"])
@@ -43,7 +56,24 @@ impl WifiHotspot for WiFi {
             .contains("hosted network started"))
     }
 
-    fn stop_hotspot() -> Result<bool, WifiHotspotError> {
+    /// Start serving publicly an already created wireless hotspot.
+    fn start_hotspot() -> Result<bool, WifiHotspotError> {
+        Self::try_turn_on_network_if_down()?;
+
+        let output = Command::new("netsh")
+            .args(&["wlan", "start", "hostednetwork"])
+            .output()
+            .map_err(|err| WifiHotspotError::CreationFailed)?;
+
+        Ok(String::from_utf8_lossy(&output.stdout)
+            .as_ref()
+            .contains("hosted network started"))
+    }
+
+    /// Stop serving a wireless network.
+    ///
+    /// **NOTE: All users connected will automatically be disconnected.**
+    fn stop_hotspot(&mut self) -> Result<bool, WifiHotspotError> {
         let output = Command::new("netsh")
             .args(&["wlan", "stop", "hostednetwork"])
             .output()