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