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;