//! 特定于 Windows 的通用 I/O 原语扩展。

#![stable(feature = "rust1", since = "1.0.0")]

use crate::fs;
use crate::io;
use crate::net;
#[cfg(doc)]
use crate::os::windows::io::{AsHandle, AsSocket};
use crate::os::windows::io::{OwnedHandle, OwnedSocket};
use crate::os::windows::raw;
use crate::ptr;
use crate::sys;
use crate::sys_common::{self, AsInner, FromInner, IntoInner};

/// 原始的句柄。
#[stable(feature = "rust1", since = "1.0.0")]
pub type RawHandle = raw::HANDLE;

/// 未加工的袜子。
#[stable(feature = "rust1", since = "1.0.0")]
pub type RawSocket = raw::SOCKET;

/// 提取原始句柄。
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRawHandle {
    /// 提取原始句柄。
    ///
    /// 这个函数通常用于**借用**一个拥有所有权的句柄。
    /// 以这种方式使用时，此方法不会 ** 将原始句柄的所有权传递给调用者，并且仅在原始 object 尚未被转换时才能保证句柄有效。
    ///
    ///
    /// 此函数可能返回 null，例如在控制台分离时在 [`Stdin`]、[`Stdout`] 或 [`Stderr`] 上调用时。
    ///
    /// 但是，借用并不是严格要求的。有关严格借用句柄的 API，请参见 [`AsHandle::as_handle`]。
    ///
    /// [`Stdin`]: io::Stdin
    /// [`Stdout`]: io::Stdout
    /// [`Stderr`]: io::Stderr
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn as_raw_handle(&self) -> RawHandle;
}

/// 从原始句柄构造 I/O 对象。
#[stable(feature = "from_raw_os", since = "1.1.0")]
pub trait FromRawHandle {
    /// 从指定的原始句柄创建一个新的 I/O 对象。
    ///
    /// 此函数通常用于**消耗给定句柄的所有权**，将关闭句柄的责任传递给返回的 object。
    /// 以这种方式使用时，返回的 object 将负责在 object 离开角色域时关闭它。
    ///
    /// 但是，并不严格要求使用所有权。对严格消耗所有权的 API 使用 `From<OwnedHandle>::from` 实现。
    ///
    /// # Safety
    ///
    /// 传入的 `handle` 必须:
    ///   - 是一个有效的打开句柄，
    ///   - 是可以通过 [`CloseHandle`] 释放的资源的句柄 (与 `RegCloseKey` 或其他关闭函数相反)。
    ///
    /// 请注意，句柄*可能*具有值 `INVALID_HANDLE_VALUE` (-1)，有时它是有效的句柄值。有关完整故事，请参见 [这个][here]。
    ///
    /// [`CloseHandle`]: https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle
    /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "from_raw_os", since = "1.1.0")]
    unsafe fn from_raw_handle(handle: RawHandle) -> Self;
}

/// 一个 trait，表示消费一个对象并获得其原始 `HANDLE` 所有权的能力。
///
#[stable(feature = "into_raw_os", since = "1.4.0")]
pub trait IntoRawHandle {
    /// 消耗此对象，返回原始底层句柄。
    ///
    /// 此函数通常用于将底层句柄的所有权 ** 转移给调用者。
    /// 当以这种方式使用时，调用者是句柄的唯一所有者，并且一旦不再需要它就必须关闭它。
    ///
    ///
    /// 但是，转让所有权并不是严格要求的。
    /// 对严格转移所有权的 API 使用 `Into<OwnedHandle>::into` 实现。
    ///
    #[stable(feature = "into_raw_os", since = "1.4.0")]
    fn into_raw_handle(self) -> RawHandle;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl AsRawHandle for fs::File {
    #[inline]
    fn as_raw_handle(&self) -> RawHandle {
        self.as_inner().as_raw_handle() as RawHandle
    }
}

#[stable(feature = "asraw_stdio", since = "1.21.0")]
impl AsRawHandle for io::Stdin {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_INPUT_HANDLE) as RawHandle })
    }
}

#[stable(feature = "asraw_stdio", since = "1.21.0")]
impl AsRawHandle for io::Stdout {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_OUTPUT_HANDLE) as RawHandle })
    }
}

#[stable(feature = "asraw_stdio", since = "1.21.0")]
impl AsRawHandle for io::Stderr {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_ERROR_HANDLE) as RawHandle })
    }
}

#[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
impl<'a> AsRawHandle for io::StdinLock<'a> {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_INPUT_HANDLE) as RawHandle })
    }
}

#[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
impl<'a> AsRawHandle for io::StdoutLock<'a> {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_OUTPUT_HANDLE) as RawHandle })
    }
}

#[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
impl<'a> AsRawHandle for io::StderrLock<'a> {
    fn as_raw_handle(&self) -> RawHandle {
        stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_ERROR_HANDLE) as RawHandle })
    }
}

// 将 `GetStdHandle` 返回的句柄翻译成句柄返回给用户。
//
fn stdio_handle(raw: RawHandle) -> RawHandle {
    // `GetStdHandle` 预计不会真正失败，所以当它返回 `INVALID_HANDLE_VALUE` 时，这意味着我们是从没有为我们提供标准输入输出句柄的父级启动的，例如带有分离控制台的父级。
    // 在这种情况下，将 null 返回给用户，这与他们在父进程中得到的一致，并且避免了 `INVALID_HANDLE_VALUE` 为当前进程句柄起别名的问题。
    //
    //
    //
    //
    if raw == sys::c::INVALID_HANDLE_VALUE { ptr::null_mut() } else { raw }
}

#[stable(feature = "from_raw_os", since = "1.1.0")]
impl FromRawHandle for fs::File {
    #[inline]
    unsafe fn from_raw_handle(handle: RawHandle) -> fs::File {
        let handle = handle as sys::c::HANDLE;
        fs::File::from_inner(sys::fs::File::from_inner(FromInner::from_inner(
            OwnedHandle::from_raw_handle(handle),
        )))
    }
}

#[stable(feature = "into_raw_os", since = "1.4.0")]
impl IntoRawHandle for fs::File {
    #[inline]
    fn into_raw_handle(self) -> RawHandle {
        self.into_inner().into_raw_handle() as *mut _
    }
}

/// 提取原始套接字。
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRawSocket {
    /// 提取原始套接字。
    ///
    /// 此函数通常用于**借用**一个拥有所有权的套接字。
    /// 以这种方式使用时，此方法不会 ** 将原始套接字的所有权传递给调用者，并且仅在原始 object 尚未转换时才保证套接字有效。
    ///
    ///
    /// 但是，借用并不是严格要求的。有关严格借用套接字的 API，请参见 [`AsSocket::as_socket`]。
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn as_raw_socket(&self) -> RawSocket;
}

/// 从原始套接字创建 I/O 对象。
#[stable(feature = "from_raw_os", since = "1.1.0")]
pub trait FromRawSocket {
    /// 从指定的原始套接字创建一个新的 I/O object。
    ///
    /// 此函数通常用于**消耗给定套接字的所有权**，将关闭套接字的责任传递给返回的 object。
    /// 以这种方式使用时，返回的 object 将负责在 object 离开角色域时关闭它。
    ///
    /// 但是，并不严格要求使用所有权。对严格消耗所有权的 API 使用 `From<OwnedSocket>::from` 实现。
    ///
    /// # Safety
    ///
    /// 传入的 `socket` 必须:
    ///   - 是一个有效的打开套接字，
    ///   - 是一个可以通过 [`closesocket`] 释放的套接字。
    ///
    /// [`closesocket`]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "from_raw_os", since = "1.1.0")]
    unsafe fn from_raw_socket(sock: RawSocket) -> Self;
}

/// 一个 trait，表示消费一个对象并获得其原始 `SOCKET` 所有权的能力。
///
#[stable(feature = "into_raw_os", since = "1.4.0")]
pub trait IntoRawSocket {
    /// 消耗此对象，返回原始底层套接字。
    ///
    /// 此函数通常用于将底层套接字的所有权 ** 转移给调用者。
    /// 当以这种方式使用时，调用者是套接字的唯一所有者，一旦不再需要它就必须关闭它。
    ///
    ///
    /// 但是，转让所有权并不是严格要求的。
    /// 对严格转移所有权的 API 使用 `Into<OwnedSocket>::into` 实现。
    ///
    #[stable(feature = "into_raw_os", since = "1.4.0")]
    fn into_raw_socket(self) -> RawSocket;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl AsRawSocket for net::TcpStream {
    #[inline]
    fn as_raw_socket(&self) -> RawSocket {
        self.as_inner().socket().as_raw_socket()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl AsRawSocket for net::TcpListener {
    #[inline]
    fn as_raw_socket(&self) -> RawSocket {
        self.as_inner().socket().as_raw_socket()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl AsRawSocket for net::UdpSocket {
    #[inline]
    fn as_raw_socket(&self) -> RawSocket {
        self.as_inner().socket().as_raw_socket()
    }
}

#[stable(feature = "from_raw_os", since = "1.1.0")]
impl FromRawSocket for net::TcpStream {
    #[inline]
    unsafe fn from_raw_socket(sock: RawSocket) -> net::TcpStream {
        let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock));
        net::TcpStream::from_inner(sys_common::net::TcpStream::from_inner(sock))
    }
}
#[stable(feature = "from_raw_os", since = "1.1.0")]
impl FromRawSocket for net::TcpListener {
    #[inline]
    unsafe fn from_raw_socket(sock: RawSocket) -> net::TcpListener {
        let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock));
        net::TcpListener::from_inner(sys_common::net::TcpListener::from_inner(sock))
    }
}
#[stable(feature = "from_raw_os", since = "1.1.0")]
impl FromRawSocket for net::UdpSocket {
    #[inline]
    unsafe fn from_raw_socket(sock: RawSocket) -> net::UdpSocket {
        let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock));
        net::UdpSocket::from_inner(sys_common::net::UdpSocket::from_inner(sock))
    }
}

#[stable(feature = "into_raw_os", since = "1.4.0")]
impl IntoRawSocket for net::TcpStream {
    #[inline]
    fn into_raw_socket(self) -> RawSocket {
        self.into_inner().into_socket().into_inner().into_raw_socket()
    }
}

#[stable(feature = "into_raw_os", since = "1.4.0")]
impl IntoRawSocket for net::TcpListener {
    #[inline]
    fn into_raw_socket(self) -> RawSocket {
        self.into_inner().into_socket().into_inner().into_raw_socket()
    }
}

#[stable(feature = "into_raw_os", since = "1.4.0")]
impl IntoRawSocket for net::UdpSocket {
    #[inline]
    fn into_raw_socket(self) -> RawSocket {
        self.into_inner().into_socket().into_inner().into_raw_socket()
    }
}