GIO Reference Manual: GNetworkMonitor

## GNetworkMonitor GNetworkMonitor — Network status monitor |

## Functions

GNetworkMonitor * | g_network_monitor_get_default ()
gboolean | g_network_monitor_get_network_available ()
gboolean | g_network_monitor_can_reach ()
void | g_network_monitor_can_reach_async ()
gboolean | g_network_monitor_can_reach_finish ()

## Properties

gboolean | network-available | Read

## Signals

void | network-changed | Run Last

## Types and Values

| GNetworkMonitor
struct | GNetworkMonitorInterface
#define | G_NETWORK_MONITOR_EXTENSION_POINT_NAME

## Object Hierarchy

        GInterface
        ╰── GNetworkMonitor

## Prerequisites

GNetworkMonitor requires GInitable and GObject.

## Includes

    #include <gio/gio.h>

## 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.

## Functions

### 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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

monitor | a GNetworkMonitor |
result | a GAsyncResult |
error | return location for errors, or `NULL` |

#### Returns

`TRUE` if network is reachable, `FALSE` if not.

## Types and Values

### 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

## Property Details

### The `“network-available”` property

      “network-available”        gboolean

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”.

Flags: Read

Default value: FALSE

Since 2.32

## Signal Details

### The `“network-changed”` signal

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

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.

#### Parameters

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

Flags: Run Last

Since 2.32