gnetworkmonitor.c 14.3 KB
Newer Older
1 2 3 4 5 6 7
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright 2011 Red Hat, Inc
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
8
 * version 2.1 of the License, or (at your option) any later version.
9 10 11 12 13 14 15
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
16
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 18 19 20 21 22 23 24 25 26 27 28
 */

#include "config.h"
#include "glib.h"
#include "glibintl.h"

#include "gnetworkmonitor.h"
#include "ginetaddress.h"
#include "ginetsocketaddress.h"
#include "ginitable.h"
#include "gioenumtypes.h"
#include "giomodule-priv.h"
29
#include "gtask.h"
30 31 32 33 34 35

/**
 * SECTION:gnetworkmonitor
 * @title: GNetworkMonitor
 * @short_description: Network status monitor
 * @include: gio/gio.h
36 37
 *
 * #GNetworkMonitor provides an easy-to-use cross-platform API
38 39 40 41
 * for monitoring network connectivity. On Linux, the available
 * implementations are based on the kernel's netlink interface and
 * on NetworkManager.
 *
Krzesimir Nowak's avatar
Krzesimir Nowak committed
42
 * There is also an implementation for use inside Flatpak sandboxes.
43 44 45 46 47 48 49 50 51 52 53
 */

/**
 * GNetworkMonitor:
 *
 * #GNetworkMonitor monitors the status of network connections and
 * indicates when a possibly-user-visible change has occurred.
 *
 * Since: 2.32
 */

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
/**
 * GNetworkMonitorInterface:
 * @g_iface: The parent interface.
 * @network_changed: the virtual function pointer for the
 *  GNetworkMonitor::network-changed signal.
 * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
 * @can_reach_async: the virtual function pointer for
 *  g_network_monitor_can_reach_async()
 * @can_reach_finish: the virtual function pointer for
 *  g_network_monitor_can_reach_finish()
 *
 * The virtual function table for #GNetworkMonitor.
 *
 * Since: 2.32
 */

70
G_DEFINE_INTERFACE_WITH_CODE (GNetworkMonitor, g_network_monitor, G_TYPE_OBJECT,
Matthias Clasen's avatar
Matthias Clasen committed
71
                              g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_INITABLE);)
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93


enum {
  NETWORK_CHANGED,
  LAST_SIGNAL
};

static guint signals[LAST_SIGNAL] = { 0 };

/**
 * g_network_monitor_get_default:
 *
 * Gets the default #GNetworkMonitor for the system.
 *
 * Returns: (transfer none): a #GNetworkMonitor
 *
 * Since: 2.32
 */
GNetworkMonitor *
g_network_monitor_get_default (void)
{
  return _g_io_module_get_default (G_NETWORK_MONITOR_EXTENSION_POINT_NAME,
Matthias Clasen's avatar
Matthias Clasen committed
94 95
                                   "GIO_USE_NETWORK_MONITOR",
                                   NULL);
96 97 98 99 100 101 102 103 104 105 106
}

/**
 * g_network_monitor_get_network_available:
 * @monitor: the #GNetworkMonitor
 *
 * 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.
 *
107
 * Returns: whether the network is available
108 109 110 111 112 113 114 115 116 117 118 119
 *
 * Since: 2.32
 */
gboolean
g_network_monitor_get_network_available (GNetworkMonitor *monitor)
{
  gboolean available = FALSE;

  g_object_get (G_OBJECT (monitor), "network-available", &available, NULL);
  return available;
}

120 121 122 123
/**
 * g_network_monitor_get_network_metered:
 * @monitor: the #GNetworkMonitor
 *
124
 * Checks if the network is metered.
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
 * See #GNetworkMonitor:network-metered for more details.
 *
 * Returns: whether the connection is metered
 *
 * Since: 2.46
 */
gboolean
g_network_monitor_get_network_metered (GNetworkMonitor *monitor)
{
  gboolean metered = FALSE;

  g_object_get (G_OBJECT (monitor), "network-metered", &metered, NULL);
  return metered;
}

140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
/**
 * g_network_monitor_get_connectivity:
 * @monitor: the #GNetworkMonitor
 *
 * 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 %G_NETWORK_CONNECTIVITY_LOCAL.
 *
 * If #GNetworkMonitor:network-available is %TRUE, then the
 * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
 * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
 * the host has a default route, but appears to be unable to actually
 * reach the full Internet), or %G_NETWORK_CONNECTIVITY_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 %G_NETWORK_CONNECTIVITY_LIMITED and
 * %G_NETWORK_CONNECTIVITY_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.
 *
 * Return value: the network connectivity state
 *
166
 * Since: 2.44
167 168 169 170 171 172 173 174 175 176 177
 */
GNetworkConnectivity
g_network_monitor_get_connectivity (GNetworkMonitor *monitor)
{
  GNetworkConnectivity connectivity;

  g_object_get (G_OBJECT (monitor), "connectivity", &connectivity, NULL);

  return connectivity;
}

178 179 180 181
/**
 * g_network_monitor_can_reach:
 * @monitor: a #GNetworkMonitor
 * @connectable: a #GSocketConnectable
182
 * @cancellable: (nullable): a #GCancellable, or %NULL
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
 * @error: return location for a #GError, or %NULL
 *
 * 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, @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().
 *
203
 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
204 205 206 207 208
 *
 * Since: 2.32
 */
gboolean
g_network_monitor_can_reach (GNetworkMonitor     *monitor,
Matthias Clasen's avatar
Matthias Clasen committed
209 210 211
                             GSocketConnectable  *connectable,
                             GCancellable        *cancellable,
                             GError             **error)
212 213 214 215 216 217 218 219 220
{
  GNetworkMonitorInterface *iface;

  iface = G_NETWORK_MONITOR_GET_INTERFACE (monitor);
  return iface->can_reach (monitor, connectable, cancellable, error);
}

static void
g_network_monitor_real_can_reach_async (GNetworkMonitor     *monitor,
Matthias Clasen's avatar
Matthias Clasen committed
221 222 223 224
                                        GSocketConnectable  *connectable,
                                        GCancellable        *cancellable,
                                        GAsyncReadyCallback  callback,
                                        gpointer             user_data)
225
{
226
  GTask *task;
227 228
  GError *error = NULL;

229
  task = g_task_new (monitor, cancellable, callback, user_data);
230 231
  g_task_set_source_tag (task, g_network_monitor_real_can_reach_async);

232
  if (g_network_monitor_can_reach (monitor, connectable, cancellable, &error))
233
    g_task_return_boolean (task, TRUE);
234
  else
235 236
    g_task_return_error (task, error);
  g_object_unref (task);
237 238
}

239 240 241 242
/**
 * g_network_monitor_can_reach_async:
 * @monitor: a #GNetworkMonitor
 * @connectable: a #GSocketConnectable
243
 * @cancellable: (nullable): a #GCancellable, or %NULL
244 245 246 247 248 249 250 251 252 253 254 255 256 257
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
 *     request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * 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.
 */
258 259
void
g_network_monitor_can_reach_async (GNetworkMonitor     *monitor,
Matthias Clasen's avatar
Matthias Clasen committed
260 261 262 263
                                   GSocketConnectable  *connectable,
                                   GCancellable        *cancellable,
                                   GAsyncReadyCallback  callback,
                                   gpointer             user_data)
264 265 266 267 268 269 270 271 272
{
  GNetworkMonitorInterface *iface;

  iface = G_NETWORK_MONITOR_GET_INTERFACE (monitor);
  iface->can_reach_async (monitor, connectable, cancellable, callback, user_data);
}

static gboolean
g_network_monitor_real_can_reach_finish (GNetworkMonitor  *monitor,
Matthias Clasen's avatar
Matthias Clasen committed
273 274
                                         GAsyncResult     *result,
                                         GError          **error)
275
{
276
  g_return_val_if_fail (g_task_is_valid (result, monitor), FALSE);
277

278
  return g_task_propagate_boolean (G_TASK (result), error);
279 280
}

281 282 283 284 285 286 287 288 289
/**
 * g_network_monitor_can_reach_finish:
 * @monitor: a #GNetworkMonitor
 * @result: a #GAsyncResult
 * @error: return location for errors, or %NULL
 *
 * Finishes an async network connectivity test.
 * See g_network_monitor_can_reach_async().
 *
290
 * Returns: %TRUE if network is reachable, %FALSE if not.
291
 */
292 293
gboolean
g_network_monitor_can_reach_finish (GNetworkMonitor     *monitor,
Matthias Clasen's avatar
Matthias Clasen committed
294 295
                                    GAsyncResult        *result,
                                    GError             **error)
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311
{
  GNetworkMonitorInterface *iface;

  iface = G_NETWORK_MONITOR_GET_INTERFACE (monitor);
  return iface->can_reach_finish (monitor, result, error);
}

static void
g_network_monitor_default_init (GNetworkMonitorInterface *iface)
{
  iface->can_reach_async  = g_network_monitor_real_can_reach_async;
  iface->can_reach_finish = g_network_monitor_real_can_reach_finish;

  /**
   * GNetworkMonitor::network-changed:
   * @monitor: a #GNetworkMonitor
312
   * @network_available: the current value of #GNetworkMonitor:network-available
313
   *
314
   * Emitted when the network configuration changes.
315 316 317 318 319
   *
   * Since: 2.32
   */
  signals[NETWORK_CHANGED] =
    g_signal_new (I_("network-changed"),
Matthias Clasen's avatar
Matthias Clasen committed
320 321 322 323 324 325 326
                  G_TYPE_NETWORK_MONITOR,
                  G_SIGNAL_RUN_LAST,
                  G_STRUCT_OFFSET (GNetworkMonitorInterface, network_changed),
                  NULL, NULL,
                  g_cclosure_marshal_VOID__BOOLEAN,
                  G_TYPE_NONE, 1,
                  G_TYPE_BOOLEAN);
327 328 329 330 331 332 333 334 335 336 337 338 339

  /**
   * GNetworkMonitor: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
340 341 342
   * 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
343 344 345 346 347 348 349 350 351
   * %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.
   *
   * Since: 2.32
   */
  g_object_interface_install_property (iface,
Matthias Clasen's avatar
Matthias Clasen committed
352 353 354 355 356
                                       g_param_spec_boolean ("network-available",
                                                             P_("Network available"),
                                                             P_("Whether the network is available"),
                                                             FALSE,
                                                             G_PARAM_READABLE |
357 358 359 360 361 362 363
                                                             G_PARAM_STATIC_STRINGS));

  /**
   * GNetworkMonitor:network-metered:
   *
   * Whether the network is considered metered. That is, whether the
   * system has traffic flowing through the default connection that is
364 365 366 367 368 369
   * 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.
370 371
   *
   * If more information is required about specific devices then the
372 373
   * system network management API should be used instead (for example,
   * NetworkManager or ConnMan).
374
   *
375
   * If this information is not available then no networks will be
376 377
   * marked as metered.
   *
378
   * See also #GNetworkMonitor:network-available.
379 380 381 382 383 384 385 386 387
   *
   * Since: 2.46
   */
  g_object_interface_install_property (iface,
                                       g_param_spec_boolean ("network-metered",
                                                             P_("Network metered"),
                                                             P_("Whether the network is metered"),
                                                             FALSE,
                                                             G_PARAM_READABLE |
Matthias Clasen's avatar
Matthias Clasen committed
388
                                                             G_PARAM_STATIC_STRINGS));
389 390 391 392 393 394 395 396

  /**
   * GNetworkMonitor:connectivity:
   *
   * More detailed information about the host's network connectivity.
   * See g_network_monitor_get_connectivity() and
   * #GNetworkConnectivity for more details.
   *
397
   * Since: 2.44
398 399 400 401 402 403 404 405 406
   */
  g_object_interface_install_property (iface,
                                       g_param_spec_enum ("connectivity",
                                                          P_("Network connectivity"),
                                                          P_("Level of network connectivity"),
                                                          G_TYPE_NETWORK_CONNECTIVITY,
                                                          G_NETWORK_CONNECTIVITY_FULL,
                                                          G_PARAM_READABLE |
                                                          G_PARAM_STATIC_STRINGS));
407
}