Crate winresult

Source
Expand description

§🦀 winresult - windows result codes 🦀

Debug-friendly types for windows result codes.

GitHub crates.io docs.rs License

§Why?

  • u32 error codes are annoying to dbg!(...). winresult has awesome Debug impls.

  • u32 error codes are annoying to view in your debugger. winresult has awesome *.natvis files. Use natvis-pdbs!

  • typoing ERROR_WHATEVER in a match is a mere warning. ERROR::WHATEVER is a hard error.
    (I’d still use #![deny(unreachable_patterns)] anyways.)

  • ERROR_INVALID_FUNCTION == S_FALSE (== 1.) Lame!

  • ERROR_FILE_NOT_FOUND (2) is a mess. A function or GetLastError might return:

    labelvaluenotes
    ERROR_FILE_NOT_FOUND0x00000002Not an HRESULT (would be “successful”)
    HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)0x80070002hresult.info “incorrectly” labels ERROR_* as this
    D3D10_ERROR_FILE_NOT_FOUND0x88790002Different facility, same code
    D3D11_ERROR_FILE_NOT_FOUND0x887C0002Different facility, same code

  • ERROR_* is a mixture of HRESULTs and non-HRESULTs. Can you keep them straight? No. No you cannot. Stop lying.

§Types

minmaxtypenotes
00xFFFFErrorCode
00x7FFFFFFFHResultSuccess
0x800000000xFFFFFFFFHResultError
00xFFFFFFFFHResultHResultSuccess | HResultError
00xFFF    HResultFacilityMicrosoft
00xFFFFFFFFNtStatusSuccessNtStatus | ErrorNtStatus
00xFFF    NtStatusFacilityMicrosoft
04    NtStatusSeverity
00xFFFFFFFFWaitCodemostly <= 0x102
00xFFFFFFFFErrorHResultOrCodeErrorCode | HResultError

§Modules of Note

§Buggy Bitwise Comparisons to Forbid

leftrightwhy
ErrorCodeHResultErrornever true, non-overlapping ranges, need to add or remove facility
ErrorCodeHResultSuccessERROR_INVALID_FUNCTION == S_FALSE, need to add or remove facility
ErrorCodeHResultERROR_INVALID_FUNCTION == S_FALSE, need to add or remove facility
ErrorCodeWaitCodeERROR_INVALID_FUNCTION == WAIT_OBJECT_0+1
*Success*Error*never true except by accident

§Conversions

Modules§

APPMODEL
WinRT / UWP AppModel
APPX
APPX package
BT
Background Task
CACHE
Remote Desktop Protocol Bitmap Cache?
CAT
COM Categories
CERT
Certificates (for e.g. HTTPS etc.)
CERTSRV
Certificate Server (for e.g. Certificate Authority validation, etc.)
CLASS
COM Class
CLIPBRD
Clipboard
CO
COM
COMADMIN
COM Admin / Catalog
COMQC
COM+ Queued Components Protocol
CONTEXT
DCOM Context?
CONVERT10
CRYPT
CS
D3D
Direct3D
D3D10
Direct3D 10+
D3D11
Direct3D 11+
D3D12
Direct3D 12+
D3DERR
Direct3D Errors
D3DOK
Direct3D
D3DXERR
D3DX Errors
D3DXFERR
D3DX .X file type errors
DATA
OLE / Clipboard Stuff?
DCOMPOSITION
DirectComposition
DIGSIG
Digital Signature
DISP
IDispatch
DNS
Domain Name Services
DRAGDROP
Drag and Drop
DV
OLE / Data Values / Clipboard Stuff?
DWM
Display Window Manager (desktop rendering composition)
DWRITE
DirectWrite
DXCORE
DirectX
DXGI
DXGI
E
Errors Codes. Typically HResultErrors.
EAS
Exchange ActiveSync
ERROR
Error Codes. Mostly a mixture of HResultErrors and ErrorCodes. submodules: CLOUD_FILE, CLUSTER, DBG, DS, EVT, GRAPHICS, IPSEC, MRM, MUI, NDIS, PRI_MERGE, SECUREBOOT, SERVICE, SVHDX, SXS, SXS::XML, VHD, WMI
Note that ERROR::SUBCATEGORY::CODE is also generally exported as ERROR::SUBCATEGORY_CODE, although the latter is hidden from the docs to reduce clutter.

EVENT
COM Events
FA
FACILITY
FACILITY_* Values for HResults and NtStatuses.
pub mod FACILITY::HRESULT::*, FACILITY::NTSTATUS::*;

FVE
Full Volume Encryption / Bitlocker
FWP
Windows Filtering Platform
GCN
Host Computer Network
HCN
Host Computer Network
HCS
Host Compute System
HSP
HTTP
WinINet / WinHTTP
INET
WinINet
INPLACE
INPUT
IORING
I/O Ring
JSCRIPT
MEM
MENROLL
Mobile Device Management (MDM) Enrollment
MK
MSDTC
MSSIPOTF
NAP
OLE
“Object Linking and Embedding”
OLEOBJ
“Object Linking and Embedding”
ONL
PEER
PEERDIST
Peer Distribution
PERSIST
PLA
Performance Logs and Alerts
PRESENTATION
REGDB
COM+ registration database
RO
WinRT COM
S
Success codes
SCARD
Smart Card
SCHED
Task Scheduler
SDIAG
SEC
SPAPI
SQLITE
SQLite
STATEREPOSITORY
STATUS
[docs.microsoft.com] NtStatus errors, warnings, and other codes (for use in e.g. Kernel / Drivers)
STG
Structured Storage?
STORE
Microsoft Store?
TBS
TBSIMP
TPC
Tablet PC
TPM
Trusted Platform Module (1.2)
TPMAPI
Trusted Platform Module
TPM_20
Trusted Platform Module 2.0
TRUST
Certificate Trust
TYPE
COM Type Libraries
UI
UTC
Universal Telemetry Client (UTC) data in Event Tracing for Windows (ETW) traces.
VIEW
VM_SAVED_STATE_DUMP
WAIT
[docs.microsoft.com] WAIT_* values returned by various WaitFor* and other win32 functions.
WEB
WinINet / WinHTTP
WEP
Wired Equivalent Privacy
WER
Windows Error Reporting
WHV
Windows Hypervisor Platform
WININET
WinINet
WPN
Windows Push Notifications?
WS
Windows Web Services
WSA
WinSock
XACT
Cross-platform Audio Creation Tool (XACT)
XAUDIO2
XAudio 2
XENROLL
Pre-Vista Certificate Enrollment Control

Structs§

ErrorCode
[docs.microsoft.com] ERROR_* values that aren’t HRESULTs (but might be implicitly convertable)
ErrorHResultOrCode
[docs.microsoft.com] HResultError or ErrorCode
HResult
[docs.microsoft.com] HRESULT
HResultError
[docs.microsoft.com] Error HRESULT
HResultFacilityMicrosoft
[docs.microsoft.com] FACILITY_* values corresponding to Microsoft (non-customer) HRSEULTs.
HResultSuccess
[docs.microsoft.com] Success HRESULT
NtStatus
[docs.microsoft.com] NTSTATUS
NtStatusFacilityMicrosoft
[docs.microsoft.com] FACILITY_* values corresponding to Microsoft (non-customer) NTSTATUSes.
NtStatusSeverity
[docs.microsoft.com] NtStatus::Sev
WaitCode
[docs.microsoft.com] WAIT_* values returned by various WaitFor* and other win32 functions.