1 //! The following is derived from Rust's
2 //! library/std/src/os/windows/io/raw.rs
3 //! at revision
4 //! 4f9b394c8a24803e57ba892fa00e539742ebafc0.
5 //!
6 //! All code in this file is licensed MIT or Apache 2.0 at your option.
7 
8 use super::super::raw;
9 
10 /// Raw SOCKETs.
11 #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))]
12 pub type RawSocket = raw::SOCKET;
13 
14 /// Extracts raw sockets.
15 #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))]
16 pub trait AsRawSocket {
17     /// Extracts the raw socket.
18     ///
19     /// This function is typically used to **borrow** an owned socket.
20     /// When used in this way, this method does **not** pass ownership of the
21     /// raw socket to the caller, and the socket is only guaranteed
22     /// to be valid while the original object has not yet been destroyed.
23     ///
24     /// However, borrowing is not strictly required. See [`AsSocket::as_socket`]
25     /// for an API which strictly borrows a socket.
26     #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))]
as_raw_socket(&self) -> RawSocket27     fn as_raw_socket(&self) -> RawSocket;
28 }
29 
30 /// Creates I/O objects from raw sockets.
31 #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))]
32 pub trait FromRawSocket {
33     /// Constructs a new I/O object from the specified raw socket.
34     ///
35     /// This function is typically used to **consume ownership** of the socket
36     /// given, passing responsibility for closing the socket to the returned
37     /// object. When used in this way, the returned object
38     /// will take responsibility for closing it when the object goes out of
39     /// scope.
40     ///
41     /// However, consuming ownership is not strictly required. Use a
42     /// `From<OwnedSocket>::from` implementation for an API which strictly
43     /// consumes ownership.
44     ///
45     /// # Safety
46     ///
47     /// The `socket` passed in must:
48     ///   - be a valid an open socket,
49     ///   - be a socket that may be freed via [`closesocket`].
50     ///
51     /// [`closesocket`]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
52     #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))]
from_raw_socket(sock: RawSocket) -> Self53     unsafe fn from_raw_socket(sock: RawSocket) -> Self;
54 }
55 
56 /// A trait to express the ability to consume an object and acquire ownership of
57 /// its raw `SOCKET`.
58 #[cfg_attr(staged_api, stable(feature = "into_raw_os", since = "1.4.0"))]
59 pub trait IntoRawSocket {
60     /// Consumes this object, returning the raw underlying socket.
61     ///
62     /// This function is typically used to **transfer ownership** of the underlying
63     /// socket to the caller. When used in this way, callers are then the unique
64     /// owners of the socket and must close it once it's no longer needed.
65     ///
66     /// However, transferring ownership is not strictly required. Use a
67     /// `Into<OwnedSocket>::into` implementation for an API which strictly
68     /// transfers ownership.
69     #[cfg_attr(staged_api, stable(feature = "into_raw_os", since = "1.4.0"))]
into_raw_socket(self) -> RawSocket70     fn into_raw_socket(self) -> RawSocket;
71 }
72