windows_result/

error.rs

use super::*;
use core::num::NonZeroI32;

#[expect(unused_imports)]
use core::mem::size_of;

/// A Windows error code with optional COM error information.
///
/// # Extended error information
///
/// By default, `Error` retains an `IErrorInfo` object when available. This may include a message,
/// source, and WinRT stack trace.
///
/// Set `RUSTFLAGS=--cfg=windows_slim_errors` to omit `IErrorInfo`. This reduces `Error` to the
/// four-byte [`HRESULT`] and removes its `Drop` implementation, but discards extended information.
///
/// This is controlled by a `--cfg` option rather than a Cargo feature because this compilation
/// option sets a policy that applies to an entire graph of crates. Individual crates that take a
/// dependency on the `windows-result` crate are not in a good position to decide whether they want
/// slim errors or full errors.  Cargo features are meant to be additive, but specifying the size
/// and contents of `Error` is not a feature so much as a whole-program policy decision.
///
/// # References
///
/// * [`IErrorInfo`][error-info]
///
/// [error-info]: https://learn.microsoft.com/windows/win32/api/oaidl/nn-oaidl-ierrorinfo
#[derive(Clone)]
pub struct Error {
    /// The `HRESULT` error code, but represented using [`NonZeroI32`]. [`NonZeroI32`] provides
    /// a "niche" to the Rust compiler, which is a space-saving optimization. This allows the
    /// compiler to use more compact representation for enum variants (such as [`Result`]) that
    /// contain instances of [`Error`].
    code: NonZeroI32,

    /// Contains details about the error, such as error text.
    info: ErrorInfo,
}

/// We remap S_OK to this error because the S_OK representation (zero) is reserved for niche
/// optimizations.
const S_EMPTY_ERROR: NonZeroI32 = const_nonzero_i32(u32::from_be_bytes(*b"S_OK") as i32);

/// Converts an HRESULT into a NonZeroI32. If the input is S_OK (zero), then this is converted to
/// S_EMPTY_ERROR. This is necessary because NonZeroI32, as the name implies, cannot represent the
/// value zero. So we remap it to a value no one should be using, during storage.
const fn const_nonzero_i32(i: i32) -> NonZeroI32 {
    if let Some(nz) = NonZeroI32::new(i) {
        nz
    } else {
        panic!();
    }
}

fn nonzero_hresult(hr: HRESULT) -> NonZeroI32 {
    if let Some(nz) = NonZeroI32::new(hr.0) {
        nz
    } else {
        S_EMPTY_ERROR
    }
}

impl Error {
    /// Creates an error object without any failure information.
    pub const fn empty() -> Self {
        Self {
            code: S_EMPTY_ERROR,
            info: ErrorInfo::empty(),
        }
    }

    /// Creates a new error object, capturing the stack and other information about the
    /// point of failure.
    pub fn new<T: AsRef<str>>(code: HRESULT, message: T) -> Self {
        let message: &str = message.as_ref();
        if message.is_empty() {
            Self::from_hresult(code)
        } else {
            ErrorInfo::originate_error(code, message);
            code.into()
        }
    }

    /// Creates a new error object with an error code, but without additional error information.
    pub fn from_hresult(code: HRESULT) -> Self {
        Self {
            code: nonzero_hresult(code),
            info: ErrorInfo::empty(),
        }
    }

    /// Creates a new `Error` from the Win32 error code returned by `GetLastError()`.
    pub fn from_thread() -> Self {
        Self::from_hresult(HRESULT::from_thread())
    }

    /// The error code describing the error.
    pub const fn code(&self) -> HRESULT {
        if self.code.get() == S_EMPTY_ERROR.get() {
            HRESULT(0)
        } else {
            HRESULT(self.code.get())
        }
    }

    /// The error message describing the error.
    pub fn message(&self) -> String {
        if let Some(message) = self.info.message() {
            return message;
        }

        // Otherwise fallback to a generic error code description.
        self.code().message()
    }

    /// The error object describing the error.
    #[cfg(windows)]
    pub fn as_ptr(&self) -> *mut core::ffi::c_void {
        self.info.as_ptr()
    }
}

#[cfg(feature = "std")]
impl std::error::Error for Error {}

impl From<Error> for HRESULT {
    fn from(error: Error) -> Self {
        let code = error.code();
        error.info.into_thread();
        code
    }
}

impl From<HRESULT> for Error {
    fn from(code: HRESULT) -> Self {
        Self {
            code: nonzero_hresult(code),
            info: ErrorInfo::from_thread(),
        }
    }
}

#[cfg(feature = "std")]
impl From<Error> for std::io::Error {
    fn from(from: Error) -> Self {
        // If the HRESULT wraps a Win32 error (FACILITY_WIN32), unwrap it to the
        // underlying Win32 error code so that `std::io::Error::kind` can decode
        // it into a meaningful `ErrorKind`. For HRESULTs from other facilities
        // (such as COM `E_*` codes or custom facilities), preserve the full
        // HRESULT value to avoid losing information. This mirrors the behavior
        // of .NET's `Marshal.GetExceptionForHR` and the conventions used by
        // Rust's own Win32 error decoding.
        if let Some(win32) = WIN32_ERROR::from_error(&from) {
            Self::from_raw_os_error(win32.0 as i32)
        } else {
            Self::from_raw_os_error(from.code().0)
        }
    }
}

#[cfg(feature = "std")]
impl From<std::io::Error> for Error {
    fn from(from: std::io::Error) -> Self {
        match from.raw_os_error() {
            Some(status) => WIN32_ERROR(status as u32).into(),
            None => HRESULT(E_UNEXPECTED).into(),
        }
    }
}

impl From<alloc::string::FromUtf16Error> for Error {
    fn from(_: alloc::string::FromUtf16Error) -> Self {
        WIN32_ERROR(ERROR_NO_UNICODE_TRANSLATION as u32).into()
    }
}

impl From<alloc::string::FromUtf8Error> for Error {
    fn from(_: alloc::string::FromUtf8Error) -> Self {
        WIN32_ERROR(ERROR_NO_UNICODE_TRANSLATION as u32).into()
    }
}

impl From<core::num::TryFromIntError> for Error {
    fn from(_: core::num::TryFromIntError) -> Self {
        WIN32_ERROR(ERROR_INVALID_DATA as u32).into()
    }
}

impl core::fmt::Debug for Error {
    fn fmt(&self, fmt: &mut core::fmt::Formatter) -> core::fmt::Result {
        let mut debug = fmt.debug_struct("Error");
        debug
            .field("code", &self.code())
            .field("message", &self.message())
            .finish()
    }
}

impl core::fmt::Display for Error {
    fn fmt(&self, fmt: &mut core::fmt::Formatter) -> core::fmt::Result {
        let message = self.message();
        if message.is_empty() {
            core::write!(fmt, "{}", self.code())
        } else {
            core::write!(fmt, "{} ({})", message, self.code())
        }
    }
}

impl core::hash::Hash for Error {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        self.code.hash(state);
        // We do not hash the error info.
    }
}

// Equality tests only the HRESULT, not the error info (if any).
impl PartialEq for Error {
    fn eq(&self, other: &Self) -> bool {
        self.code == other.code
    }
}

impl Eq for Error {}

impl PartialOrd for Error {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Error {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.code.cmp(&other.code)
    }
}

use error_info::*;

#[cfg(all(windows, not(windows_slim_errors)))]
mod error_info {
    use super::*;
    use crate::com::ComPtr;

    /// This type stores error detail, represented by a COM `IErrorInfo` object.
    ///
    /// # References
    ///
    /// * [`IErrorInfo`][error-info]
    ///
    /// [error-info]: https://learn.microsoft.com/windows/win32/api/oaidl/nn-oaidl-ierrorinfo
    #[derive(Clone, Default)]
    pub(crate) struct ErrorInfo {
        pub(super) ptr: Option<ComPtr>,
    }

    impl ErrorInfo {
        pub(crate) const fn empty() -> Self {
            Self { ptr: None }
        }

        pub(crate) fn from_thread() -> Self {
            let mut ptr: *mut core::ffi::c_void = core::ptr::null_mut();
            unsafe { GetErrorInfo(0, &mut ptr) };
            Self {
                ptr: core::ptr::NonNull::new(ptr).map(ComPtr),
            }
        }

        pub(crate) fn into_thread(self) {
            if let Some(ptr) = self.ptr {
                unsafe {
                    SetErrorInfo(0, ptr.as_raw());
                }
            }
        }

        pub(crate) fn originate_error(code: HRESULT, message: &str) {
            let message: Vec<_> = message.encode_utf16().collect();
            unsafe {
                RoOriginateErrorW(code.0, message.len() as u32, message.as_ptr());
            }
        }

        pub(crate) fn message(&self) -> Option<String> {
            use crate::bstr::BasicString;

            let ptr = self.ptr.as_ref()?;

            let mut message = BasicString::default();

            // First attempt to retrieve the restricted error information.
            if let Some(info) = ptr.cast(&IID_IRestrictedErrorInfo) {
                let mut fallback = BasicString::default();
                let mut code = 0;

                unsafe {
                    com_call!(
                        IRestrictedErrorInfo_Vtbl,
                        info.GetErrorDetails(
                            &mut fallback as *mut _ as _,
                            &mut code,
                            &mut message as *mut _ as _,
                            &mut BasicString::default() as *mut _ as _
                        )
                    );
                }

                if message.is_empty() {
                    message = fallback;
                };
            }

            // Next attempt to retrieve the regular error information.
            if message.is_empty() {
                unsafe {
                    com_call!(
                        IErrorInfo_Vtbl,
                        ptr.GetDescription(&mut message as *mut _ as _)
                    );
                }
            }

            Some(String::from_utf16_lossy(wide_trim_end(&message)))
        }

        pub(crate) fn as_ptr(&self) -> *mut core::ffi::c_void {
            if let Some(info) = self.ptr.as_ref() {
                info.as_raw()
            } else {
                core::ptr::null_mut()
            }
        }
    }

    unsafe impl Send for ErrorInfo {}
    unsafe impl Sync for ErrorInfo {}
}

#[cfg(not(all(windows, not(windows_slim_errors))))]
mod error_info {
    use super::*;

    // We use this name so that the NatVis <Type> element for ErrorInfo does *not* match this type.
    // This prevents the NatVis description from failing to load.
    #[derive(Clone, Default)]
    pub(crate) struct EmptyErrorInfo;

    pub(crate) use self::EmptyErrorInfo as ErrorInfo;

    impl EmptyErrorInfo {
        pub(crate) const fn empty() -> Self {
            Self
        }

        pub(crate) fn from_thread() -> Self {
            Self
        }

        pub(crate) fn into_thread(self) {}

        pub(crate) fn originate_error(_code: HRESULT, _message: &str) {}

        pub(crate) fn message(&self) -> Option<String> {
            None
        }

        #[cfg(windows)]
        pub(crate) fn as_ptr(&self) -> *mut core::ffi::c_void {
            core::ptr::null_mut()
        }
    }
}