interprocess_docfix/local_socket/
name.rs

1use {
2    super::NameTypeSupport,
3    std::{
4        borrow::Cow,
5        ffi::{OsStr, OsString},
6    },
7};
8
9/// A name for a local socket.
10///
11/// Due to vast differences between platforms in terms of how local sockets are named, there needs to be a way to store and process those in a unified way while also retaining platform-specific pecularities. `LocalSocketName` aims to bridge the gap between portability and platform-specific correctness.
12///
13/// # Creation
14/// A separate trait is used to create names from basic strings: [`ToLocalSocketName`](super::ToLocalSocketName). Aside from being conveniently implemented on every single string type in the standard library, it also provides some special processing. Please read its documentation if you haven't already – the rest of this page assumes you did.
15///
16/// # Validity
17/// As mentioned in the [module-level documentation], not all platforms support all types of local socket names. A name pointing to a filesystem location is only supported on Unix-like systems, and names pointing to an abstract namespace reserved specifically for local sockets are only available on Linux and Windows. Due to the diversity of those differences, `LocalSocketName` does not provide any forced validation by itself – the [`is_supported`] and [`is_always_supported`] checks are not enforced to succeed. Instead, they are intended as helpers for the process of user input validation, if any local socket names are ever read from environment variables, configuration files or other methods of user input.
18///
19/// If an invalid local socket name is used to create a local socket or connect to it, the creation/connection method will fail.
20///
21/// [`to_local_socket_name`]: trait.ToLocalSocketName.html " "
22/// [module-level documentation]: index.html " "
23/// [`is_supported`]: #method.is_supported " "
24/// [`is_always_supported`]: #method.is_always_supported " "
25pub struct LocalSocketName<'a> {
26    inner: Cow<'a, OsStr>,
27    namespaced: bool,
28}
29impl<'a> LocalSocketName<'a> {
30    /// Returns `true` if the type of the name is supported by the OS, `false` otherwise.
31    ///
32    /// The check is performed at runtime. For a conservative compile-time check, see [`.is_always_supported`](Self::is_always_supported).
33    pub fn is_supported(&self) -> bool {
34        self.is_supported_in_nts_type(NameTypeSupport::query())
35    }
36    /// Returns `true` if the type of the name is supported by the OS, `false` otherwise.
37    ///
38    /// The check is performed at compile-time. For a check which might return a more permissive result on certain platforms by checking for support at runtime, see [`.is_supported()`](Self::is_supported).
39    pub const fn is_always_supported(&self) -> bool {
40        self.is_supported_in_nts_type(NameTypeSupport::ALWAYS_AVAILABLE)
41    }
42    /// Returns `true` if the type of the name is supported by an OS with the specified name type support class, `false` otherwise.
43    ///
44    /// This is mainly a helper function for [`.is_supported()`](Self::is_supported) and [`.is_always_supported()`](Self::is_always_supported), but there's no good reason not to expose it as a public method, so why not?
45    pub const fn is_supported_in_nts_type(&self, nts: NameTypeSupport) -> bool {
46        (self.is_namespaced() && nts.namespace_supported())
47            || (self.is_path() && nts.paths_supported())
48    }
49    /// Returns `true` if the value is a namespaced name, `false` otherwise.
50    pub const fn is_namespaced(&self) -> bool {
51        self.namespaced
52    }
53    /// Returns `true` if the value is a filesystem path, `false` otherwise.
54    pub const fn is_path(&self) -> bool {
55        !self.namespaced
56    }
57    /// Returns the name as an `OsStr`. The returned value does not retain the type of the name (whether it was a filesystem path or a namespaced name).
58    ///
59    /// If you need the value as an owned `OsString` instead, see [`.into_inner()`](Self::into_inner).
60    pub fn inner(&'a self) -> &'a OsStr {
61        &self.inner
62    }
63    /// Returns the name as an `OsString`. The returned value does not retain the type of the name (whether it was a filesystem path or a namespaced name).
64    ///
65    /// If you need the value as a borrowed `OsStr` instead, see [`.inner()`](Self::inner).
66    pub fn into_inner(self) -> OsString {
67        self.inner.into_owned()
68    }
69    /// Returns the name as a *borrowed* `Cow<'_, OsStr>`. The returned value does not retain the type of the name (whether it was a filesystem path or a namespaced name).
70    ///
71    /// If you need the value as a borrowed `OsStr`, see [`.inner()`](Self::inner); if you need the value as an owned `OsString`, see [`.into_inner()`](Self::into_inner). If you need to take ownership of the `Cow`, see [`.into_inner_cow()`](Self::into_inner_cow).
72    pub const fn inner_cow(&'a self) -> &'a Cow<'a, OsStr> {
73        &self.inner
74    }
75    /// Returns the name as a `Cow<'_, OsStr>`. The returned value does not retain the type of the name (whether it was a filesystem path or a namespaced name).
76    ///
77    /// If you need the value as a borrowed `OsStr`, see [`inner`]; if you need the value as an owned `OsString`, see [`.into_inner()`](Self::into_inner). If you don't need to take ownership of the `Cow`, see [`.inner_cow()`](Self::inner_cow).
78    pub fn into_inner_cow(self) -> Cow<'a, OsStr> {
79        self.inner
80    }
81    pub(crate) const fn from_raw_parts(inner: Cow<'a, OsStr>, namespaced: bool) -> Self {
82        Self { inner, namespaced }
83    }
84}
interprocess_docfix/local_socket/name.rs

interprocess_docfix/local_socket/
name.rs
