libnm: export nm_utils_wifi_freq_to_band()

Clients typically want to show the band of an AP. The information is
already available because we export the frequency, but it is necessary
to implement some conversion logic.

Export libnm symbol nm_utils_wifi_freq_to_band() to do
that. Previously the function was used internally to generate the
value of the "band" string property from the frequency. For a public
function it is clearer if we return a enum value.

src/core/devices/wifi/nm-wifi-ap.c

@@ -621,7 +621,7 @@ nm_wifi_ap_check_compatible(NMWifiAP *self, NMConnection *connection)
 
     band = nm_setting_wireless_get_band(s_wireless);
     if (band) {
-        const char *ap_band = nm_utils_wifi_freq_to_band(priv->freq);
+        const char *ap_band = nm_wifi_freq_to_band_prop(priv->freq);
 
         if (!nm_streq(band, ap_band))
             return FALSE;

src/core/devices/wifi/nm-wifi-utils.c

@@ -639,7 +639,7 @@ nm_wifi_utils_complete_connection(GBytes       *ap_ssid,
                 chan_valid = FALSE;
             }
 
-            band = nm_utils_wifi_freq_to_band(ap_freq);
+            band = nm_wifi_freq_to_band_prop(ap_freq);
             if (band) {
                 g_object_set(s_wifi, NM_SETTING_WIRELESS_BAND, band, NULL);
             } else {
@@ -1929,3 +1929,19 @@ nm_wifi_utils_wfd_info_eq(const NMIwdWfdInfo *a, const NMIwdWfdInfo *b)
     return a->source == b->source && a->sink == b->sink && a->port == b->port
            && a->has_audio == b->has_audio && a->has_uibc == b->has_uibc && a->has_cp == b->has_cp;
 }
+
+const char *
+nm_wifi_freq_to_band_prop(guint32 freq)
+{
+    switch (nm_utils_wifi_freq_to_band(freq)) {
+    case NM_WIFI_BAND_2_4_GHZ:
+        return "bg";
+    case NM_WIFI_BAND_5_GHZ:
+        return "a";
+    case NM_WIFI_BAND_6_GHZ:
+        return "6GHz";
+    default:
+    case NM_WIFI_BAND_UNKNOWN:
+        return NULL;
+    }
+}

src/core/devices/wifi/nm-wifi-utils.h

@@ -56,4 +56,6 @@ bool    nm_wifi_utils_parse_wfd_ies(GBytes *ies, NMIwdWfdInfo *out_wfd);
 GBytes *nm_wifi_utils_build_wfd_ies(const NMIwdWfdInfo *wfd);
 bool    nm_wifi_utils_wfd_info_eq(const NMIwdWfdInfo *a, const NMIwdWfdInfo *b);
 
+const char *nm_wifi_freq_to_band_prop(guint32 freq);
+
 #endif /* __NM_WIFI_UTILS_H__ */

src/libnm-client-impl/libnm.ver

@@ -2097,4 +2097,6 @@ global:
 libnm_1_58_0 {
 global:
 	nm_utils_wifi_6ghz_freqs;
+	nm_utils_wifi_freq_to_band;
+	nm_wifi_band_get_type;
 } libnm_1_56_0;

src/libnm-core-impl/nm-utils.c

@@ -3807,21 +3807,24 @@ nm_utils_wifi_freq_to_channel(guint32 freq)
  * nm_utils_wifi_freq_to_band:
  * @freq: frequency
  *
- * Utility function to translate a Wi-Fi frequency to its corresponding band.
+ * Translates a Wi-Fi frequency to its corresponding band.
  *
- * Returns: the band containing the frequency or NULL if freq is invalid
+ * Returns: the band containing the frequency or %NM_WIFI_BAND_UNKNOWN if
+ * the frequency does not belong to a known band.
+ *
+ * Since: 1.58
  **/
-const char *
+NMWifiBand
 nm_utils_wifi_freq_to_band(guint32 freq)
 {
     if (freq >= _NM_WIFI_FREQ_MIN_2GHZ && freq <= _NM_WIFI_FREQ_MAX_2GHZ)
-        return "bg";
+        return NM_WIFI_BAND_2_4_GHZ;
     else if (freq >= _NM_WIFI_FREQ_MIN_5GHZ && freq <= _NM_WIFI_FREQ_MAX_5GHZ)
-        return "a";
+        return NM_WIFI_BAND_5_GHZ;
     else if (freq >= _NM_WIFI_FREQ_MIN_6GHZ && freq <= _NM_WIFI_FREQ_MAX_6GHZ)
-        return "6GHz";
+        return NM_WIFI_BAND_6_GHZ;
 
-    return NULL;
+    return NM_WIFI_BAND_UNKNOWN;
 }
 
 /**

src/libnm-core-intern/nm-core-internal.h

@@ -1135,8 +1135,6 @@ gboolean nm_utils_base64secret_normalize(const char *base64_key,
 
 gboolean nm_utils_connection_is_adhoc_wpa(NMConnection *connection);
 
-const char *nm_utils_wifi_freq_to_band(guint32 freq);
-
 gboolean _nm_utils_iaid_verify(const char *str, gint64 *out_value);
 
 gboolean

src/libnm-core-public/nm-utils.h

@@ -135,10 +135,30 @@ const char *nm_utils_file_search_in_paths(const char                       *prog
                                           gpointer                          user_data,
                                           GError                          **error);
 
-guint32  nm_utils_wifi_freq_to_channel(guint32 freq);
-guint32  nm_utils_wifi_channel_to_freq(guint32 channel, const char *band);
-guint32  nm_utils_wifi_find_next_channel(guint32 channel, int direction, char *band);
-gboolean nm_utils_wifi_is_channel_valid(guint32 channel, const char *band);
+/**
+ * NMWifiBand:
+ * @NM_WIFI_BAND_UNKNOWN: the band is unknown
+ * @NM_WIFI_BAND_2_4_GHZ: the 2.4 GHz band
+ * @NM_WIFI_BAND_5_GHZ: the 5 GHz band
+ * @NM_WIFI_BAND_6_GHZ: the 6 GHz band
+ *
+ * Describes a Wi-Fi radio frequency band.
+ *
+ * Since: 1.58
+ */
+typedef enum {
+    NM_WIFI_BAND_UNKNOWN,
+    NM_WIFI_BAND_2_4_GHZ,
+    NM_WIFI_BAND_5_GHZ,
+    NM_WIFI_BAND_6_GHZ,
+} NMWifiBand;
+
+guint32 nm_utils_wifi_freq_to_channel(guint32 freq);
+NM_AVAILABLE_IN_1_58
+NMWifiBand nm_utils_wifi_freq_to_band(guint32 freq);
+guint32    nm_utils_wifi_channel_to_freq(guint32 channel, const char *band);
+guint32    nm_utils_wifi_find_next_channel(guint32 channel, int direction, char *band);
+gboolean   nm_utils_wifi_is_channel_valid(guint32 channel, const char *band);
 NM_AVAILABLE_IN_1_2
 const guint *nm_utils_wifi_2ghz_freqs(void);
 NM_AVAILABLE_IN_1_2