Crate ntresult 

Lightweight NTSTATUS-based error handling for Windows kernel-mode Rust code.

ntresult provides a minimal and idiomatic interface for working with Windows NTSTATUS values in Rust, especially in #![no_std] and kernel-mode environments.

Overview

• Converts an NTSTATUS into a Result, and collapses one back out with NtStatus or NtStatusOrSuccess
• Represents failures as Error, a transparent NTSTATUS wrapper
• Carries an expected non-success status as Status in a StatusResult
• Inspects a status through Severity, facility and code accessors
• Converts selected core and alloc errors via common_error
• Offers shorthand macros – ntres!, ntok!, nterr!, the _ret variants that return immediately, and ntbail!

Design

ntresult treats only STATUS_SUCCESS as success. All other NTSTATUS values, including warning and informational codes, are treated as errors unless they are intentionally returned as a Status inside a StatusResult.

The crate contains no unsafe code, enforced with #![forbid(unsafe_code)].

Example

use ntresult::{IntoResult, NtStatus, Result};
use windows_sys::Win32::Foundation::{NTSTATUS, STATUS_SUCCESS};

// Stand-in for a kernel API returning a raw status.
fn open_device() -> NTSTATUS {
    STATUS_SUCCESS
}

fn init_driver() -> Result<()> {
    open_device().into_result()?;   // NTSTATUS -> Result, failures propagate
    Ok(())
}

fn driver_entry() -> NTSTATUS {
    init_driver().ntstatus()        // Result -> NTSTATUS for the kernel
}

assert_eq!(driver_entry(), STATUS_SUCCESS);

Features

All features are additive: each one only adds From conversions into Error. Enabling a feature never changes the behaviour of an existing conversion.

Feature	Default	Toolchain	Conversion added
alloc	no	stable	alloc::collections::TryReserveError
allocator-api	no	nightly	core::alloc::AllocError

Conversions that need nothing beyond core – core::num::TryFromIntError and core::net::AddrParseError – are always available and are not gated.

There are no default features. Enabling alloc links the alloc crate, which makes rustc require a #[global_allocator] from the final artifact even if nothing ever allocates – so a driver that only needs the NTSTATUS wrapper is not made to supply one.

allocator-api enables the unstable allocator_api language feature and so requires a nightly compiler. Everything else builds on stable Rust.

allocator-api does not imply alloc: AllocError lives in core, so the conversion is available even without an allocator.

More features may be added in the future to support additional common error types.

Modules

common_error

Conversions from common Rust error types into Error.

Macros

ntbail

Wrap an NTSTATUS in an Error and return it as Err immediately.

nterr

Wrap an NTSTATUS in an Error and produce it as Err.

nterr_ret

Wrap an NTSTATUS in an Error and return it as Err immediately.

ntok

Shorthand for Ok(value).

ntok_ret

Shorthand for return Ok(value).

ntres

Convert an NTSTATUS into a Result<(), Error>.

ntres_ret

Convert an NTSTATUS into a Result<(), Error> and return it immediately.

Structs

Error

The error type representing [NTSTATUS] codes.

Status

A status that is an expected outcome rather than a failure.

Enums

Severity

The severity class encoded in the top two bits of an [NTSTATUS].

Traits

IntoError

Convert a value into an Error.

IntoResult

Convert a value into a Result whose error type is Error.

NtStatus

Retrieve the [NTSTATUS] code that a value represents.

NtStatusOrSuccess

Collapse any Result into an NTSTATUS, treating every Ok as success.

Type Aliases

Result

A specialized Result type used throughout kernel-mode driver code, where errors are represented by Windows [NTSTATUS] codes.

StatusResult

A Result whose success case carries a Status to be returned verbatim.