Skip to main content

open_net/api/error/
windows_reachability.rs

1//! Portable values for diagnosing native Windows reachability failures.
2
3use std::fmt;
4
5/// The native call that failed while sampling Windows Internet reachability.
6///
7/// Available on all platforms without a Windows SDK dependency. Use
8/// [`Self::as_str`] for stable identifiers in structured application events.
9#[non_exhaustive]
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11pub enum WindowsReachabilityOperation {
12    /// `CoInitializeEx` failed to initialize the sampling thread's COM apartment.
13    ComInit,
14    /// `CoCreateInstance` failed to create the Network List Manager interface.
15    NlmCreate,
16    /// `INetworkListManager::GetConnectivity` failed to return a connectivity value.
17    NlmGetConnectivity,
18}
19
20impl WindowsReachabilityOperation {
21    /// Returns the stable operation identifier for structured diagnostics.
22    pub const fn as_str(self) -> &'static str {
23        match self {
24            Self::ComInit => "com_init",
25            Self::NlmCreate => "nlm_create",
26            Self::NlmGetConnectivity => "nlm_get_connectivity",
27        }
28    }
29}
30
31/// The original native failure from Windows Internet-reachability sampling.
32///
33/// These details supplement [`super::ErrorKind::Io`] and
34/// [`super::ErrorStage::NetworkMonitor`]. The original Windows error remains
35/// available through [`std::error::Error::source`] on [`super::NetError`].
36/// No system error text, machine name or network name is retained here.
37#[non_exhaustive]
38#[derive(Clone, Copy, Eq, PartialEq)]
39pub struct WindowsReachabilityDiagnostic {
40    /// Native operation that returned this failure.
41    pub operation: WindowsReachabilityOperation,
42    /// Original HRESULT's 32-bit bit pattern, without Win32 error conversion.
43    ///
44    /// Format with `format!("0x{:08X}", detail.hresult)` for fixed-width hex.
45    pub hresult: u32,
46}
47
48impl fmt::Debug for WindowsReachabilityDiagnostic {
49    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
50        formatter
51            .debug_struct("WindowsReachabilityDiagnostic")
52            .field("operation", &self.operation.as_str())
53            .field("hresult", &format_args!("0x{:08X}", self.hresult))
54            .finish()
55    }
56}
57
58#[cfg(test)]
59#[path = "windows_reachability_tests.rs"]
60mod tests;