Struct windows_result::Error

source ·
pub struct Error { /* private fields */ }
Expand description

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

Implementations§

source§

impl Error

source

pub const fn empty() -> Self

Creates an error object without any failure information.

source

pub fn new<T: AsRef<str>>(code: HRESULT, message: T) -> Self

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

source

pub fn from_hresult(code: HRESULT) -> Self

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

source

pub fn from_win32() -> Self

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

source

pub const fn code(&self) -> HRESULT

The error code describing the error.

source

pub fn message(&self) -> String

The error message describing the error.

source

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

The error object describing the error.

Trait Implementations§

source§

impl Clone for Error

source§

fn clone(&self) -> Error

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Error

source§

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

Formats the value using the given formatter. Read more
source§

impl Display for Error

source§

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

Formats the value using the given formatter. Read more
source§

impl Error for Error

1.30.0 · source§

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

The lower-level source of this error, if any. Read more
1.0.0 · source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
1.0.0 · source§

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

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

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. Read more
source§

impl From<Error> for Error

source§

fn from(from: Error) -> Self

Converts to this type from the input type.
source§

impl From<Error> for Error

source§

fn from(from: Error) -> Self

Converts to this type from the input type.
source§

impl From<Error> for HRESULT

source§

fn from(error: Error) -> Self

Converts to this type from the input type.
source§

impl From<FromUtf16Error> for Error

source§

fn from(_: FromUtf16Error) -> Self

Converts to this type from the input type.
source§

impl From<FromUtf8Error> for Error

source§

fn from(_: FromUtf8Error) -> Self

Converts to this type from the input type.
source§

impl From<HRESULT> for Error

source§

fn from(code: HRESULT) -> Self

Converts to this type from the input type.
source§

impl From<TryFromIntError> for Error

source§

fn from(_: TryFromIntError) -> Self

Converts to this type from the input type.
source§

impl Hash for Error

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl Ord for Error

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl PartialEq for Error

source§

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

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

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.
source§

impl PartialOrd for Error

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

impl Eq for Error

Auto Trait Implementations§

§

impl Freeze for Error

§

impl RefUnwindSafe for Error

§

impl Send for Error

§

impl Sync for Error

§

impl Unpin for Error

§

impl UnwindSafe for Error

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.