Expand description
Windows-specific extensions to general I/O primitives.
Just like raw pointers, raw Windows handles and sockets point to resources with dynamic lifetimes, and they can dangle if they outlive their resources or be forged if they’re created from invalid values.
This module provides three types for representing raw handles and sockets with different ownership properties: raw, borrowed, and owned, which are analogous to types used for representing pointers:
Type | Analogous to |
---|---|
RawHandle | *const _ |
RawSocket | *const _ |
BorrowedHandle<'a> | &'a _ |
BorrowedSocket<'a> | &'a _ |
OwnedHandle | Box<_> |
OwnedSocket | Box<_> |
Like raw pointers, RawHandle
and RawSocket
values are primitive values.
And in new code, they should be considered unsafe to do I/O on (analogous
to dereferencing them). Rust did not always provide this guidance, so
existing code in the Rust ecosystem often doesn’t mark RawHandle
and
RawSocket
usage as unsafe. Once the io_safety
feature is stable,
libraries will be encouraged to migrate, either by adding unsafe
to APIs
that dereference RawHandle
and RawSocket
values, or by using to
BorrowedHandle
, BorrowedSocket
, OwnedHandle
, or OwnedSocket
.
Like references, BorrowedHandle
and BorrowedSocket
values are tied to a
lifetime, to ensure that they don’t outlive the resource they point to.
These are safe to use. BorrowedHandle
and BorrowedSocket
values may be
used in APIs which provide safe access to any system call except for
CloseHandle
, closesocket
, or any other call that would end the
dynamic lifetime of the resource without ending the lifetime of the
handle or socket.
BorrowedHandle
and BorrowedSocket
values may be used in APIs which
provide safe access to DuplicateHandle
and WSADuplicateSocketW
and
related functions, so types implementing AsHandle
, AsSocket
,
From<OwnedHandle>
, or From<OwnedSocket>
should not assume they always
have exclusive access to the underlying object.
Like boxes, OwnedHandle
and OwnedSocket
values conceptually own the
resource they point to, and free (close) it when they are dropped.
Structs
A borrowed handle.
A borrowed socket.
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.
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.
This is the error type used by HandleOrInvalid
when attempting to
convert into a handle, to indicate that the value is
INVALID_HANDLE_VALUE
.
This is the error type used by HandleOrNull
when attempting to convert
into a handle, to indicate that the value is null.
An owned handle.
An owned socket.
Traits
A trait to borrow the handle from an underlying object.
Extracts raw handles.
Extracts raw sockets.
A trait to borrow the socket from an underlying object.
Construct I/O objects from raw handles.
Creates I/O objects from raw sockets.
A trait to express the ability to consume an object and acquire ownership of
its raw HANDLE
.
A trait to express the ability to consume an object and acquire ownership of
its raw SOCKET
.