//! Linux 和特定于 Android 的套接字地址扩展。

use crate::os::unix::net::SocketAddr;
use crate::sealed::Sealed;

/// [`SocketAddr`] 的平台特定扩展。
#[stable(feature = "unix_socket_abstract", since = "1.70.0")]
pub trait SocketAddrExt: Sealed {
    /// 在抽象命名空间中创建一个 Unix 套接字地址。
    ///
    /// 抽象名称空间是特定于 Linux 的扩展，它允许在不在文件系统中创建条目的情况下绑定 Unix 套接字。
    ///
    /// 抽象套接字不受文件系统布局或权限的影响，并且在套接字关闭时不需要清理。
    ///
    /// 抽象套接字地址名称可以包含任何字节，包括零。
    ///
    /// # Errors
    ///
    /// 如果名称长于 `SUN_LEN - 1`，则返回错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::os::unix::net::{UnixListener, SocketAddr};
    /// use std::os::linux::net::SocketAddrExt;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let addr = SocketAddr::from_abstract_name(b"hidden")?;
    ///     let listener = match UnixListener::bind_addr(&addr) {
    ///         Ok(sock) => sock,
    ///         Err(err) => {
    ///             println!("Couldn't bind: {err:?}");
    ///             return Err(err);
    ///         }
    ///     };
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "unix_socket_abstract", since = "1.70.0")]
    fn from_abstract_name<N>(name: N) -> crate::io::Result<SocketAddr>
    where
        N: AsRef<[u8]>;

    /// 如果该地址位于抽象命名空间中，则返回该地址的内容。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::os::unix::net::{UnixListener, SocketAddr};
    /// use std::os::linux::net::SocketAddrExt;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let name = b"hidden";
    ///     let name_addr = SocketAddr::from_abstract_name(name)?;
    ///     let socket = UnixListener::bind_addr(&name_addr)?;
    ///     let local_addr = socket.local_addr().expect("Couldn't get local address");
    ///     assert_eq!(local_addr.as_abstract_name(), Some(&name[..]));
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "unix_socket_abstract", since = "1.70.0")]
    fn as_abstract_name(&self) -> Option<&[u8]>;
}