qrc 0.0.6

A Rust library for generating and manipulating QR code images in various formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

// Copyright © 2022-2026 QR Code Library (QRC). All rights reserved.
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Wi-Fi network join payloads.
//!
//! [`WifiNetwork`] builds the `WIFI:...;;` string that phone cameras recognise
//! to offer "join network". Encode it like any other string:
//!
//! ```
//! use qrc::payload::wifi::{WifiNetwork, WifiSecurity};
//! use qrc::QRCode;
//!
//! let wifi = WifiNetwork::new("Cafe Guest")
//!     .security(WifiSecurity::Wpa)
//!     .password("latte123");
//! let qr = QRCode::from_string(wifi.to_qr_string());
//! assert!(qr.try_to_qrcode().is_ok());
//! ```

/// The authentication type of a Wi-Fi network.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum WifiSecurity {
    /// WPA/WPA2/WPA3 personal (the common case).
    #[default]
    Wpa,
    /// Legacy WEP.
    Wep,
    /// Open network (no password).
    None,
}

impl WifiSecurity {
    /// The `T:` token value used in the payload.
    fn token(self) -> &'static str {
        match self {
            WifiSecurity::Wpa => "WPA",
            WifiSecurity::Wep => "WEP",
            WifiSecurity::None => "nopass",
        }
    }
}

/// Escapes a value for a Wi-Fi payload: `\`, `;`, `,`, `:` and `"` are
/// backslash-escaped per the de-facto MeCard-style convention.
fn escape(value: &str) -> String {
    let mut out = String::with_capacity(value.len());
    for ch in value.chars() {
        if matches!(ch, '\\' | ';' | ',' | ':' | '"') {
            out.push('\\');
        }
        out.push(ch);
    }
    out
}

/// A Wi-Fi network that serialises to a `WIFI:...;;` join string.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct WifiNetwork {
    /// Network name (SSID).
    ssid: String,
    /// Pre-shared key / password (omitted for open networks).
    password: Option<String>,
    /// Authentication type.
    security: WifiSecurity,
    /// Whether the SSID is hidden (not broadcast).
    hidden: bool,
}

impl WifiNetwork {
    /// Creates a network with the given SSID (WPA by default).
    #[must_use]
    pub fn new(ssid: impl Into<String>) -> Self {
        WifiNetwork {
            ssid: ssid.into(),
            ..Default::default()
        }
    }

    /// Sets the authentication type.
    #[must_use]
    pub fn security(mut self, security: WifiSecurity) -> Self {
        self.security = security;
        self
    }

    /// Sets the password / pre-shared key.
    #[must_use]
    pub fn password(mut self, password: impl Into<String>) -> Self {
        self.password = Some(password.into());
        self
    }

    /// Marks the SSID as hidden.
    #[must_use]
    pub fn hidden(mut self, hidden: bool) -> Self {
        self.hidden = hidden;
        self
    }

    /// Serialises the network to its `WIFI:...;;` payload string.
    #[must_use]
    pub fn to_qr_string(&self) -> String {
        let mut s = format!("WIFI:T:{};S:{};", self.security.token(), escape(&self.ssid));
        // Open networks carry no key.
        if self.security != WifiSecurity::None {
            if let Some(password) = &self.password {
                s.push_str(&format!("P:{};", escape(password)));
            }
        }
        if self.hidden {
            s.push_str("H:true;");
        }
        s.push(';');
        s
    }
}

impl core::fmt::Display for WifiNetwork {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str(&self.to_qr_string())
    }
}