GNetworkMonitor

## GNetworkMonitor GNetworkMonitor — Network status monitor |

## Synopsis

    #include <gio/gio.h>

                        GNetworkMonitor;
    struct              GNetworkMonitorInterface;
    #define             G_NETWORK_MONITOR_EXTENSION_POINT_NAME
    GNetworkMonitor *   g_network_monitor_get_default       (void);
    gboolean            g_network_monitor_get_network_available
                                                            (GNetworkMonitor *monitor);
    gboolean            g_network_monitor_can_reach         (GNetworkMonitor *monitor,
                                                             GSocketConnectable *connectable,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_network_monitor_can_reach_async   (GNetworkMonitor *monitor,
                                                             GSocketConnectable *connectable,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            g_network_monitor_can_reach_finish  (GNetworkMonitor *monitor,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GNetworkMonitor

## Prerequisites

GNetworkMonitor requires GInitable and GObject.

## Properties

      "network-available"        gboolean              : Read

## Signals

      "network-changed"                                : Run Last

## Description

GNetworkMonitor provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the implementation is based on the kernel's netlink interface.

## Details

### GNetworkMonitor

    typedef struct _GNetworkMonitor GNetworkMonitor;

GNetworkMonitor monitors the status of network connections and indicates when a possibly-user-visible change has occurred.

Since 2.32

### struct GNetworkMonitorInterface

    struct GNetworkMonitorInterface {
      GTypeInterface g_iface;

      void     (*network_changed)  (GNetworkMonitor      *monitor,
    				gboolean              available);

      gboolean (*can_reach)        (GNetworkMonitor      *monitor,
    				GSocketConnectable   *connectable,
    				GCancellable         *cancellable,
    				GError              **error);
      void     (*can_reach_async)  (GNetworkMonitor      *monitor,
    				GSocketConnectable   *connectable,
    				GCancellable         *cancellable,
    				GAsyncReadyCallback   callback,
    				gpointer              user_data);
      gboolean (*can_reach_finish) (GNetworkMonitor      *monitor,
    				GAsyncResult         *result,
    				GError              **error);
    };

### G_NETWORK_MONITOR_EXTENSION_POINT_NAME

    #define G_NETWORK_MONITOR_EXTENSION_POINT_NAME "gio-network-monitor"

Extension point for network status monitoring functionality. See Extending GIO.

Since 2.30

### g_network_monitor_get_default ()

    GNetworkMonitor *   g_network_monitor_get_default       (void);

Gets the default GNetworkMonitor for the system.

Returns : | a GNetworkMonitor. [transfer none]

Since 2.32

### g_network_monitor_get_network_available ()

    gboolean            g_network_monitor_get_network_available
                                                            (GNetworkMonitor *monitor);

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 "network-available" for more details.

`monitor` : | the GNetworkMonitor
Returns : | whether the network is available

Since 2.32

### g_network_monitor_can_reach ()

    gboolean            g_network_monitor_can_reach         (GNetworkMonitor *monitor,
                                                             GSocketConnectable *connectable,
                                                             GCancellable *cancellable,
                                                             GError **error);

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 "network-available" is `FALSE`, if, for example, `monitor` can determine that `connectable` refers to a host on a local network.

If `monitor` 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 `G_IO_ERROR_HOST_UNREACHABLE`).

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()`.

`monitor` : | a GNetworkMonitor
`connectable` : | a GSocketConnectable
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if `connectable` is reachable, `FALSE` if not.

Since 2.32

### g_network_monitor_can_reach_async ()

    void                g_network_monitor_can_reach_async   (GNetworkMonitor *monitor,
                                                             GSocketConnectable *connectable,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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.

`monitor` : | a GNetworkMonitor
`connectable` : | a GSocketConnectable
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to callback function. [closure]

### g_network_monitor_can_reach_finish ()

    gboolean            g_network_monitor_can_reach_finish  (GNetworkMonitor *monitor,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async network connectivity test. See `g_network_monitor_can_reach_async()`.

`monitor` : | a GNetworkMonitor
`result` : | a GAsyncResult
`error` : | return location for errors, or `NULL`
Returns : | `TRUE` if network is reachable, `FALSE` if not.

## Property Details

### The `"network-available"` property

      "network-available"        gboolean              : Read

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 "network-changed".

Default value: FALSE

Since 2.32

## Signal Details

### The `"network-changed"` signal

    void                user_function                      (GNetworkMonitor *monitor,
                                                            gboolean         available,
                                                            gpointer         user_data)      : Run Last

Emitted when the network configuration changes. If `available` is `TRUE`, then some hosts may be reachable that were not reachable before, while others that were reachable before may no longer be reachable. If `available` is `FALSE`, then no remote hosts are reachable.

`monitor` : | a GNetworkMonitor
`available` : | the current value of "network-available"
`user_data` : | user data set when the signal handler was connected.

Since 2.32