Struct windows_core::Error

pub struct Error { /* private fields */ }

An error object consists of both an error code and optional detailed error information for debugging.

Extended error info and the windows_slim_errors configuration option

Error contains an HRESULT value that describes the error, as well as an optional IErrorInfo COM object. The IErrorInfo object is a COM object that can provide detailed information about an error, such as a text string, a ProgID of the originator, etc. If the error object was originated in an WinRT component, then additional information such as a stack track may be captured.

However, many systems based on COM do not use IErrorInfo. For these systems, the optional error info within Error has no benefits, but has substantial costs because it increases the size of the Error object, which also increases the size of Result<T>.

This error information can be disabled at compile time by setting RUSTFLAGS=--cfg=windows_slim_errors. This removes the IErrorInfo support within the Error type, which has these benefits:

• It reduces the size of Error to 4 bytes (the size of HRESULT).

• It reduces the size of Result<(), Error> to 4 bytes, allowing it to be returned in a single machine register.

• The Error (and Result<T, Error>) types no longer have a Drop impl. This removes the need for lifetime checking and running drop code when Error and Result go out of scope. This significantly reduces code size for codebase that make extensive use of Error.

Of course, these benefits come with a cost; you lose extended error information for those COM objects that support it.

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

Implementations

impl Error

pub const fn empty() -> Error

Creates an error object without any failure information.

pub fn new<T>(code: HRESULT, message: T) -> Error

where T: AsRef<str>,

Creates a new error object, capturing the stack and other information about the point of failure.

pub fn from_hresult(code: HRESULT) -> Error

Creates a new error object with an error code, but without additional error information.

pub fn from_win32() -> Error

Creates a new Error from the Win32 error code returned by GetLastError().

pub const fn code(&self) -> HRESULT

The error code describing the error.

pub fn message(&self) -> String

The error message describing the error.

pub fn as_ptr(&self) -> *mut c_void

The error object describing the error.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type based access to context intended for error reports.

impl From<Error> for Error

fn from(from: Error) -> Error

Converts to this type from the input type.

impl From<Error> for HRESULT

fn from(error: Error) -> HRESULT

Converts to this type from the input type.

impl From<FromUtf16Error> for Error

fn from(_: FromUtf16Error) -> Error

Converts to this type from the input type.

impl From<FromUtf8Error> for Error

fn from(_: FromUtf8Error) -> Error

Converts to this type from the input type.

impl From<HRESULT> for Error

fn from(code: HRESULT) -> Error

Converts to this type from the input type.

impl From<TryFromIntError> for Error

fn from(_: TryFromIntError) -> Error

Converts to this type from the input type.

impl Hash for Error

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Error

fn cmp(&self, other: &Error) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Error

fn eq(&self, other: &Error) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Error

fn partial_cmp(&self, other: &Error) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Error