Struct Win32Error 

pub struct Win32Error(/* private fields */);

A raw Win32 error code, exactly as Windows produced it: win_error_codes::Win32Error, which carries a code of 2^31 or more through its io::Error form, where this crate’s own earlier type did not.

Re-exported under the name this crate has always used, so every path keeps working. See the shared type for its documentation.

Example

use windows_namespace_request_sys::Win32Error;
use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;

let error = Win32Error::from_code(ERROR_FILE_NOT_FOUND);
assert_eq!(error.code(), ERROR_FILE_NOT_FOUND);

// The io::Error form is a re-presentation, not a reclassification: the raw
// code survives it, however large.
assert_eq!(error.to_io_error().raw_os_error(), Some(ERROR_FILE_NOT_FOUND as i32));
let virtdisk = Win32Error::from_code(0xC03A_0015);
assert_eq!(Win32Error::from_io(&virtdisk.to_io_error()), Some(virtdisk));

A Win32 error code, exactly as Windows produced it.

The DWORD that GetLastError returns, and that a call such as GetStorageDependencyInformation returns directly. Deliberately not an enum: the type carries whatever Windows said, including a code this crate has never heard of. It is not assumed to fit in 16 bits: the virtdisk errors are WIN32_ERRORs above 2^31, and u32 holds them.

ERROR_SUCCESS is an ordinary value of this type, zero, and is_success and into_result are how a call’s return is turned into a Result.

Example

use win_error_codes::Win32Error;

// ERROR_FILE_NOT_FOUND.
let error = Win32Error::from_code(2);
assert_eq!(error.code(), 2);
assert!(!error.is_success());

// A call that returns its code directly: zero is success.
assert_eq!(Win32Error::from_code(0).into_result(), Ok(()));
assert_eq!(Win32Error::from_code(2).into_result(), Err(error));

// A code above 2^31 is carried as it is.
assert_eq!(Win32Error::from_code(0xC03A_0015).code(), 0xC03A_0015);

On Windows the io::Error form keeps the code exactly, however large it is:

use win_error_codes::Win32Error;

// ERROR_VIRTDISK_NOT_VIRTUAL_DISK.
let error = Win32Error::from_code(0xC03A_0015);
let io_error = error.to_io_error();

assert_eq!(Win32Error::from_io(&io_error), Some(error));

Implementations

impl Win32Error

pub const fn to_lstatus(self) -> LStatus

The same code as an LStatus: a bit cast from u32 to i32, so a code above 2^31 is a negative value, which is how a LONG carries it.

impl Win32Error

pub const fn from_code(code: u32) -> Win32Error

Wraps a raw code. Any value is accepted, zero included.

pub const fn code(self) -> u32

The raw code, unaltered.

pub const fn is_success(self) -> bool

Whether this is ERROR_SUCCESS, which is zero.

pub const fn into_result(self) -> Result<(), Win32Error>

Ok for ERROR_SUCCESS and Err carrying this code for anything else, which is how a call that returns its code directly becomes a Result.

Errors

This code, when it is not ERROR_SUCCESS.

impl Win32Error

pub fn from_io(error: &Error) -> Option<Win32Error>

The code in an io::Error, or None for one that carries no OS error at all (one made with io::Error::other, or from an io::ErrorKind alone).

None and not zero: zero is ERROR_SUCCESS, so an error with no code that came back as a code would read as a success.

Std’s io::Error holds an OS error as an i32, so the cast back to the u32 a Win32 code is happens here and is bit-preserving: a code above 2^31, which std holds as a negative number, comes back as it went in.

pub fn to_io_error(self) -> Error

The same failure as a standard io::Error, for callers that funnel everything through std::io.

A re-presentation and not a reclassification: io::Error::raw_os_error on the result is this code, cast at std’s i32 boundary and bit-preserved, for every code, and from_io reverses it exactly.

pub fn last() -> Win32Error

The calling thread’s last error, as GetLastError holds it.

Call this immediately after the failing call: the slot is volatile thread state, and almost any other Win32 call overwrites it, a CloseHandle in a Drop included.

Trait Implementations

impl Clone for Win32Error

fn clone(&self) -> Win32Error

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Win32Error

impl Debug for Win32Error

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

Formats the value using the given formatter.

impl Display for Win32Error

The code in decimal and in hex, and on Windows the system’s message for it after a colon.

The message is io::Error’s own rendering, which this crate does not edit: it ends with std’s (os error N), where N is the code as std holds it, so a code above 2^31 appears there as a negative number as well, and a code the system has no message for says so.

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

Formats the value using the given formatter.

impl Eq for Win32Error

impl Error for Win32Error

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

Returns 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<LStatus> for Win32Error

fn from(status: LStatus) -> Win32Error

Converts to this type from the input type.

impl From<Win32Error> for FinalPathError

fn from(error: Win32Error) -> Self

Converts to this type from the input type.

impl From<Win32Error> for FullPathError

fn from(error: Win32Error) -> Self

Converts to this type from the input type.

impl From<Win32Error> for PerformIntoError

fn from(error: Win32Error) -> Self

Converts to this type from the input type.

impl Hash for Win32Error

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 PartialEq for Win32Error

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Win32Error