Struct std::os::windows::io::HandleOrNull

#[repr(transparent)]
pub struct HandleOrNull(_);

🔬 This is a nightly-only experimental API. (io_safety #87074)

This is supported on Windows only.

返回值或输出参数句柄的 FFI 类型，其中 NULL 用作指示错误的哨兵值，例如在 CreateThread 的返回值中。 这使用 repr(transparent) 并具有主机句柄的表示，因此它可以用于此类 FFI 声明。

您可以对 HandleOrNull 做的唯一有用的事情是使用其 TryFrom 实现将其转换成一个 OwnedHandle； 此转换负责检查 NULL。 这可确保此类 FFI 调用在未先检查 NULL 的情况下无法开始使用句柄。

此类型涉及除 NULL 之外的任何有效值，包括 INVALID_HANDLE_VALUE。 这是因为使用 NULL 作为它的哨兵值的 API 不会将 INVALID_HANDLE_VALUE 视为特殊值。

如果它持有一个有效的句柄，它将关闭 丢弃 上的句柄。

Trait Implementations

impl Debug for HandleOrNull

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化程序格式化该值。

impl FromRawHandle for HandleOrNull

unsafe fn from_raw_handle(handle: RawHandle) -> Self

根据从 Windows API 返回的给定 RawHandle 构造一个新的 Self 实例，该 API 使用 null 表示失败，例如 CreateThread。

对于使用 INVALID_HANDLE_VALUE 指示失败的 API，使用 HandleOrInvalid 而不是 HandleOrNull。

Safety

handle 指向的资源必须是打开的，否则是 unowned，或者为 null。请注意，并非所有 Windows API 都使用 null 表示错误； 有关完整故事，请参见 这个。

impl TryFrom<HandleOrNull> for OwnedHandle

type Error = ()

发生转换错误时返回的类型。

fn try_from(handle_or_null: HandleOrNull) -> Result<Self, ()>

执行转换。

impl Send for HandleOrNull

impl Sync for HandleOrNull