#[repr(transparent)]pub struct HandleOrInvalid(_);
Expand description
FFI type for handles in return values or out parameters, where INVALID_HANDLE_VALUE
is used
as a sentry value to indicate errors, such as in the return value of CreateFileW
. This uses
repr(transparent)
and has the representation of a host handle, so that it can be used in such
FFI declarations.
The only thing you can usefully do with a HandleOrInvalid
is to convert it into an
OwnedHandle
using its TryFrom
implementation; this conversion takes care of the check for
INVALID_HANDLE_VALUE
. This ensures that such FFI calls cannot start using the handle without
checking for INVALID_HANDLE_VALUE
first.
This type concerns any value other than INVALID_HANDLE_VALUE
to be valid, including NULL
.
This is because APIs that use INVALID_HANDLE_VALUE
as their sentry value may return NULL
under windows_subsystem = "windows"
or other situations where I/O devices are detached.
If this holds a valid handle, it will close the handle on drop.
Implementations
sourceimpl HandleOrInvalid
impl HandleOrInvalid
sourcepub unsafe fn from_raw_handle(handle: RawHandle) -> Self
pub unsafe fn from_raw_handle(handle: RawHandle) -> Self
Constructs a new instance of Self
from the given RawHandle
returned
from a Windows API that uses INVALID_HANDLE_VALUE
to indicate
failure, such as CreateFileW
.
Use HandleOrNull
instead of HandleOrInvalid
for APIs that
use null to indicate failure.
Safety
The passed handle
value must either satisfy the safety requirements
of FromRawHandle::from_raw_handle
, or be
INVALID_HANDLE_VALUE
(-1). Note that not all Windows APIs use
INVALID_HANDLE_VALUE
for errors; see here for the full story.
Trait Implementations
sourceimpl Debug for HandleOrInvalid
impl Debug for HandleOrInvalid
sourceimpl TryFrom<HandleOrInvalid> for OwnedHandle
impl TryFrom<HandleOrInvalid> for OwnedHandle
impl Send for HandleOrInvalid
impl Sync for HandleOrInvalid
Auto Trait Implementations
impl RefUnwindSafe for HandleOrInvalid
impl Unpin for HandleOrInvalid
impl UnwindSafe for HandleOrInvalid
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more