pub struct HResult(/* private fields */);Expand description
An HRESULT, the signed code COM and much of the Windows API report in.
An i32: FAILED(hr) is hr < 0, so the severity is the sign bit. The layout, from the top: the
severity, a reserved bit, the customer bit, the NTSTATUS bit, another reserved bit, the facility,
and a 16-bit code. It is a number space of its own, not Win32Error’s: a Win32 code is
wrapped into one by from_win32 and read back out by
win32, and neither direction is lossless in general (see each).
Success is any non-negative value, S_OK (zero) and S_FALSE (one) among them, which is why
into_result can not tell those apart and the raw value is there for a
caller who must. It is not an Error, because a success is a value of this type.
§Example
use win_error_codes::{HResult, Win32Error};
// ERROR_IO_DEVICE, wrapped as HRESULT_FROM_WIN32 wraps it.
let hresult = HResult::from_win32(Win32Error::from_code(1117));
assert_eq!(hresult.raw().cast_unsigned(), 0x8007_045D);
assert!(hresult.is_failure());
assert_eq!(hresult.win32(), Some(Win32Error::from_code(1117)));
assert_eq!(hresult.to_string(), "0x8007045D");
// E_FAIL is a failure that wraps no Win32 code.
let e_fail = HResult::from_raw(0x8000_4005_u32.cast_signed());
assert!(e_fail.is_failure());
assert_eq!(e_fail.win32(), None);Implementations§
Source§impl HResult
impl HResult
Sourcepub const fn is_failure(self) -> bool
pub const fn is_failure(self) -> bool
FAILED(hr): whether the severity bit is set, which is whether the value is negative.
Sourcepub const fn is_success(self) -> bool
pub const fn is_success(self) -> bool
SUCCEEDED(hr): any non-negative value, S_OK and S_FALSE among them.
Sourcepub const fn into_result(self) -> Result<(), Self>
pub const fn into_result(self) -> Result<(), Self>
Ok for a success and Err carrying this value for a failure.
§Errors
This value, when it is a failure.
Sourcepub const fn facility(self) -> u16
pub const fn facility(self) -> u16
HRESULT_FACILITY: the 13 bits above the code, as winerror.h’s macro takes them. That is
wider than the 11-bit facility the documentation draws; see the note on the mask.
Sourcepub const fn is_customer(self) -> bool
pub const fn is_customer(self) -> bool
Whether the customer bit is set: a code a third party defined, not Microsoft.
Sourcepub const fn is_ntstatus_mapped(self) -> bool
pub const fn is_ntstatus_mapped(self) -> bool
Whether the NTSTATUS bit is set, which is what HRESULT_FROM_NT does to a status.
Sourcepub const fn from_win32(error: Win32Error) -> Self
pub const fn from_win32(error: Win32Error) -> Self
HRESULT_FROM_WIN32: wraps a Win32 code with the severity bit and FACILITY_WIN32.
Not lossless, and that is the macro’s own rule. Zero is S_OK. A code that is not
positive as an i32, so one of 2^31 or more, is taken to be an HRESULT already and is
returned as it is. Any other code keeps only its low 16 bits: 0x0010045D and 0x0000045D
both give 0x8007045D. win32 is the inverse only for the codes from 1 to
65535.
Sourcepub const fn win32(self) -> Option<Win32Error>
pub const fn win32(self) -> Option<Win32Error>
The Win32 code this wraps, or None if it is not one from_win32 makes: severity set,
FACILITY_WIN32, and no other bit above the code.
None for S_OK, though from_win32 of zero is S_OK: a success wraps no error, which is
the reading durable-ioring’s ErrorCode already takes and tests. So the round trip holds for
the codes from 1 to 65535 and not for zero or anything above.