libnm-core: add nm_utils_hwaddr_canonical()

Add a helper function for converting hardware addresses to canonical
form.

libnm-core/nm-utils.c

@@ -2352,6 +2352,39 @@ nm_utils_hwaddr_valid (const char *asc, gssize length)
 	return nm_utils_hwaddr_aton (asc, buf, length) != NULL;
 }
 
+/**
+ * nm_utils_hwaddr_canonical:
+ * @asc: the ASCII representation of a hardware address
+ * @length: the length of address that @asc is expected to convert to
+ *   (or -1 to accept any length up to %NM_UTILS_HWADDR_LEN_MAX)
+ *
+ * Parses @asc to see if it is a valid hardware address of the given
+ * length, and if so, returns it in canonical form (uppercase, with
+ * leading 0s as needed, and with colons rather than hyphens).
+ *
+ * Return value: (transfer full): the canonicalized address if @asc appears to
+ *   be a valid hardware address of the indicated length, %NULL if not.
+ */
+char *
+nm_utils_hwaddr_canonical (const char *asc, gssize length)
+{
+	guint8 buf[NM_UTILS_HWADDR_LEN_MAX];
+
+	g_return_val_if_fail (asc != NULL, NULL);
+	g_return_val_if_fail (length == -1 || (length > 0 && length <= NM_UTILS_HWADDR_LEN_MAX), NULL);
+
+	if (length == -1) {
+		length = hwaddr_binary_len (asc);
+		if (length == 0 || length > NM_UTILS_HWADDR_LEN_MAX)
+			return NULL;
+	}
+
+	if (nm_utils_hwaddr_aton (asc, buf, length) == NULL)
+		return NULL;
+
+	return g_strdup (nm_utils_hwaddr_ntoa (buf, length));
+}
+
 /**
  * nm_utils_hwaddr_matches:
  * @hwaddr1: pointer to a binary or ASCII hardware address, or %NULL

libnm-core/nm-utils.h

@@ -141,17 +141,18 @@ const char *nm_utils_wifi_strength_bars (guint8 strength);
  */
 #define NM_UTILS_HWADDR_LEN_MAX 20 /* INFINIBAND_ALEN */
 
-gsize       nm_utils_hwaddr_len   (int type) G_GNUC_PURE;
+gsize       nm_utils_hwaddr_len       (int type) G_GNUC_PURE;
 
-char       *nm_utils_hwaddr_ntoa  (gconstpointer addr, gsize length);
-GByteArray *nm_utils_hwaddr_atoba (const char *asc, gsize length);
-guint8     *nm_utils_hwaddr_aton  (const char *asc, gpointer buffer, gsize length);
+char       *nm_utils_hwaddr_ntoa      (gconstpointer addr, gsize length);
+GByteArray *nm_utils_hwaddr_atoba     (const char *asc, gsize length);
+guint8     *nm_utils_hwaddr_aton      (const char *asc, gpointer buffer, gsize length);
 
-gboolean    nm_utils_hwaddr_valid (const char *asc, gssize length);
-gboolean    nm_utils_hwaddr_matches (gconstpointer hwaddr1,
-                                     gssize        hwaddr1_len,
-                                     gconstpointer hwaddr2,
-                                     gssize        hwaddr2_len);
+gboolean    nm_utils_hwaddr_valid     (const char *asc, gssize length);
+char       *nm_utils_hwaddr_canonical (const char *asc, gssize length);
+gboolean    nm_utils_hwaddr_matches   (gconstpointer hwaddr1,
+                                       gssize        hwaddr1_len,
+                                       gconstpointer hwaddr2,
+                                       gssize        hwaddr2_len);
 
 char *nm_utils_bin2hexstr (const char *bytes, int len, int final_len);
 int   nm_utils_hex2byte   (const char *hex);

libnm-core/tests/test-general.c

@@ -2238,6 +2238,35 @@ test_hwaddr_equal (void)
 	g_assert (nm_utils_hwaddr_matches (null_binary, sizeof (null_binary), NULL, ETH_ALEN));
 }
 
+static void
+test_hwaddr_canonical (void)
+{
+	const char *string = "00:1A:2B:03:44:05";
+	const char *lower_string = "00:1a:2b:03:44:05";
+	const char *short_string = "0:1a:2b:3:44:5";
+	const char *invalid_string = "00:1A:2B";
+	char *canonical;
+
+	canonical = nm_utils_hwaddr_canonical (string, ETH_ALEN);
+	g_assert_cmpstr (canonical, ==, string);
+	g_free (canonical);
+
+	canonical = nm_utils_hwaddr_canonical (lower_string, ETH_ALEN);
+	g_assert_cmpstr (canonical, ==, string);
+	g_free (canonical);
+
+	canonical = nm_utils_hwaddr_canonical (short_string, ETH_ALEN);
+	g_assert_cmpstr (canonical, ==, string);
+	g_free (canonical);
+
+	canonical = nm_utils_hwaddr_canonical (invalid_string, ETH_ALEN);
+	g_assert_cmpstr (canonical, ==, NULL);
+
+	canonical = nm_utils_hwaddr_canonical (invalid_string, -1);
+	g_assert_cmpstr (canonical, ==, invalid_string);
+	g_free (canonical);
+}
+
 static void
 test_connection_changed_cb (NMConnection *connection, gboolean *data)
 {
@@ -3372,6 +3401,7 @@ int main (int argc, char **argv)
 	g_test_add_func ("/core/general/test_hwaddr_aton_no_leading_zeros", test_hwaddr_aton_no_leading_zeros);
 	g_test_add_func ("/core/general/test_hwaddr_aton_malformed", test_hwaddr_aton_malformed);
 	g_test_add_func ("/core/general/test_hwaddr_equal", test_hwaddr_equal);
+	g_test_add_func ("/core/general/test_hwaddr_canonical", test_hwaddr_canonical);
 
 	g_test_add_func ("/core/general/test_ip4_prefix_to_netmask", test_ip4_prefix_to_netmask);
 	g_test_add_func ("/core/general/test_ip4_netmask_to_prefix", test_ip4_netmask_to_prefix);

libnm/libnm.ver

@@ -809,6 +809,7 @@ global:
 	nm_utils_hexstr2bin;
 	nm_utils_hwaddr_atoba;
 	nm_utils_hwaddr_aton;
+	nm_utils_hwaddr_canonical;
 	nm_utils_hwaddr_len;
 	nm_utils_hwaddr_matches;
 	nm_utils_hwaddr_ntoa;