pub struct HandleOrNull(/* private fields */);
Expand description
FFI type for handles in return values or out parameters, where NULL
is used
as a sentry value to indicate errors, such as in the return value of CreateThread
. 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 HandleOrNull
is to convert it into an
OwnedHandle
using its TryFrom
implementation; this conversion takes care of the check for
NULL
. This ensures that such FFI calls cannot start using the handle without
checking for NULL
first.
This type may hold any handle value that OwnedHandle
may hold. As with OwnedHandle
, when
it holds -1
, that value is interpreted as a valid handle value, such as
the current process handle, and not INVALID_HANDLE_VALUE
.
If this holds a non-null handle, it will close the handle on drop.
Implementations§
source§impl HandleOrNull
impl HandleOrNull
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 null to indicate failure, such as
CreateThread
.
Use HandleOrInvalid
instead of HandleOrNull
for APIs that
use INVALID_HANDLE_VALUE
to indicate failure.
§Safety
The passed handle
value must either satisfy the safety requirements
of FromRawHandle::from_raw_handle
, or be null. Note that not all
Windows APIs use null for errors; see here for the full story.