//! 特定于 Windows 的 [`std::fs`] 模块中原语的扩展。
//!
//! [`std::fs`]: crate::fs

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

use crate::fs::{self, Metadata, OpenOptions};
use crate::io;
use crate::path::Path;
use crate::sealed::Sealed;
use crate::sys;
use crate::sys_common::{AsInner, AsInnerMut, IntoInner};
use crate::time::SystemTime;

/// 特定于 Windows 的 [`fs::File`] 扩展。
#[stable(feature = "file_offset", since = "1.15.0")]
pub trait FileExt {
    /// 搜寻到给定位置并读取多个字节。
    ///
    /// 返回读取的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    /// 当前游标受此函数的影响，它被设置为读取的结尾。
    ///
    /// 超出文件末尾的读取将始终以 0\ 的长度返回。
    ///
    /// 请注意，类似于 `File::read`，短读返回不会出错。
    /// 从如此短的读取返回时，文件指针仍会更新。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs::File;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///     let mut buffer = [0; 10];
    ///
    ///     // 从文件开头开始读取 10 个字节，从 72 个字节开始。
    /////
    ///     file.seek_read(&mut buffer[..], 72)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "file_offset", since = "1.15.0")]
    fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize>;

    /// 搜寻到给定位置并写入多个字节。
    ///
    /// 返回写入的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    /// 当前游标受此函数的影响，它被设置为写入结束。
    ///
    /// 当写入超出文件末尾时，文件将适当扩展，并且中间字节将保持未初始化状态。
    ///
    ///
    /// 请注意，与 `File::write` 相似，返回短写也不是错误。
    /// 从这么短的写入返回时，文件指针仍会更新。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     // 从文件开头开始写一个字节字符串，从 72 个字节开始。
    /////
    ///     buffer.seek_write(b"some bytes", 72)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "file_offset", since = "1.15.0")]
    fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize>;
}

#[stable(feature = "file_offset", since = "1.15.0")]
impl FileExt for fs::File {
    fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
        self.as_inner().read_at(buf, offset)
    }

    fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
        self.as_inner().write_at(buf, offset)
    }
}

/// 特定于 Windows 的 [`fs::OpenOptions`] 扩展。
#[stable(feature = "open_options_ext", since = "1.10.0")]
pub trait OpenOptionsExt {
    /// 将 `dwDesiredAccess` 参数覆盖为具有指定值的 [`CreateFile`]。
    ///
    /// 这将覆盖 `OpenOptions` 结构体上的 `read`，`write` 和 `append` 标志。
    /// 此方法提供对读取、写入和追加数据、属性 (如隐藏和系统) 和扩展属性的权限的细粒度控制。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    /// use std::os::windows::prelude::*;
    ///
    /// // 在没有读写权限的情况下打开，例如，如果您只需要在文件上调用 `stat`
    /////
    /// let file = OpenOptions::new().access_mode(0).open("foo.txt");
    /// ```
    ///
    /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    ///
    ///
    #[stable(feature = "open_options_ext", since = "1.10.0")]
    fn access_mode(&mut self, access: u32) -> &mut Self;

    /// 将 `dwShareMode` 参数覆盖为具有指定值的 [`CreateFile`]。
    ///
    /// 默认情况下，`share_mode` 设置为 `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`。
    /// 这允许其他进程在打开文件时读取，写入和 delete/rename。
    /// 删除任何标志将阻止其他进程执行相应的操作，直到关闭文件句柄为止。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    /// use std::os::windows::prelude::*;
    ///
    /// // 当我们打开该文件以供写入时，请勿允许他人读取或修改此文件。
    /////
    /// let file = OpenOptions::new()
    ///     .write(true)
    ///     .share_mode(0)
    ///     .open("foo.txt");
    /// ```
    ///
    /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    ///
    ///
    ///
    #[stable(feature = "open_options_ext", since = "1.10.0")]
    fn share_mode(&mut self, val: u32) -> &mut Self;

    /// 将 `dwFileFlags` 参数的额外标志设置为 [`CreateFile2`] 的指定值 (或将其与 `attributes` 和 `security_qos_flags` 组合以将 `dwFlagsAndAttributes` 设置为 [`CreateFile`])。
    ///
    ///
    /// 自定义标志只能设置标志，而不能删除 Rust 选项设置的标志。
    /// 此选项将覆盖以前设置的所有自定义标志。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # #![allow(unexpected_cfgs)]
    /// # #[cfg(for_demonstration_only)]
    /// extern crate winapi;
    /// # mod winapi { pub const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x04000000; }
    ///
    /// use std::fs::OpenOptions;
    /// use std::os::windows::prelude::*;
    ///
    /// let file = OpenOptions::new()
    ///     .create(true)
    ///     .write(true)
    ///     .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE)
    ///     .open("foo.txt");
    /// ```
    ///
    /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
    ///
    ///
    #[stable(feature = "open_options_ext", since = "1.10.0")]
    fn custom_flags(&mut self, flags: u32) -> &mut Self;

    /// 将 `dwFileAttributes` 参数设置为 [`CreateFile2`] 的指定值 (或将其与 `custom_flags` 和 `security_qos_flags` 组合以将 `dwFlagsAndAttributes` 设置为 [`CreateFile`])。
    ///
    ///
    /// 如果由于 _new_ 文件尚不存在而创建了 _new_ 文件，并且已指定 `.create(true)` 或 `.create_new(true)`，则将为新文件提供 `.attributes()` 声明的属性。
    ///
    /// 如果使用 `.create(true).truncate(true)` 打开 _existing_ 文件，则将保留其现有属性并将其与 `.attributes()` 声明的属性合并。
    ///
    /// 在所有其他情况下，属性将被忽略。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # #![allow(unexpected_cfgs)]
    /// # #[cfg(for_demonstration_only)]
    /// extern crate winapi;
    /// # mod winapi { pub const FILE_ATTRIBUTE_HIDDEN: u32 = 2; }
    ///
    /// use std::fs::OpenOptions;
    /// use std::os::windows::prelude::*;
    ///
    /// let file = OpenOptions::new()
    ///     .write(true)
    ///     .create(true)
    ///     .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
    ///     .open("foo.txt");
    /// ```
    ///
    /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "open_options_ext", since = "1.10.0")]
    fn attributes(&mut self, val: u32) -> &mut Self;

    /// 将 `dwSecurityQosFlags` 参数设置为 [`CreateFile2`] 的指定值 (或将其与 `custom_flags` 和 `attributes` 组合以将 `dwFlagsAndAttributes` 设置为 [`CreateFile`])。
    ///
    /// 默认情况下，未设置 `security_qos_flags`。
    /// 在打开命名管道时应指定此名称，以控制服务器进程可以代表客户端进程执行的程度 (安全模拟级别)。
    ///
    /// 如果未设置 `security_qos_flags`，则恶意程序可以通过诱使程序打开命名管道来允许其打开用户指定的路径，从而获得权限 Rust 进程的提升的权限。
    ///
    /// 因此可以说在打开任意路径时也应设置 `security_qos_flags`。
    /// 但是，这些位可能会与其他标志 (特别是 `FILE_FLAG_OPEN_NO_RECALL`) 发生冲突。
    ///
    /// 有关可能的值的信息，请参见 Windows Dev Center 网站上的 [Impersonation Levels]。使用此方法时，`SECURITY_SQOS_PRESENT` 标志会自动设置。
    ///
    ///
    ///
    ///
    ///
    ///
    ///

    /// # Examples
    ///
    /// ```no_run
    /// # #![allow(unexpected_cfgs)]
    /// # #[cfg(for_demonstration_only)]
    /// extern crate winapi;
    /// # mod winapi { pub const SECURITY_IDENTIFICATION: u32 = 0; }
    /// use std::fs::OpenOptions;
    /// use std::os::windows::prelude::*;
    ///
    /// let file = OpenOptions::new()
    ///     .write(true)
    ///     .create(true)
    ///
    ///     // 将标志值设置为 `SecurityIdentification`。
    ///     .security_qos_flags(winapi::SECURITY_IDENTIFICATION)
    ///
    ///     .open(r"\\.\pipe\MyPipe");
    /// ```
    ///
    /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
    /// [Impersonation Levels]:
    ///     https://docs.microsoft.com/en-us/windows/win32/api/winnt/ne-winnt-security_impersonation_level
    #[stable(feature = "open_options_ext", since = "1.10.0")]
    fn security_qos_flags(&mut self, flags: u32) -> &mut Self;
}

#[stable(feature = "open_options_ext", since = "1.10.0")]
impl OpenOptionsExt for OpenOptions {
    fn access_mode(&mut self, access: u32) -> &mut OpenOptions {
        self.as_inner_mut().access_mode(access);
        self
    }

    fn share_mode(&mut self, share: u32) -> &mut OpenOptions {
        self.as_inner_mut().share_mode(share);
        self
    }

    fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions {
        self.as_inner_mut().custom_flags(flags);
        self
    }

    fn attributes(&mut self, attributes: u32) -> &mut OpenOptions {
        self.as_inner_mut().attributes(attributes);
        self
    }

    fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions {
        self.as_inner_mut().security_qos_flags(flags);
        self
    }
}

/// 特定于 Windows 的 [`fs::Metadata`] 扩展。
///
/// 这个 trait 公开的数据成员与 [`BY_HANDLE_FILE_INFORMATION`] 结构体的成员相对应。
///
///
/// [`BY_HANDLE_FILE_INFORMATION`]:
///     https://docs.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information
#[stable(feature = "metadata_ext", since = "1.1.0")]
pub trait MetadataExt {
    /// 返回此元数据的 `dwFileAttributes` 字段的值。
    ///
    /// 该字段包含文件或目录的文件系统属性信息。
    /// 有关可能的值及其说明，请参见 Windows 开发人员中心中的 [文件属性常量][File Attribute Constants]。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let attributes = metadata.file_attributes();
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [File Attribute Constants]:
    ///     https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants
    #[stable(feature = "metadata_ext", since = "1.1.0")]
    fn file_attributes(&self) -> u32;

    /// 返回此元数据的 `ftCreationTime` 字段的值。
    ///
    /// 返回的 64 位值等效于 [`FILETIME`] 结构体，它表示自 1601 年 1 月 1 日以来的 100 纳秒间隔 (UTC)。
    /// 建议将结构体自动转换为 `u64` 值。
    ///
    /// 如果底层文件系统不支持创建时间，则返回值为 0.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let creation_time = metadata.creation_time();
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime
    ///
    ///
    ///
    ///
    #[stable(feature = "metadata_ext", since = "1.1.0")]
    fn creation_time(&self) -> u64;

    /// 返回此元数据的 `ftLastAccessTime` 字段的值。
    ///
    /// 返回的 64 位值等效于 [`FILETIME`] 结构体，它表示自 1601 年 1 月 1 日以来的 100 纳秒间隔 (UTC)。
    ///
    /// 建议将结构体自动转换为 `u64` 值。
    ///
    /// 对于文件，该值指定最后一次读取或写入文件的时间。
    /// 对于目录，该值指定创建目录的时间。
    /// 对于文件和目录，指定的日期都是正确的，但是一天中的时间始终设置为午夜。
    ///
    /// 如果底层文件系统不支持上次访问时间，则返回值为 0.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let last_access_time = metadata.last_access_time();
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "metadata_ext", since = "1.1.0")]
    fn last_access_time(&self) -> u64;

    /// 返回此元数据的 `ftLastWriteTime` 字段的值。
    ///
    /// 返回的 64 位值等效于 [`FILETIME`] 结构体，它表示自 1601 年 1 月 1 日以来的 100 纳秒间隔 (UTC)。
    /// 建议将结构体自动转换为 `u64` 值。
    ///
    /// 对于文件，该值指定文件的最后写入时间。对于目录，结构体指定目录的创建时间。
    ///
    /// 如果底层文件系统不支持最后写入时间，则返回值为 0.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let last_write_time = metadata.last_write_time();
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "metadata_ext", since = "1.1.0")]
    fn last_write_time(&self) -> u64;

    /// 返回此元数据的 `nFileSize{High,Low}` 字段的值。
    ///
    ///
    /// 返回的值对目录没有意义。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::fs;
    /// use std::os::windows::prelude::*;
    ///
    /// fn main() -> io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let file_size = metadata.file_size();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "metadata_ext", since = "1.1.0")]
    fn file_size(&self) -> u64;

    /// 返回此元数据的 `dwVolumeSerialNumber` 字段的值。
    ///
    /// 如果 `Metadata` 实例是从调用创建到 `DirEntry::metadata`，则将返回 `None`。
    /// 如果此 `Metadata` 是使用 `fs::metadata` 或 `File::metadata` 创建的，则它将返回 `Some`。
    ///
    ///
    #[unstable(feature = "windows_by_handle", issue = "63010")]
    fn volume_serial_number(&self) -> Option<u32>;

    /// 返回此元数据的 `nNumberOfLinks` 字段的值。
    ///
    /// 如果 `Metadata` 实例是从调用创建到 `DirEntry::metadata`，则将返回 `None`。
    /// 如果此 `Metadata` 是使用 `fs::metadata` 或 `File::metadata` 创建的，则它将返回 `Some`。
    ///
    ///
    #[unstable(feature = "windows_by_handle", issue = "63010")]
    fn number_of_links(&self) -> Option<u32>;

    /// 返回此元数据的 `nFileIndex{Low,High}` 字段的值。
    ///
    /// 如果 `Metadata` 实例是从调用创建到 `DirEntry::metadata`，则将返回 `None`。
    /// 如果此 `Metadata` 是使用 `fs::metadata` 或 `File::metadata` 创建的，则它将返回 `Some`。
    ///
    ///
    #[unstable(feature = "windows_by_handle", issue = "63010")]
    fn file_index(&self) -> Option<u64>;
}

#[stable(feature = "metadata_ext", since = "1.1.0")]
impl MetadataExt for Metadata {
    fn file_attributes(&self) -> u32 {
        self.as_inner().attrs()
    }
    fn creation_time(&self) -> u64 {
        self.as_inner().created_u64()
    }
    fn last_access_time(&self) -> u64 {
        self.as_inner().accessed_u64()
    }
    fn last_write_time(&self) -> u64 {
        self.as_inner().modified_u64()
    }
    fn file_size(&self) -> u64 {
        self.as_inner().size()
    }
    fn volume_serial_number(&self) -> Option<u32> {
        self.as_inner().volume_serial_number()
    }
    fn number_of_links(&self) -> Option<u32> {
        self.as_inner().number_of_links()
    }
    fn file_index(&self) -> Option<u64> {
        self.as_inner().file_index()
    }
}

/// 特定于 Windows 的 [`fs::FileType`] 扩展。
///
/// 在 Windows 上，符号链接知道它是文件还是目录。
#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
pub trait FileTypeExt: Sealed {
    /// 如果此文件类型是也是目录的符号链接，则返回 `true`。
    #[stable(feature = "windows_file_type_ext", since = "1.64.0")]
    fn is_symlink_dir(&self) -> bool;
    /// 如果此文件类型是也是文件的符号链接，则返回 `true`。
    #[stable(feature = "windows_file_type_ext", since = "1.64.0")]
    fn is_symlink_file(&self) -> bool;
}

#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
impl Sealed for fs::FileType {}

#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
impl FileTypeExt for fs::FileType {
    fn is_symlink_dir(&self) -> bool {
        self.as_inner().is_symlink_dir()
    }
    fn is_symlink_file(&self) -> bool {
        self.as_inner().is_symlink_file()
    }
}

/// [`fs::FileTimes`] 的 Windows 特定扩展。
#[unstable(feature = "file_set_times", issue = "98245")]
pub trait FileTimesExt: Sealed {
    /// 设置文件的创建时间。
    #[unstable(feature = "file_set_times", issue = "98245")]
    fn set_created(self, t: SystemTime) -> Self;
}

#[unstable(feature = "file_set_times", issue = "98245")]
impl FileTimesExt for fs::FileTimes {
    fn set_created(mut self, t: SystemTime) -> Self {
        self.as_inner_mut().set_created(t.into_inner());
        self
    }
}

/// 创建指向文件系统上非目录文件的新符号链接。
///
/// `link` 路径将是指向 `original` 路径的文件符号链接。
///
/// `original` 路径不应是目录或指向目录的符号链接，否则符号链接将被破坏。对目录使用 [`symlink_dir`]。
///
/// 该函数目前对应 [`CreateSymbolicLinkW`][CreateSymbolicLinkW]。
/// 注意这个 [将来可能会发生变化][changes]。
///
/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
/// [changes]: io#platform-specific-behavior
///
/// # Examples
///
/// ```no_run
/// use std::os::windows::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::symlink_file("a.txt", "b.txt")?;
///     Ok(())
/// }
/// ```
///
/// # Limitations
///
/// Windows 将符号链接创建视为 [特权操作][symlink-security]，此除非用户对其系统进行更改以允许创建符号链接，否则此功能可能会失败。
/// 用户可以尝试启用开发者模式、授予 `SeCreateSymbolicLinkPrivilege` 权限或以管理员身份运行进程。
///
/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
///
///
///
///
///
#[stable(feature = "symlink", since = "1.1.0")]
pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    sys::fs::symlink_inner(original.as_ref(), link.as_ref(), false)
}

/// 创建一个指向文件系统目录的新符号链接。
///
/// `link` 路径将是指向 `original` 路径的目录符号链接。
///
/// `original` 路径必须是目录或指向目录的符号链接，否则符号链接将被破坏。对其他文件使用 [`symlink_file`]。
///
/// 该函数目前对应 [`CreateSymbolicLinkW`][CreateSymbolicLinkW]。
/// 注意这个 [将来可能会发生变化][changes]。
///
/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
/// [changes]: io#platform-specific-behavior
///
/// # Examples
///
/// ```no_run
/// use std::os::windows::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::symlink_dir("a", "b")?;
///     Ok(())
/// }
/// ```
///
/// # Limitations
///
/// Windows 将符号链接创建视为 [特权操作][symlink-security]，此除非用户对其系统进行更改以允许创建符号链接，否则此功能可能会失败。
/// 用户可以尝试启用开发者模式、授予 `SeCreateSymbolicLinkPrivilege` 权限或以管理员身份运行进程。
///
/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
///
///
///
///
///
#[stable(feature = "symlink", since = "1.1.0")]
pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true)
}