Struct std::os::windows::io::HandleOrInvalid

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

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

This is supported on Windows only.

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

您可以对 HandleOrInvalid 做的唯一有用的事情是使用其 TryFrom 实现将其转换为 OwnedHandle； 此转换负责检查 INVALID_HANDLE_VALUE。

这可确保此类 FFI 调用在未先检查 INVALID_HANDLE_VALUE 的情况下无法开始使用句柄。

此类型涉及除 INVALID_HANDLE_VALUE 之外的任何有效值，包括 NULL。 这是因为使用 INVALID_HANDLE_VALUE 作为它的哨兵值的 API 在 windows_subsystem = "windows" 或其他 I/O 设备分离的情况下可能会返回 NULL。

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

Trait Implementations

impl Debug for HandleOrInvalid

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

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

impl FromRawHandle for HandleOrInvalid

unsafe fn from_raw_handle(handle: RawHandle) -> Self

根据从 Windows API 返回的给定 RawHandle 构造 Self 的新实例，该 API 使用 INVALID_HANDLE_VALUE 指示失败，例如 CreateFileW。

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

Safety

handle 指向的资源必须是打开的，否则为 unowned、null 或等于 INVALID_HANDLE_VALUE (-1)。 请注意，并非所有 Windows API 都使用 INVALID_HANDLE_VALUE 来处理错误； 有关完整故事，请参见 这个。

impl TryFrom<HandleOrInvalid> for OwnedHandle

type Error = ()

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

fn try_from(handle_or_invalid: HandleOrInvalid) -> Result<Self, ()>

执行转换。

impl Send for HandleOrInvalid

impl Sync for HandleOrInvalid