gio/auto/network_monitor.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, AsyncResult, Cancellable, Initable, NetworkConnectivity, SocketConnectable};
6use glib::{
7 object::ObjectType as _,
8 prelude::*,
9 signal::{connect_raw, SignalHandlerId},
10 translate::*,
11};
12use std::{boxed::Box as Box_, pin::Pin};
13
14glib::wrapper! {
15 /// `GNetworkMonitor` provides an easy-to-use cross-platform API
16 /// for monitoring network connectivity. On Linux, the available
17 /// implementations are based on the kernel's netlink interface and
18 /// on NetworkManager.
19 ///
20 /// There is also an implementation for use inside Flatpak sandboxes.
21 ///
22 /// ## Properties
23 ///
24 ///
25 /// #### `connectivity`
26 /// More detailed information about the host's network connectivity.
27 /// See g_network_monitor_get_connectivity() and
28 /// #GNetworkConnectivity for more details.
29 ///
30 /// Readable
31 ///
32 ///
33 /// #### `network-available`
34 /// Whether the network is considered available. That is, whether the
35 /// system has a default route for at least one of IPv4 or IPv6.
36 ///
37 /// Real-world networks are of course much more complicated than
38 /// this; the machine may be connected to a wifi hotspot that
39 /// requires payment before allowing traffic through, or may be
40 /// connected to a functioning router that has lost its own upstream
41 /// connectivity. Some hosts might only be accessible when a VPN is
42 /// active. Other hosts might only be accessible when the VPN is
43 /// not active. Thus, it is best to use g_network_monitor_can_reach()
44 /// or g_network_monitor_can_reach_async() to test for reachability
45 /// on a host-by-host basis. (On the other hand, when the property is
46 /// [`false`], the application can reasonably expect that no remote
47 /// hosts at all are reachable, and should indicate this to the user
48 /// in its UI.)
49 ///
50 /// See also #GNetworkMonitor::network-changed.
51 ///
52 /// Readable
53 ///
54 ///
55 /// #### `network-metered`
56 /// Whether the network is considered metered.
57 ///
58 /// That is, whether the
59 /// system has traffic flowing through the default connection that is
60 /// subject to limitations set by service providers. For example, traffic
61 /// might be billed by the amount of data transmitted, or there might be a
62 /// quota on the amount of traffic per month. This is typical with tethered
63 /// connections (3G and 4G) and in such situations, bandwidth intensive
64 /// applications may wish to avoid network activity where possible if it will
65 /// cost the user money or use up their limited quota. Anything more than a
66 /// few hundreds of kilobytes of data usage per hour should be avoided without
67 /// asking permission from the user.
68 ///
69 /// If more information is required about specific devices then the
70 /// system network management API should be used instead (for example,
71 /// NetworkManager or ConnMan).
72 ///
73 /// If this information is not available then no networks will be
74 /// marked as metered.
75 ///
76 /// See also #GNetworkMonitor:network-available.
77 ///
78 /// Readable
79 ///
80 /// ## Signals
81 ///
82 ///
83 /// #### `network-changed`
84 /// Emitted when the network configuration changes.
85 ///
86 ///
87 ///
88 /// # Implements
89 ///
90 /// [`NetworkMonitorExt`][trait@crate::prelude::NetworkMonitorExt], [`InitableExt`][trait@crate::prelude::InitableExt]
91 #[doc(alias = "GNetworkMonitor")]
92 pub struct NetworkMonitor(Interface<ffi::GNetworkMonitor, ffi::GNetworkMonitorInterface>) @requires Initable;
93
94 match fn {
95 type_ => || ffi::g_network_monitor_get_type(),
96 }
97}
98
99impl NetworkMonitor {
100 pub const NONE: Option<&'static NetworkMonitor> = None;
101
102 /// Gets the default #GNetworkMonitor for the system.
103 ///
104 /// # Returns
105 ///
106 /// a #GNetworkMonitor, which will be
107 /// a dummy object if no network monitor is available
108 #[doc(alias = "g_network_monitor_get_default")]
109 #[doc(alias = "get_default")]
110 #[allow(clippy::should_implement_trait)]
111 pub fn default() -> NetworkMonitor {
112 unsafe { from_glib_none(ffi::g_network_monitor_get_default()) }
113 }
114}
115
116mod sealed {
117 pub trait Sealed {}
118 impl<T: super::IsA<super::NetworkMonitor>> Sealed for T {}
119}
120
121/// Trait containing all [`struct@NetworkMonitor`] methods.
122///
123/// # Implementors
124///
125/// [`NetworkMonitor`][struct@crate::NetworkMonitor]
126pub trait NetworkMonitorExt: IsA<NetworkMonitor> + sealed::Sealed + 'static {
127 /// Attempts to determine whether or not the host pointed to by
128 /// @connectable can be reached, without actually trying to connect to
129 /// it.
130 ///
131 /// This may return [`true`] even when #GNetworkMonitor:network-available
132 /// is [`false`], if, for example, @self can determine that
133 /// @connectable refers to a host on a local network.
134 ///
135 /// If @self believes that an attempt to connect to @connectable
136 /// will succeed, it will return [`true`]. Otherwise, it will return
137 /// [`false`] and set @error to an appropriate error (such as
138 /// [`IOErrorEnum::HostUnreachable`][crate::IOErrorEnum::HostUnreachable]).
139 ///
140 /// Note that although this does not attempt to connect to
141 /// @connectable, it may still block for a brief period of time (eg,
142 /// trying to do multicast DNS on the local network), so if you do not
143 /// want to block, you should use g_network_monitor_can_reach_async().
144 /// ## `connectable`
145 /// a #GSocketConnectable
146 /// ## `cancellable`
147 /// a #GCancellable, or [`None`]
148 ///
149 /// # Returns
150 ///
151 /// [`true`] if @connectable is reachable, [`false`] if not.
152 #[doc(alias = "g_network_monitor_can_reach")]
153 fn can_reach(
154 &self,
155 connectable: &impl IsA<SocketConnectable>,
156 cancellable: Option<&impl IsA<Cancellable>>,
157 ) -> Result<(), glib::Error> {
158 unsafe {
159 let mut error = std::ptr::null_mut();
160 let is_ok = ffi::g_network_monitor_can_reach(
161 self.as_ref().to_glib_none().0,
162 connectable.as_ref().to_glib_none().0,
163 cancellable.map(|p| p.as_ref()).to_glib_none().0,
164 &mut error,
165 );
166 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
167 if error.is_null() {
168 Ok(())
169 } else {
170 Err(from_glib_full(error))
171 }
172 }
173 }
174
175 /// Asynchronously attempts to determine whether or not the host
176 /// pointed to by @connectable can be reached, without actually
177 /// trying to connect to it.
178 ///
179 /// For more details, see g_network_monitor_can_reach().
180 ///
181 /// When the operation is finished, @callback will be called.
182 /// You can then call g_network_monitor_can_reach_finish()
183 /// to get the result of the operation.
184 /// ## `connectable`
185 /// a #GSocketConnectable
186 /// ## `cancellable`
187 /// a #GCancellable, or [`None`]
188 /// ## `callback`
189 /// a #GAsyncReadyCallback
190 /// to call when the request is satisfied
191 #[doc(alias = "g_network_monitor_can_reach_async")]
192 fn can_reach_async<P: FnOnce(Result<(), glib::Error>) + 'static>(
193 &self,
194 connectable: &impl IsA<SocketConnectable>,
195 cancellable: Option<&impl IsA<Cancellable>>,
196 callback: P,
197 ) {
198 let main_context = glib::MainContext::ref_thread_default();
199 let is_main_context_owner = main_context.is_owner();
200 let has_acquired_main_context = (!is_main_context_owner)
201 .then(|| main_context.acquire().ok())
202 .flatten();
203 assert!(
204 is_main_context_owner || has_acquired_main_context.is_some(),
205 "Async operations only allowed if the thread is owning the MainContext"
206 );
207
208 let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
209 Box_::new(glib::thread_guard::ThreadGuard::new(callback));
210 unsafe extern "C" fn can_reach_async_trampoline<
211 P: FnOnce(Result<(), glib::Error>) + 'static,
212 >(
213 _source_object: *mut glib::gobject_ffi::GObject,
214 res: *mut crate::ffi::GAsyncResult,
215 user_data: glib::ffi::gpointer,
216 ) {
217 let mut error = std::ptr::null_mut();
218 let _ =
219 ffi::g_network_monitor_can_reach_finish(_source_object as *mut _, res, &mut error);
220 let result = if error.is_null() {
221 Ok(())
222 } else {
223 Err(from_glib_full(error))
224 };
225 let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
226 Box_::from_raw(user_data as *mut _);
227 let callback: P = callback.into_inner();
228 callback(result);
229 }
230 let callback = can_reach_async_trampoline::<P>;
231 unsafe {
232 ffi::g_network_monitor_can_reach_async(
233 self.as_ref().to_glib_none().0,
234 connectable.as_ref().to_glib_none().0,
235 cancellable.map(|p| p.as_ref()).to_glib_none().0,
236 Some(callback),
237 Box_::into_raw(user_data) as *mut _,
238 );
239 }
240 }
241
242 fn can_reach_future(
243 &self,
244 connectable: &(impl IsA<SocketConnectable> + Clone + 'static),
245 ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
246 let connectable = connectable.clone();
247 Box_::pin(crate::GioFuture::new(
248 self,
249 move |obj, cancellable, send| {
250 obj.can_reach_async(&connectable, Some(cancellable), move |res| {
251 send.resolve(res);
252 });
253 },
254 ))
255 }
256
257 /// Gets a more detailed networking state than
258 /// g_network_monitor_get_network_available().
259 ///
260 /// If #GNetworkMonitor:network-available is [`false`], then the
261 /// connectivity state will be [`NetworkConnectivity::Local`][crate::NetworkConnectivity::Local].
262 ///
263 /// If #GNetworkMonitor:network-available is [`true`], then the
264 /// connectivity state will be [`NetworkConnectivity::Full`][crate::NetworkConnectivity::Full] (if there
265 /// is full Internet connectivity), [`NetworkConnectivity::Limited`][crate::NetworkConnectivity::Limited] (if
266 /// the host has a default route, but appears to be unable to actually
267 /// reach the full Internet), or [`NetworkConnectivity::Portal`][crate::NetworkConnectivity::Portal] (if the
268 /// host is trapped behind a "captive portal" that requires some sort
269 /// of login or acknowledgement before allowing full Internet access).
270 ///
271 /// Note that in the case of [`NetworkConnectivity::Limited`][crate::NetworkConnectivity::Limited] and
272 /// [`NetworkConnectivity::Portal`][crate::NetworkConnectivity::Portal], it is possible that some sites are
273 /// reachable but others are not. In this case, applications can
274 /// attempt to connect to remote servers, but should gracefully fall
275 /// back to their "offline" behavior if the connection attempt fails.
276 ///
277 /// # Returns
278 ///
279 /// the network connectivity state
280 #[doc(alias = "g_network_monitor_get_connectivity")]
281 #[doc(alias = "get_connectivity")]
282 fn connectivity(&self) -> NetworkConnectivity {
283 unsafe {
284 from_glib(ffi::g_network_monitor_get_connectivity(
285 self.as_ref().to_glib_none().0,
286 ))
287 }
288 }
289
290 /// Checks if the network is available. "Available" here means that the
291 /// system has a default route available for at least one of IPv4 or
292 /// IPv6. It does not necessarily imply that the public Internet is
293 /// reachable. See #GNetworkMonitor:network-available for more details.
294 ///
295 /// # Returns
296 ///
297 /// whether the network is available
298 #[doc(alias = "g_network_monitor_get_network_available")]
299 #[doc(alias = "get_network_available")]
300 #[doc(alias = "network-available")]
301 fn is_network_available(&self) -> bool {
302 unsafe {
303 from_glib(ffi::g_network_monitor_get_network_available(
304 self.as_ref().to_glib_none().0,
305 ))
306 }
307 }
308
309 /// Checks if the network is metered.
310 /// See #GNetworkMonitor:network-metered for more details.
311 ///
312 /// # Returns
313 ///
314 /// whether the connection is metered
315 #[doc(alias = "g_network_monitor_get_network_metered")]
316 #[doc(alias = "get_network_metered")]
317 #[doc(alias = "network-metered")]
318 fn is_network_metered(&self) -> bool {
319 unsafe {
320 from_glib(ffi::g_network_monitor_get_network_metered(
321 self.as_ref().to_glib_none().0,
322 ))
323 }
324 }
325
326 /// Emitted when the network configuration changes.
327 /// ## `network_available`
328 /// the current value of #GNetworkMonitor:network-available
329 #[doc(alias = "network-changed")]
330 fn connect_network_changed<F: Fn(&Self, bool) + 'static>(&self, f: F) -> SignalHandlerId {
331 unsafe extern "C" fn network_changed_trampoline<
332 P: IsA<NetworkMonitor>,
333 F: Fn(&P, bool) + 'static,
334 >(
335 this: *mut ffi::GNetworkMonitor,
336 network_available: glib::ffi::gboolean,
337 f: glib::ffi::gpointer,
338 ) {
339 let f: &F = &*(f as *const F);
340 f(
341 NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref(),
342 from_glib(network_available),
343 )
344 }
345 unsafe {
346 let f: Box_<F> = Box_::new(f);
347 connect_raw(
348 self.as_ptr() as *mut _,
349 b"network-changed\0".as_ptr() as *const _,
350 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
351 network_changed_trampoline::<Self, F> as *const (),
352 )),
353 Box_::into_raw(f),
354 )
355 }
356 }
357
358 #[doc(alias = "connectivity")]
359 fn connect_connectivity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
360 unsafe extern "C" fn notify_connectivity_trampoline<
361 P: IsA<NetworkMonitor>,
362 F: Fn(&P) + 'static,
363 >(
364 this: *mut ffi::GNetworkMonitor,
365 _param_spec: glib::ffi::gpointer,
366 f: glib::ffi::gpointer,
367 ) {
368 let f: &F = &*(f as *const F);
369 f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
370 }
371 unsafe {
372 let f: Box_<F> = Box_::new(f);
373 connect_raw(
374 self.as_ptr() as *mut _,
375 b"notify::connectivity\0".as_ptr() as *const _,
376 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
377 notify_connectivity_trampoline::<Self, F> as *const (),
378 )),
379 Box_::into_raw(f),
380 )
381 }
382 }
383
384 #[doc(alias = "network-available")]
385 fn connect_network_available_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
386 unsafe extern "C" fn notify_network_available_trampoline<
387 P: IsA<NetworkMonitor>,
388 F: Fn(&P) + 'static,
389 >(
390 this: *mut ffi::GNetworkMonitor,
391 _param_spec: glib::ffi::gpointer,
392 f: glib::ffi::gpointer,
393 ) {
394 let f: &F = &*(f as *const F);
395 f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
396 }
397 unsafe {
398 let f: Box_<F> = Box_::new(f);
399 connect_raw(
400 self.as_ptr() as *mut _,
401 b"notify::network-available\0".as_ptr() as *const _,
402 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
403 notify_network_available_trampoline::<Self, F> as *const (),
404 )),
405 Box_::into_raw(f),
406 )
407 }
408 }
409
410 #[doc(alias = "network-metered")]
411 fn connect_network_metered_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
412 unsafe extern "C" fn notify_network_metered_trampoline<
413 P: IsA<NetworkMonitor>,
414 F: Fn(&P) + 'static,
415 >(
416 this: *mut ffi::GNetworkMonitor,
417 _param_spec: glib::ffi::gpointer,
418 f: glib::ffi::gpointer,
419 ) {
420 let f: &F = &*(f as *const F);
421 f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
422 }
423 unsafe {
424 let f: Box_<F> = Box_::new(f);
425 connect_raw(
426 self.as_ptr() as *mut _,
427 b"notify::network-metered\0".as_ptr() as *const _,
428 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
429 notify_network_metered_trampoline::<Self, F> as *const (),
430 )),
431 Box_::into_raw(f),
432 )
433 }
434 }
435}
436
437impl<O: IsA<NetworkMonitor>> NetworkMonitorExt for O {}