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 {}