ntresult 0.1.0

Lightweight NTSTATUS-based error handling for Windows kernel-mode Rust code.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Conversions from allocation-related error types.
//!
//! | Error type | `NTSTATUS` | Feature | Toolchain |
//! |---|---|---|---|
//! | `alloc::collections::TryReserveError` | `STATUS_INSUFFICIENT_RESOURCES` | `alloc` | stable |
//! | `core::alloc::AllocError` | `STATUS_INSUFFICIENT_RESOURCES` | `allocator-api` | nightly |
//!
//! The two features are independent. `allocator-api` does not require `alloc`,
//! because `AllocError` is defined in `core` -- a driver using a custom
//! `Allocator` without a global allocator can still use the conversion.

use crate::Error;
use windows_sys::Win32::Foundation::STATUS_INSUFFICIENT_RESOURCES;

#[cfg(feature = "alloc")]
use alloc::collections::TryReserveError;

#[cfg(feature = "allocator-api")]
use core::alloc::AllocError;

/// Convert [`TryReserveError`] into `Error(STATUS_INSUFFICIENT_RESOURCES)`.
///
/// A failed reservation is reported as `STATUS_INSUFFICIENT_RESOURCES`
/// regardless of whether it failed because of capacity overflow or because the
/// allocator refused the request; `TryReserveError` is opaque and the
/// distinction is not actionable for a caller returning an `NTSTATUS`.
///
/// # Examples
/// ```
/// use windows_sys::Win32::Foundation::STATUS_INSUFFICIENT_RESOURCES;
///
/// fn allocate(len: usize) -> ntresult::Result<Vec<u8>> {
///     let mut buf = Vec::new();
///     buf.try_reserve(len)?;
///     Ok(buf)
/// }
///
/// assert!(allocate(16).is_ok());
///
/// let err = allocate(usize::MAX).unwrap_err();
/// assert!(err.is(STATUS_INSUFFICIENT_RESOURCES));
/// ```
#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl From<TryReserveError> for Error {
    #[inline]
    fn from(_: TryReserveError) -> Self {
        Self(STATUS_INSUFFICIENT_RESOURCES)
    }
}

/// Convert [`AllocError`] into `Error(STATUS_INSUFFICIENT_RESOURCES)`.
///
/// Requires the `allocator-api` feature and a nightly compiler.
///
/// # Examples
/// ```
/// #![feature(allocator_api)]
/// use core::alloc::AllocError;
/// use ntresult::Error;
/// use windows_sys::Win32::Foundation::STATUS_INSUFFICIENT_RESOURCES;
///
/// let err = Error::from(AllocError);
/// assert!(err.is(STATUS_INSUFFICIENT_RESOURCES));
/// ```
#[cfg(feature = "allocator-api")]
#[cfg_attr(docsrs, doc(cfg(feature = "allocator-api")))]
impl From<AllocError> for Error {
    #[inline]
    fn from(_: AllocError) -> Self {
        Self(STATUS_INSUFFICIENT_RESOURCES)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[cfg(feature = "alloc")]
    #[test]
    fn try_reserve_error_maps_to_insufficient_resources() {
        let err: TryReserveError = alloc::vec::Vec::<u8>::new()
            .try_reserve(usize::MAX)
            .unwrap_err();

        assert_eq!(Error::from(err).ntstatus(), STATUS_INSUFFICIENT_RESOURCES);
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn try_reserve_error_propagates_through_question_mark() {
        fn allocate(len: usize) -> crate::Result<alloc::vec::Vec<u8>> {
            let mut buf = alloc::vec::Vec::new();
            buf.try_reserve(len)?;
            Ok(buf)
        }

        assert!(allocate(16).is_ok());
        assert!(
            allocate(usize::MAX)
                .unwrap_err()
                .is(STATUS_INSUFFICIENT_RESOURCES)
        );
    }

    #[cfg(feature = "allocator-api")]
    #[test]
    fn alloc_error_maps_to_insufficient_resources() {
        assert_eq!(
            Error::from(AllocError).ntstatus(),
            STATUS_INSUFFICIENT_RESOURCES
        );
    }

    #[cfg(feature = "allocator-api")]
    #[test]
    fn alloc_error_propagates_through_question_mark() {
        fn fallible(fail: bool) -> crate::Result<u32> {
            if fail {
                Err(AllocError)?;
            }
            Ok(7)
        }

        assert_eq!(fallible(false).unwrap(), 7);
        assert!(
            fallible(true)
                .unwrap_err()
                .is(STATUS_INSUFFICIENT_RESOURCES)
        );
    }
}