From 04803a2bae8253c96252e19c08154ccfd37daf8b Mon Sep 17 00:00:00 2001 From: Thomas Haller Date: Mon, 12 Aug 2019 13:52:19 +0200 Subject: [PATCH] libnm/doc: clarify NMMetered enum and how metered state in NetworkManager works --- libnm-core/nm-dbus-interface.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/libnm-core/nm-dbus-interface.h b/libnm-core/nm-dbus-interface.h index d74ea2ba2..089b2ab7f 100644 --- a/libnm-core/nm-dbus-interface.h +++ b/libnm-core/nm-dbus-interface.h @@ -658,6 +658,33 @@ typedef enum { * @NM_METERED_GUESS_YES: Metered, the value was guessed * @NM_METERED_GUESS_NO: Not metered, the value was guessed * + * The NMMetered enum has two different purposes: one is to configure + * "connection.metered" setting of a connection profile, and the other is + * to express the actual metered state of the device at a given moment. + * + * For the connection profile only %NM_METERED_UNKNOWN, %NM_METERED_NO + * and %NM_METERED_YES are allowed. + * + * The device's metered state at runtime is determined by the profile + * which is currently active. If the profile explicitly specifies %NM_METERED_NO + * or %NM_METERED_YES, then the device's metered state is as such. + * If the connection profile leaves it undecided at %NM_METERED_UNKNOWN (the default), + * then NetworkManager tries to guess the metered state, for example based on the + * device type or on DHCP options (like Android devices exposing a "ANDROID_METERED" + * DHCP vendor option). + * + * Most applications probably should treat the runtime states %NM_METERED_GUESS_YES + * like %NM_METERED_YES, and all other states as not metered. + * + * Note that the per-device metered states are then combined to a global metered + * state. This is basically the metered state of the device with the best default + * route. However, that generalization of a global metered state may not be correct + * if the default routes for IPv4 and IPv6 are on different devices, or if policy + * routing is configured. In general, the global metered state tries to express whether + * the traffic is likely metered, but since that depends on the traffic itself, + * there is not one answer in all cases. Hance, an application may want to consider + * the per-device's metered states. + * * Since: 1.2 **/ NM_AVAILABLE_IN_1_2