win_error_codes/
lib.rs

1// Copyright (c) Mike Grier.
2
3//! The numbers Windows reports failure in, as types.
4//!
5//! Windows reports a failure as a number, and which number space it is in is not in the number.
6//! A `DWORD` from `GetLastError` is one; a `LONG` from a registry call is the same space in a
7//! signed carrier; an `HRESULT` is another, signed and carrying severity and facility bits; and an
8//! `NTSTATUS` is a third, signed, with a two-bit severity and a facility of its own.
9//! Crates here each kept a bare `u32` or wrote a `Win32Error` of their own, and the two that did
10//! disagreed about what to do with a code of 2^31 or more -- which exist: the virtdisk errors are
11//! `WIN32_ERROR`s such as `ERROR_VIRTDISK_NOT_VIRTUAL_DISK`, 3225026581.
12//!
13//! This crate gives each number space its own type, so a code is never a bare integer whose space
14//! the reader has to guess, and so the conversion to and from [`std::io::Error`] is written once
15//! and is exact for every code.
16//!
17//! The decisions behind it are in the crate's `DESIGN-NOTES.md`. The types carry what Windows
18//! said and nothing else: no code is mapped onto a friendlier taxonomy, and no named constants
19//! are defined here, because `windows-sys` has them.
20//!
21//! The numbers and their conversions build on every target. The bridge to [`std::io::Error`] is
22//! `cfg(windows)`, because off Windows a raw OS error is an `errno` and reading one as a Win32
23//! code would be a wrong answer and not a missing feature.
24
25mod hresult;
26mod lstatus;
27mod ntstatus;
28mod win32_error;
29
30#[cfg(test)]
31mod test_codes;
32
33pub use hresult::HResult;
34pub use lstatus::LStatus;
35pub use ntstatus::{NtSeverity, NtStatus};
36pub use win32_error::Win32Error;
37
38// The README carries runnable examples, so they are compiled and a change to the API that breaks
39// one breaks the build.
40#[cfg(doctest)]
41#[doc = include_str!("../README.md")]
42struct ReadmeDoctests;
win_error_codes/lib.rs

win_error_codes/
lib.rs
