gio/auto/

network_monitor.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{AsyncResult, Cancellable, Initable, NetworkConnectivity, SocketConnectable, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::{boxed::Box as Box_, pin::Pin};

glib::wrapper! {
    /// `GNetworkMonitor` provides an easy-to-use cross-platform API
    /// for monitoring network connectivity. On Linux, the available
    /// implementations are based on the kernel's netlink interface and
    /// on NetworkManager.
    ///
    /// There is also an implementation for use inside Flatpak sandboxes.
    ///
    /// ## Properties
    ///
    ///
    /// #### `connectivity`
    ///  More detailed information about the host's network connectivity.
    /// See g_network_monitor_get_connectivity() and
    /// #GNetworkConnectivity for more details.
    ///
    /// Readable
    ///
    ///
    /// #### `network-available`
    ///  Whether the network is considered available. That is, whether the
    /// system has a default route for at least one of IPv4 or IPv6.
    ///
    /// Real-world networks are of course much more complicated than
    /// this; the machine may be connected to a wifi hotspot that
    /// requires payment before allowing traffic through, or may be
    /// connected to a functioning router that has lost its own upstream
    /// connectivity. Some hosts might only be accessible when a VPN is
    /// active. Other hosts might only be accessible when the VPN is
    /// not active. Thus, it is best to use g_network_monitor_can_reach()
    /// or g_network_monitor_can_reach_async() to test for reachability
    /// on a host-by-host basis. (On the other hand, when the property is
    /// [`false`], the application can reasonably expect that no remote
    /// hosts at all are reachable, and should indicate this to the user
    /// in its UI.)
    ///
    /// See also #GNetworkMonitor::network-changed.
    ///
    /// Readable
    ///
    ///
    /// #### `network-metered`
    ///  Whether the network is considered metered.
    ///
    /// That is, whether the
    /// system has traffic flowing through the default connection that is
    /// subject to limitations set by service providers. For example, traffic
    /// might be billed by the amount of data transmitted, or there might be a
    /// quota on the amount of traffic per month. This is typical with tethered
    /// connections (3G and 4G) and in such situations, bandwidth intensive
    /// applications may wish to avoid network activity where possible if it will
    /// cost the user money or use up their limited quota. Anything more than a
    /// few hundreds of kilobytes of data usage per hour should be avoided without
    /// asking permission from the user.
    ///
    /// If more information is required about specific devices then the
    /// system network management API should be used instead (for example,
    /// NetworkManager or ConnMan).
    ///
    /// If this information is not available then no networks will be
    /// marked as metered.
    ///
    /// See also #GNetworkMonitor:network-available.
    ///
    /// Readable
    ///
    /// ## Signals
    ///
    ///
    /// #### `network-changed`
    ///  Emitted when the network configuration changes.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`NetworkMonitorExt`][trait@crate::prelude::NetworkMonitorExt], [`InitableExt`][trait@crate::prelude::InitableExt]
    #[doc(alias = "GNetworkMonitor")]
    pub struct NetworkMonitor(Interface<ffi::GNetworkMonitor, ffi::GNetworkMonitorInterface>) @requires Initable;

    match fn {
        type_ => || ffi::g_network_monitor_get_type(),
    }
}

impl NetworkMonitor {
    pub const NONE: Option<&'static NetworkMonitor> = None;

    /// Gets the default #GNetworkMonitor for the system.
    ///
    /// Some implementations complete their initialization asynchronously:
    /// properties such as #GNetworkMonitor:network-available may start at their
    /// default values and update shortly afterwards, with notify emissions, once
    /// the state is resolved from the thread-default main context of this first
    /// call.
    ///
    /// # Returns
    ///
    /// a #GNetworkMonitor, which will be
    ///     a dummy object if no network monitor is available
    #[doc(alias = "g_network_monitor_get_default")]
    #[doc(alias = "get_default")]
    #[allow(clippy::should_implement_trait)]
    pub fn default() -> NetworkMonitor {
        unsafe { from_glib_none(ffi::g_network_monitor_get_default()) }
    }
}

/// Trait containing all [`struct@NetworkMonitor`] methods.
///
/// # Implementors
///
/// [`NetworkMonitor`][struct@crate::NetworkMonitor]
pub trait NetworkMonitorExt: IsA<NetworkMonitor> + 'static {
    /// Attempts to determine whether or not the host pointed to by
    /// @connectable can be reached, without actually trying to connect to
    /// it.
    ///
    /// This may return [`true`] even when #GNetworkMonitor:network-available
    /// is [`false`], if, for example, @self can determine that
    /// @connectable refers to a host on a local network.
    ///
    /// If @self believes that an attempt to connect to @connectable
    /// will succeed, it will return [`true`]. Otherwise, it will return
    /// [`false`] and set @error to an appropriate error (such as
    /// [`IOErrorEnum::HostUnreachable`][crate::IOErrorEnum::HostUnreachable]).
    ///
    /// Note that although this does not attempt to connect to
    /// @connectable, it may still block for a brief period of time (eg,
    /// trying to do multicast DNS on the local network), so if you do not
    /// want to block, you should use g_network_monitor_can_reach_async().
    /// ## `connectable`
    /// a #GSocketConnectable
    /// ## `cancellable`
    /// a #GCancellable, or [`None`]
    ///
    /// # Returns
    ///
    /// [`true`] if @connectable is reachable, [`false`] if not.
    #[doc(alias = "g_network_monitor_can_reach")]
    fn can_reach(
        &self,
        connectable: &impl IsA<SocketConnectable>,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_network_monitor_can_reach(
                self.as_ref().to_glib_none().0,
                connectable.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Asynchronously attempts to determine whether or not the host
    /// pointed to by @connectable can be reached, without actually
    /// trying to connect to it.
    ///
    /// For more details, see g_network_monitor_can_reach().
    ///
    /// When the operation is finished, @callback will be called.
    /// You can then call g_network_monitor_can_reach_finish()
    /// to get the result of the operation.
    /// ## `connectable`
    /// a #GSocketConnectable
    /// ## `cancellable`
    /// a #GCancellable, or [`None`]
    /// ## `callback`
    /// a #GAsyncReadyCallback
    ///     to call when the request is satisfied
    #[doc(alias = "g_network_monitor_can_reach_async")]
    fn can_reach_async<P: FnOnce(Result<(), glib::Error>) + 'static>(
        &self,
        connectable: &impl IsA<SocketConnectable>,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn can_reach_async_trampoline<
            P: FnOnce(Result<(), glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            unsafe {
                let mut error = std::ptr::null_mut();
                ffi::g_network_monitor_can_reach_finish(_source_object as *mut _, res, &mut error);
                let result = if error.is_null() {
                    Ok(())
                } else {
                    Err(from_glib_full(error))
                };
                let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                    Box_::from_raw(user_data as *mut _);
                let callback: P = callback.into_inner();
                callback(result);
            }
        }
        let callback = can_reach_async_trampoline::<P>;
        unsafe {
            ffi::g_network_monitor_can_reach_async(
                self.as_ref().to_glib_none().0,
                connectable.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    fn can_reach_future(
        &self,
        connectable: &(impl IsA<SocketConnectable> + Clone + 'static),
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
        let connectable = connectable.clone();
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.can_reach_async(&connectable, Some(cancellable), move |res| {
                    send.resolve(res);
                });
            },
        ))
    }

    /// Gets a more detailed networking state than
    /// g_network_monitor_get_network_available().
    ///
    /// If #GNetworkMonitor:network-available is [`false`], then the
    /// connectivity state will be [`NetworkConnectivity::Local`][crate::NetworkConnectivity::Local].
    ///
    /// If #GNetworkMonitor:network-available is [`true`], then the
    /// connectivity state will be [`NetworkConnectivity::Full`][crate::NetworkConnectivity::Full] (if there
    /// is full Internet connectivity), [`NetworkConnectivity::Limited`][crate::NetworkConnectivity::Limited] (if
    /// the host has a default route, but appears to be unable to actually
    /// reach the full Internet), or [`NetworkConnectivity::Portal`][crate::NetworkConnectivity::Portal] (if the
    /// host is trapped behind a "captive portal" that requires some sort
    /// of login or acknowledgement before allowing full Internet access).
    ///
    /// Note that in the case of [`NetworkConnectivity::Limited`][crate::NetworkConnectivity::Limited] and
    /// [`NetworkConnectivity::Portal`][crate::NetworkConnectivity::Portal], it is possible that some sites are
    /// reachable but others are not. In this case, applications can
    /// attempt to connect to remote servers, but should gracefully fall
    /// back to their "offline" behavior if the connection attempt fails.
    ///
    /// # Returns
    ///
    /// the network connectivity state
    #[doc(alias = "g_network_monitor_get_connectivity")]
    #[doc(alias = "get_connectivity")]
    fn connectivity(&self) -> NetworkConnectivity {
        unsafe {
            from_glib(ffi::g_network_monitor_get_connectivity(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if the network is available. "Available" here means that the
    /// system has a default route available for at least one of IPv4 or
    /// IPv6. It does not necessarily imply that the public Internet is
    /// reachable. See #GNetworkMonitor:network-available for more details.
    ///
    /// # Returns
    ///
    /// whether the network is available
    #[doc(alias = "g_network_monitor_get_network_available")]
    #[doc(alias = "get_network_available")]
    #[doc(alias = "network-available")]
    fn is_network_available(&self) -> bool {
        unsafe {
            from_glib(ffi::g_network_monitor_get_network_available(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if the network is metered.
    /// See #GNetworkMonitor:network-metered for more details.
    ///
    /// # Returns
    ///
    /// whether the connection is metered
    #[doc(alias = "g_network_monitor_get_network_metered")]
    #[doc(alias = "get_network_metered")]
    #[doc(alias = "network-metered")]
    fn is_network_metered(&self) -> bool {
        unsafe {
            from_glib(ffi::g_network_monitor_get_network_metered(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Emitted when the network configuration changes.
    /// ## `network_available`
    /// the current value of #GNetworkMonitor:network-available
    #[doc(alias = "network-changed")]
    fn connect_network_changed<F: Fn(&Self, bool) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn network_changed_trampoline<
            P: IsA<NetworkMonitor>,
            F: Fn(&P, bool) + 'static,
        >(
            this: *mut ffi::GNetworkMonitor,
            network_available: glib::ffi::gboolean,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref(),
                    from_glib(network_available),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"network-changed".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    network_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "connectivity")]
    fn connect_connectivity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_connectivity_trampoline<
            P: IsA<NetworkMonitor>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GNetworkMonitor,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::connectivity".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_connectivity_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "network-available")]
    fn connect_network_available_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_network_available_trampoline<
            P: IsA<NetworkMonitor>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GNetworkMonitor,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::network-available".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_network_available_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "network-metered")]
    fn connect_network_metered_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_network_metered_trampoline<
            P: IsA<NetworkMonitor>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GNetworkMonitor,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(NetworkMonitor::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::network-metered".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_network_metered_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<NetworkMonitor>> NetworkMonitorExt for O {}