gio/auto/
network_address.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, SocketConnectable};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// `GNetworkAddress` provides an easy way to resolve a hostname and
10    /// then attempt to connect to that host, handling the possibility of
11    /// multiple IP addresses and multiple address families.
12    ///
13    /// The enumeration results of resolved addresses *may* be cached as long
14    /// as this object is kept alive which may have unexpected results if
15    /// alive for too long.
16    ///
17    /// See [`SocketConnectable`][crate::SocketConnectable] for an example of using the connectable
18    /// interface.
19    ///
20    /// ## Properties
21    ///
22    ///
23    /// #### `hostname`
24    ///  Hostname to resolve.
25    ///
26    /// Readable | Writeable | Construct Only
27    ///
28    ///
29    /// #### `port`
30    ///  Network port.
31    ///
32    /// Readable | Writeable | Construct Only
33    ///
34    ///
35    /// #### `scheme`
36    ///  URI scheme.
37    ///
38    /// Readable | Writeable | Construct Only
39    ///
40    /// # Implements
41    ///
42    /// [`NetworkAddressExt`][trait@crate::prelude::NetworkAddressExt], [`trait@glib::ObjectExt`], [`SocketConnectableExt`][trait@crate::prelude::SocketConnectableExt]
43    #[doc(alias = "GNetworkAddress")]
44    pub struct NetworkAddress(Object<ffi::GNetworkAddress, ffi::GNetworkAddressClass>) @implements SocketConnectable;
45
46    match fn {
47        type_ => || ffi::g_network_address_get_type(),
48    }
49}
50
51impl NetworkAddress {
52    pub const NONE: Option<&'static NetworkAddress> = None;
53
54    /// Creates a new #GSocketConnectable for connecting to the given
55    /// @hostname and @port.
56    ///
57    /// Note that depending on the configuration of the machine, a
58    /// @hostname of `localhost` may refer to the IPv4 loopback address
59    /// only, or to both IPv4 and IPv6; use
60    /// g_network_address_new_loopback() to create a #GNetworkAddress that
61    /// is guaranteed to resolve to both addresses.
62    /// ## `hostname`
63    /// the hostname
64    /// ## `port`
65    /// the port
66    ///
67    /// # Returns
68    ///
69    /// the new #GNetworkAddress
70    #[doc(alias = "g_network_address_new")]
71    pub fn new(hostname: &str, port: u16) -> NetworkAddress {
72        unsafe { from_glib_full(ffi::g_network_address_new(hostname.to_glib_none().0, port)) }
73    }
74
75    /// Creates a new #GSocketConnectable for connecting to the local host
76    /// over a loopback connection to the given @port. This is intended for
77    /// use in connecting to local services which may be running on IPv4 or
78    /// IPv6.
79    ///
80    /// The connectable will return IPv4 and IPv6 loopback addresses,
81    /// regardless of how the host resolves `localhost`. By contrast,
82    /// g_network_address_new() will often only return an IPv4 address when
83    /// resolving `localhost`, and an IPv6 address for `localhost6`.
84    ///
85    /// g_network_address_get_hostname() will always return `localhost` for
86    /// a #GNetworkAddress created with this constructor.
87    /// ## `port`
88    /// the port
89    ///
90    /// # Returns
91    ///
92    /// the new #GNetworkAddress
93    #[doc(alias = "g_network_address_new_loopback")]
94    pub fn new_loopback(port: u16) -> NetworkAddress {
95        unsafe { from_glib_full(ffi::g_network_address_new_loopback(port)) }
96    }
97
98    /// Creates a new #GSocketConnectable for connecting to the given
99    /// @hostname and @port. May fail and return [`None`] in case
100    /// parsing @host_and_port fails.
101    ///
102    /// @host_and_port may be in any of a number of recognised formats; an IPv6
103    /// address, an IPv4 address, or a domain name (in which case a DNS
104    /// lookup is performed). Quoting with [] is supported for all address
105    /// types. A port override may be specified in the usual way with a
106    /// colon.
107    ///
108    /// If no port is specified in @host_and_port then @default_port will be
109    /// used as the port number to connect to.
110    ///
111    /// In general, @host_and_port is expected to be provided by the user
112    /// (allowing them to give the hostname, and a port override if necessary)
113    /// and @default_port is expected to be provided by the application.
114    ///
115    /// (The port component of @host_and_port can also be specified as a
116    /// service name rather than as a numeric port, but this functionality
117    /// is deprecated, because it depends on the contents of /etc/services,
118    /// which is generally quite sparse on platforms other than Linux.)
119    /// ## `host_and_port`
120    /// the hostname and optionally a port
121    /// ## `default_port`
122    /// the default port if not in @host_and_port
123    ///
124    /// # Returns
125    ///
126    /// the new
127    ///   #GNetworkAddress, or [`None`] on error
128    #[doc(alias = "g_network_address_parse")]
129    pub fn parse(host_and_port: &str, default_port: u16) -> Result<NetworkAddress, glib::Error> {
130        unsafe {
131            let mut error = std::ptr::null_mut();
132            let ret = ffi::g_network_address_parse(
133                host_and_port.to_glib_none().0,
134                default_port,
135                &mut error,
136            );
137            if error.is_null() {
138                Ok(from_glib_full(ret))
139            } else {
140                Err(from_glib_full(error))
141            }
142        }
143    }
144
145    /// Creates a new #GSocketConnectable for connecting to the given
146    /// @uri. May fail and return [`None`] in case parsing @uri fails.
147    ///
148    /// Using this rather than g_network_address_new() or
149    /// g_network_address_parse() allows #GSocketClient to determine
150    /// when to use application-specific proxy protocols.
151    /// ## `uri`
152    /// the hostname and optionally a port
153    /// ## `default_port`
154    /// The default port if none is found in the URI
155    ///
156    /// # Returns
157    ///
158    /// the new
159    ///   #GNetworkAddress, or [`None`] on error
160    #[doc(alias = "g_network_address_parse_uri")]
161    pub fn parse_uri(uri: &str, default_port: u16) -> Result<NetworkAddress, glib::Error> {
162        unsafe {
163            let mut error = std::ptr::null_mut();
164            let ret =
165                ffi::g_network_address_parse_uri(uri.to_glib_none().0, default_port, &mut error);
166            if error.is_null() {
167                Ok(from_glib_full(ret))
168            } else {
169                Err(from_glib_full(error))
170            }
171        }
172    }
173}
174
175unsafe impl Send for NetworkAddress {}
176unsafe impl Sync for NetworkAddress {}
177
178mod sealed {
179    pub trait Sealed {}
180    impl<T: super::IsA<super::NetworkAddress>> Sealed for T {}
181}
182
183/// Trait containing all [`struct@NetworkAddress`] methods.
184///
185/// # Implementors
186///
187/// [`NetworkAddress`][struct@crate::NetworkAddress]
188pub trait NetworkAddressExt: IsA<NetworkAddress> + sealed::Sealed + 'static {
189    /// Gets @self's hostname. This might be either UTF-8 or ASCII-encoded,
190    /// depending on what @self was created with.
191    ///
192    /// # Returns
193    ///
194    /// @self's hostname
195    #[doc(alias = "g_network_address_get_hostname")]
196    #[doc(alias = "get_hostname")]
197    fn hostname(&self) -> glib::GString {
198        unsafe {
199            from_glib_none(ffi::g_network_address_get_hostname(
200                self.as_ref().to_glib_none().0,
201            ))
202        }
203    }
204
205    /// Gets @self's port number
206    ///
207    /// # Returns
208    ///
209    /// @self's port (which may be 0)
210    #[doc(alias = "g_network_address_get_port")]
211    #[doc(alias = "get_port")]
212    fn port(&self) -> u16 {
213        unsafe { ffi::g_network_address_get_port(self.as_ref().to_glib_none().0) }
214    }
215
216    /// Gets @self's scheme
217    ///
218    /// # Returns
219    ///
220    /// @self's scheme ([`None`] if not built from URI)
221    #[doc(alias = "g_network_address_get_scheme")]
222    #[doc(alias = "get_scheme")]
223    fn scheme(&self) -> Option<glib::GString> {
224        unsafe {
225            from_glib_none(ffi::g_network_address_get_scheme(
226                self.as_ref().to_glib_none().0,
227            ))
228        }
229    }
230}
231
232impl<O: IsA<NetworkAddress>> NetworkAddressExt for O {}