## nm-utils nm-utils — Utility functions |

## Synopsis

    #include <nm-utils.h>

    gboolean            nm_utils_init                       (GError **error);
    void                nm_utils_deinit                     (void);
    gboolean            nm_utils_is_empty_ssid              (const guint8 *ssid,
                                                             int len);
    const char *        nm_utils_escape_ssid                (const guint8 *ssid,
                                                             guint32 len);
    gboolean            nm_utils_same_ssid                  (const GByteArray *ssid1,
                                                             const GByteArray *ssid2,
                                                             gboolean ignore_trailing_null);
    char *              nm_utils_ssid_to_utf8               (const GByteArray *ssid);
    GHashTable *        nm_utils_gvalue_hash_dup            (GHashTable *hash);
    void                nm_utils_slist_free                 (GSList *list,
                                                             GDestroyNotify elem_destroy_fn);
    enum                NMUtilsSecurityType;
    gboolean            nm_utils_security_valid             (NMUtilsSecurityType type,
                                                             NMDeviceWifiCapabilities wifi_caps,
                                                             gboolean have_ap,
                                                             gboolean adhoc,
                                                             NM80211ApFlags ap_flags,
                                                             NM80211ApSecurityFlags ap_wpa,
                                                             NM80211ApSecurityFlags ap_rsn);
    gboolean            nm_utils_ap_mode_security_valid     (NMUtilsSecurityType type,
                                                             NMDeviceWifiCapabilities wifi_caps);
    gboolean            nm_utils_wep_key_valid              (const char *key,
                                                             NMWepKeyType wep_type);
    gboolean            nm_utils_wpa_psk_valid              (const char *psk);
    GSList *            nm_utils_ip4_addresses_from_gvalue  (const GValue *value);
    void                nm_utils_ip4_addresses_to_gvalue    (GSList *list,
                                                             GValue *value);
    GSList *            nm_utils_ip4_routes_from_gvalue     (const GValue *value);
    void                nm_utils_ip4_routes_to_gvalue       (GSList *list,
                                                             GValue *value);
    guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);
    guint32             nm_utils_ip4_prefix_to_netmask      (guint32 prefix);
    guint32             nm_utils_ip4_get_default_prefix     (guint32 ip);
    GSList *            nm_utils_ip6_addresses_from_gvalue  (const GValue *value);
    void                nm_utils_ip6_addresses_to_gvalue    (GSList *list,
                                                             GValue *value);
    GSList *            nm_utils_ip6_routes_from_gvalue     (const GValue *value);
    void                nm_utils_ip6_routes_to_gvalue       (GSList *list,
                                                             GValue *value);
    GSList *            nm_utils_ip6_dns_from_gvalue        (const GValue *value);
    void                nm_utils_ip6_dns_to_gvalue          (GSList *list,
                                                             GValue *value);
    char *              nm_utils_uuid_generate              (void);
    char *              nm_utils_uuid_generate_from_string  (const char *s);
    GByteArray *        nm_utils_rsa_key_encrypt            (const GByteArray *data,
                                                             const char *in_password,
                                                             char **out_password,
                                                             GError **error);
    GByteArray *        nm_utils_rsa_key_encrypt_aes        (const GByteArray *data,
                                                             const char *in_password,
                                                             char **out_password,
                                                             GError **error);
    gboolean            nm_utils_file_is_pkcs12             (const char *filename);
    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);
    #define             NM_UTILS_HWADDR_LEN_MAX
    int                 nm_utils_hwaddr_len                 (int type);
    int                 nm_utils_hwaddr_type                (int len);
    char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
                                                             int type);
    GByteArray *        nm_utils_hwaddr_atoba               (const char *asc,
                                                             int type);
    guint8 *            nm_utils_hwaddr_aton                (const char *asc,
                                                             int type,
                                                             gpointer buffer);
    char *              nm_utils_hwaddr_ntoa_len            (gconstpointer addr,
                                                             gsize length);
    guint8 *            nm_utils_hwaddr_aton_len            (const char *asc,
                                                             gpointer buffer,
                                                             gsize length);
    gboolean            nm_utils_hwaddr_valid               (const char *asc);
    char *              nm_utils_bin2hexstr                 (const char *bytes,
                                                             int len,
                                                             int final_len);
    int                 nm_utils_hex2byte                   (const char *hex);
    char *              nm_utils_hexstr2bin                 (const char *hex,
                                                             size_t len);
    gboolean            nm_utils_iface_valid_name           (const char *name);
    gboolean            nm_utils_is_uuid                    (const char *str);
    #define             NM_UTILS_INET_ADDRSTRLEN
    const char *        nm_utils_inet4_ntop                 (in_addr_t inaddr,
                                                             char *dst);
    const char *        nm_utils_inet6_ntop                 (const struct in6_addr *in6addr,
                                                             char *dst);
    gboolean            nm_utils_check_virtual_device_compatibility
                                                            (GType virtual_type,
                                                             GType other_type);

## Object Hierarchy

      GEnum
       +----NMUtilsSecurityType

## Description

A collection of utility functions for working SSIDs, IP addresses, Wi-Fi access points and devices, among other things.

## Details

### nm_utils_init ()

    gboolean            nm_utils_init                       (GError **error);

Initializes libnm-util; should be called when starting and program that uses libnm-util. Sets up an `atexit()` handler to ensure de-initialization is performed, but calling `nm_utils_deinit()` to explicitly deinitialize libnm-util can also be done. This function can be called more than once.

`error` : | location to store error, or `NULL`
Returns : | `TRUE` if the initialization was successful, `FALSE` on failure.

### nm_utils_deinit ()

    void                nm_utils_deinit                     (void);

Frees all resources used internally by libnm-util. This function is called from an `atexit()` handler, set up by `nm_utils_init()`, but is safe to be called more than once. Subsequent calls have no effect until `nm_utils_init()` is called again.

### nm_utils_is_empty_ssid ()

    gboolean            nm_utils_is_empty_ssid              (const guint8 *ssid,
                                                             int len);

Different manufacturers use different mechanisms for not broadcasting the AP's SSID. This function attempts to detect blank/empty SSIDs using a number of known SSID-cloaking methods.

`ssid` : | pointer to a buffer containing the SSID data
`len` : | length of the SSID data in `ssid`
Returns : | `TRUE` if the SSID is "empty", `FALSE` if it is not

### nm_utils_escape_ssid ()

    const char *        nm_utils_escape_ssid                (const guint8 *ssid,
                                                             guint32 len);

This function does a quick printable character conversion of the SSID, simply replacing embedded NULLs and non-printable characters with the hexadecimal representation of that character. Intended for debugging only, should not be used for display of SSIDs.

`ssid` : | pointer to a buffer containing the SSID data
`len` : | length of the SSID data in `ssid`
Returns : | pointer to the escaped SSID, which uses an internal static buffer and will be overwritten by subsequent calls to this function

### nm_utils_same_ssid ()

    gboolean            nm_utils_same_ssid                  (const GByteArray *ssid1,
                                                             const GByteArray *ssid2,
                                                             gboolean ignore_trailing_null);

Earlier versions of the Linux kernel added a NULL byte to the end of the SSID to enable easy printing of the SSID on the console or in a terminal, but this behavior was problematic (SSIDs are simply byte arrays, not strings) and thus was changed. This function compensates for that behavior at the cost of some compatibility with odd SSIDs that may legitimately have trailing NULLs, even though that is functionally pointless.

`ssid1` : | first SSID data to compare
`ssid2` : | second SSID data to compare
`ignore_trailing_null` : | `TRUE` to ignore one trailing NULL byte
Returns : | `TRUE` if the SSIDs are the same, `FALSE` if they are not

### nm_utils_ssid_to_utf8 ()

    char *              nm_utils_ssid_to_utf8               (const GByteArray *ssid);

Wi-Fi SSIDs are byte arrays, they are _not_ strings. Thus, an SSID may contain embedded NULLs and other unprintable characters. Often it is useful to print the SSID out for debugging purposes, but that should be the _only_ use of this function. Do not use this function for any persistent storage of the SSID, since the printable SSID returned from this function cannot be converted back into the real SSID of the access point.

This function does almost everything humanly possible to convert the input into a printable UTF-8 string, using roughly the following procedure:

1) if the input data is already UTF-8 safe, no conversion is performed 2) attempts to get the current system language from the LANG environment variable, and depending on the language, uses a table of alternative encodings to try. For example, if LANG=hu_HU, the table may first try the ISO-8859-2 encoding, and if that fails, try the Windows-1250 encoding. If all fallback encodings fail, replaces non-UTF-8 characters with '?'. 3) If the system language was unable to be determined, falls back to the ISO-8859-1 encoding, then to the Windows-1251 encoding. 4) If step 3 fails, replaces non-UTF-8 characters with '?'.

Again, this function should be used for debugging and display purposes _only_.

`ssid` : | a byte array containing the SSID data
Returns : | an allocated string containing a UTF-8 representation of the SSID, which must be freed by the caller using `g_free()`. Returns `NULL` on errors. [transfer full]

### nm_utils_gvalue_hash_dup ()

    GHashTable *        nm_utils_gvalue_hash_dup            (GHashTable *hash);

Utility function to duplicate a hash table of GValues.

`hash` : | a GHashTable mapping string:GValue
Returns : | a newly allocated duplicated GHashTable, caller must free the returned hash with `g_hash_table_unref()` or `g_hash_table_destroy()`. [transfer container][element-type utf8 GObject.Value]

### nm_utils_slist_free ()

    void                nm_utils_slist_free                 (GSList *list,
                                                             GDestroyNotify elem_destroy_fn);

### Warning

`nm_utils_slist_free` is deprecated and should not be used in newly-written code. use `g_slist_free_full()`.

Utility function to free a GSList.

`list` : | a GSList
`elem_destroy_fn` : | user function called for each element in `list`

### enum NMUtilsSecurityType

    typedef enum {
    	NMU_SEC_INVALID = 0,
    	NMU_SEC_NONE,
    	NMU_SEC_STATIC_WEP,
    	NMU_SEC_LEAP,
    	NMU_SEC_DYNAMIC_WEP,
    	NMU_SEC_WPA_PSK,
    	NMU_SEC_WPA_ENTERPRISE,
    	NMU_SEC_WPA2_PSK,
    	NMU_SEC_WPA2_ENTERPRISE
    } NMUtilsSecurityType;

Describes generic security mechanisms that 802.11 access points may offer. Used with `nm_utils_security_valid()` for checking whether a given access point is compatible with a network device.

`NMU_SEC_INVALID` | unknown or invalid security, placeholder and not used
`NMU_SEC_NONE` | unencrypted and open
`NMU_SEC_STATIC_WEP` | static WEP keys are used for encryption
`NMU_SEC_LEAP` | Cisco LEAP is used for authentication and for generating the dynamic WEP keys automatically
`NMU_SEC_DYNAMIC_WEP` | standard 802.1x is used for authentication and generating the dynamic WEP keys automatically
`NMU_SEC_WPA_PSK` | WPA1 is used with Pre-Shared Keys (PSK)
`NMU_SEC_WPA_ENTERPRISE` | WPA1 is used with 802.1x authentication
`NMU_SEC_WPA2_PSK` | WPA2/RSN is used with Pre-Shared Keys (PSK)
`NMU_SEC_WPA2_ENTERPRISE` | WPA2 is used with 802.1x authentication

### nm_utils_security_valid ()

    gboolean            nm_utils_security_valid             (NMUtilsSecurityType type,
                                                             NMDeviceWifiCapabilities wifi_caps,
                                                             gboolean have_ap,
                                                             gboolean adhoc,
                                                             NM80211ApFlags ap_flags,
                                                             NM80211ApSecurityFlags ap_wpa,
                                                             NM80211ApSecurityFlags ap_rsn);

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device, desired security type, and AP capabilities intersect.

NOTE: this function cannot handle checking security for AP/Hotspot mode; use `nm_utils_ap_mode_security_valid()` instead.

`type` : | the security type to check AP flags and device capabilties against, e.g. NMU_SEC_STATIC_WEP
`wifi_caps` : | bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40
`have_ap` : | whether the `ap_flags`, `ap_wpa`, and `ap_rsn` arguments are valid
`adhoc` : | whether the capabilities being tested are from an Ad-Hoc AP (IBSS)
`ap_flags` : | bitfield of AP capabilities, e.g. NM_802_11_AP_FLAGS_PRIVACY
`ap_wpa` : | bitfield of AP capabilties derived from the AP's WPA beacon, e.g. (NM_802_11_AP_SEC_PAIR_TKIP | NM_802_11_AP_SEC_KEY_MGMT_PSK)
`ap_rsn` : | bitfield of AP capabilties derived from the AP's RSN/WPA2 beacon, e.g. (NM_802_11_AP_SEC_PAIR_CCMP | NM_802_11_AP_SEC_PAIR_TKIP)
Returns : | `TRUE` if the device capabilities and AP capabilties intersect and are compatible with the desired `type`, `FALSE` if they are not

### nm_utils_ap_mode_security_valid ()

    gboolean            nm_utils_ap_mode_security_valid     (NMUtilsSecurityType type,
                                                             NMDeviceWifiCapabilities wifi_caps);

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device capabilities and desired security type are valid for AP/Hotspot connections.

`type` : | the security type to check device capabilties against, e.g. NMU_SEC_STATIC_WEP
`wifi_caps` : | bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40
Returns : | `TRUE` if the device capabilities are compatible with the desired `type`, `FALSE` if they are not.

Since 0.9.8

### nm_utils_wep_key_valid ()

    gboolean            nm_utils_wep_key_valid              (const char *key,
                                                             NMWepKeyType wep_type);

Checks if `key` is a valid WEP key

`key` : | a string that might be a WEP key
`wep_type` : | the NMWepKeyType type of the WEP key
Returns : | `TRUE` if `key` is a WEP key, `FALSE` if not

Since 0.9.8

### nm_utils_wpa_psk_valid ()

    gboolean            nm_utils_wpa_psk_valid              (const char *psk);

Checks if `psk` is a valid WPA PSK

`psk` : | a string that might be a WPA PSK
Returns : | `TRUE` if `psk` is a WPA PSK, `FALSE` if not

Since 0.9.8

### nm_utils_ip4_addresses_from_gvalue ()

    GSList *            nm_utils_ip4_addresses_from_gvalue  (const GValue *value);

Utility function to convert a GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 addresses (which is a tuple of address, gateway, and prefix) into a GSList of NMIP4Address objects. The specific format of this serialization is not guaranteed to be stable and the GArray may be extended in the future.

`value` : | GValue containing a GPtrArray of GArrays of guint32s
Returns : | a newly allocated GSList of NMIP4Address objects. [transfer full][element-type NetworkManager.IP4Address]

### nm_utils_ip4_addresses_to_gvalue ()

    void                nm_utils_ip4_addresses_to_gvalue    (GSList *list,
                                                             GValue *value);

Utility function to convert a GSList of NMIP4Address objects into a GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 addresses (which is a tuple of address, gateway, and prefix). The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`list` : | a list of NMIP4Address objects. [element-type NMIP4Address]
`value` : | a pointer to a GValue into which to place the converted addresses, which should be unset by the caller (when no longer needed) with `g_value_unset()`.

### nm_utils_ip4_routes_from_gvalue ()

    GSList *            nm_utils_ip4_routes_from_gvalue     (const GValue *value);

Utility function to convert a GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 routes (which is a tuple of route, next hop, prefix, and metric) into a GSList of NMIP4Route objects. The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`value` : | GValue containing a GPtrArray of GArrays of guint32s
Returns : | a newly allocated GSList of NMIP4Route objects. [transfer full][element-type NetworkManager.IP4Route]

### nm_utils_ip4_routes_to_gvalue ()

    void                nm_utils_ip4_routes_to_gvalue       (GSList *list,
                                                             GValue *value);

Utility function to convert a GSList of NMIP4Route objects into a GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 routes (which is a tuple of route, next hop, prefix, and metric). The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`list` : | a list of NMIP4Route objects. [element-type NMIP4Route]
`value` : | a pointer to a GValue into which to place the converted routes, which should be unset by the caller (when no longer needed) with `g_value_unset()`.

### nm_utils_ip4_netmask_to_prefix ()

    guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);

`netmask` : | an IPv4 netmask in network byte order
Returns : | the CIDR prefix represented by the netmask

### nm_utils_ip4_prefix_to_netmask ()

    guint32             nm_utils_ip4_prefix_to_netmask      (guint32 prefix);

`prefix` : | a CIDR prefix
Returns : | the netmask represented by the prefix, in network byte order

### nm_utils_ip4_get_default_prefix ()

    guint32             nm_utils_ip4_get_default_prefix     (guint32 ip);

When the Internet was originally set up, various ranges of IP addresses were segmented into three network classes: A, B, and C. This function will return a prefix that is associated with the IP address specified defining where it falls in the predefined classes.

`ip` : | an IPv4 address (in network byte order)
Returns : | the default class prefix for the given IP

### nm_utils_ip6_addresses_from_gvalue ()

    GSList *            nm_utils_ip6_addresses_from_gvalue  (const GValue *value);

Utility function to convert a GPtrArray of GValueArrays of (GArray of guchars) and guint32 representing a list of NetworkManager IPv6 addresses (which is a tuple of address, prefix, and gateway), into a GSList of NMIP6Address objects. The specific format of this serialization is not guaranteed to be stable and the GValueArray may be extended in the future.

`value` : | gvalue containing a GPtrArray of GValueArrays of (GArray of guchars) and guint32
Returns : | a newly allocated GSList of NMIP6Address objects. [transfer full][element-type NetworkManager.IP6Address]

### nm_utils_ip6_addresses_to_gvalue ()

    void                nm_utils_ip6_addresses_to_gvalue    (GSList *list,
                                                             GValue *value);

Utility function to convert a GSList of NMIP6Address objects into a GPtrArray of GValueArrays representing a list of NetworkManager IPv6 addresses (which is a tuple of address, prefix, and gateway). The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`list` : | a list of NMIP6Address objects. [element-type NMIP6Address]
`value` : | a pointer to a GValue into which to place the converted addresses, which should be unset by the caller (when no longer needed) with `g_value_unset()`.

### nm_utils_ip6_routes_from_gvalue ()

    GSList *            nm_utils_ip6_routes_from_gvalue     (const GValue *value);

Utility function GPtrArray of GValueArrays of (GArray of guchars), guint32, (GArray of guchars), and guint32 representing a list of NetworkManager IPv6 routes (which is a tuple of destination, prefix, next hop, and metric) into a GSList of NMIP6Route objects. The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`value` : | GValue containing a GPtrArray of GValueArrays of (GArray of guchars), guint32, (GArray of guchars), and guint32
Returns : | a newly allocated GSList of NMIP6Route objects. [transfer full][element-type NetworkManager.IP6Route]

### nm_utils_ip6_routes_to_gvalue ()

    void                nm_utils_ip6_routes_to_gvalue       (GSList *list,
                                                             GValue *value);

Utility function to convert a GSList of NMIP6Route objects into a GPtrArray of GValueArrays of (GArray of guchars), guint32, (GArray of guchars), and guint32 representing a list of NetworkManager IPv6 routes (which is a tuple of destination, prefix, next hop, and metric). The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`list` : | a list of NMIP6Route objects. [element-type NMIP6Route]
`value` : | a pointer to a GValue into which to place the converted routes, which should be unset by the caller (when no longer needed) with `g_value_unset()`.

### nm_utils_ip6_dns_from_gvalue ()

    GSList *            nm_utils_ip6_dns_from_gvalue        (const GValue *value);

Converts a GValue containing a GPtrArray of IP6 DNS, represented as GByteArrays into a GSList of `struct in6_addr`s.

`value` : | a GValue
Returns : | a GSList of IP6 addresses.

### nm_utils_ip6_dns_to_gvalue ()

    void                nm_utils_ip6_dns_to_gvalue          (GSList *list,
                                                             GValue *value);

Utility function to convert a GSList of `struct in6_addr` structs into a GPtrArray of GByteArrays representing each server's IPv6 addresses in network byte order. The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

`list` : | a list of NMIP6Route objects
`value` : | a pointer to a GValue into which to place the converted DNS server addresses, which should be unset by the caller (when no longer needed) with `g_value_unset()`.

### nm_utils_uuid_generate ()

    char *              nm_utils_uuid_generate              (void);

Returns : | a newly allocated UUID suitable for use as the NMSettingConnection object's "id": property. Should be freed with `g_free()`

### nm_utils_uuid_generate_from_string ()

    char *              nm_utils_uuid_generate_from_string  (const char *s);

For a given `s`, this function will always return the same UUID.

`s` : | a string to use as the seed for the UUID
Returns : | a newly allocated UUID suitable for use as the NMSettingConnection object's "id": property

### nm_utils_rsa_key_encrypt ()

    GByteArray *        nm_utils_rsa_key_encrypt            (const GByteArray *data,
                                                             const char *in_password,
                                                             char **out_password,
                                                             GError **error);

Encrypts the given RSA private key data with the given password (or generates a password if no password was given) and converts the data to PEM format suitable for writing to a file. It uses Triple DES cipher for the encryption.

`data` : | RSA private key data to be encrypted
`in_password` : | existing password to use, if any. [allow-none]
`out_password` : | if `in_password` was `NULL`, a random password will be generated and returned in this argument. [out][allow-none]
`error` : | detailed error information on return, if an error occurred
Returns : | on success, PEM-formatted data suitable for writing to a PEM-formatted certificate/private key file. [transfer full]

### nm_utils_rsa_key_encrypt_aes ()

    GByteArray *        nm_utils_rsa_key_encrypt_aes        (const GByteArray *data,
                                                             const char *in_password,
                                                             char **out_password,
                                                             GError **error);

Encrypts the given RSA private key data with the given password (or generates a password if no password was given) and converts the data to PEM format suitable for writing to a file. It uses AES cipher for the encryption.

`data` : | RSA private key data to be encrypted
`in_password` : | existing password to use, if any. [allow-none]
`out_password` : | if `in_password` was `NULL`, a random password will be generated and returned in this argument. [out][allow-none]
`error` : | detailed error information on return, if an error occurred
Returns : | on success, PEM-formatted data suitable for writing to a PEM-formatted certificate/private key file. [transfer full]

### nm_utils_file_is_pkcs12 ()

    gboolean            nm_utils_file_is_pkcs12             (const char *filename);

Utility function to find out if the `filename` is in PKCS12 format.

`filename` : | name of the file to test
Returns : | `TRUE` if the file is PKCS12, `FALSE` if it is not

### nm_utils_wifi_freq_to_channel ()

    guint32             nm_utils_wifi_freq_to_channel       (guint32 freq);

Utility function to translate a Wi-Fi frequency to its corresponding channel.

`freq` : | frequency
Returns : | the channel represented by the frequency or 0

### nm_utils_wifi_channel_to_freq ()

    guint32             nm_utils_wifi_channel_to_freq       (guint32 channel,
                                                             const char *band);

Utility function to translate a Wi-Fi channel to its corresponding frequency.

`channel` : | channel
`band` : | frequency band for wireless ("a" or "bg")
Returns : | the frequency represented by the channel of the band, or -1 when the freq is invalid, or 0 when the band is invalid

### nm_utils_wifi_find_next_channel ()

    guint32             nm_utils_wifi_find_next_channel     (guint32 channel,
                                                             int direction,
                                                             char *band);

Utility function to find out next/previous Wi-Fi channel for a channel.

`channel` : | current channel
`direction` : | whether going downward (0 or less) or upward (1 or more)
`band` : | frequency band for wireless ("a" or "bg")
Returns : | the next channel in the specified direction or 0

### nm_utils_wifi_is_channel_valid ()

    gboolean            nm_utils_wifi_is_channel_valid      (guint32 channel,
                                                             const char *band);

Utility function to verify Wi-Fi channel validity.

`channel` : | channel
`band` : | frequency band for wireless ("a" or "bg")
Returns : | `TRUE` or `FALSE`

### NM_UTILS_HWADDR_LEN_MAX

    #define NM_UTILS_HWADDR_LEN_MAX 20 /* INFINIBAND_ALEN */

The maximum length of a hardware address of a type known by `nm_utils_hwaddr_len()` or `nm_utils_hwaddr_aton()`. This can be used as the size of the buffer passed to `nm_utils_hwaddr_aton()`.

### nm_utils_hwaddr_len ()

    int                 nm_utils_hwaddr_len                 (int type);

Returns the length in octets of a hardware address of type `type`.

`type` : | the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`
Returns : | the positive length, or -1 if the type is unknown/unsupported.

### nm_utils_hwaddr_type ()

    int                 nm_utils_hwaddr_type                (int len);

### Warning

`nm_utils_hwaddr_type` is deprecated and should not be used in newly-written code. This could not be extended to cover other types, since there is not a one-to-one mapping between types and lengths. This was mostly only used to get a type to pass to `nm_utils_hwaddr_ntoa()` or `nm_utils_hwaddr_aton()` when you only had a length; but you can just use `nm_utils_hwaddr_ntoa_len()` or `nm_utils_hwaddr_aton_len()` now instead.

Returns the type (either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`) of the raw address given its length.

`len` : | the length of hardware address in bytes
Returns : | the type, either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`. If the length is unexpected, return -1 (unsupported type/length).

### nm_utils_hwaddr_ntoa ()

    char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
                                                             int type);

Converts `addr` to textual form.

See also `nm_utils_hwaddr_ntoa_len()`, which takes a length instead of a type.

`addr` : | a binary hardware address
`type` : | the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`
Returns : | the textual form of `addr`. [transfer full]

### nm_utils_hwaddr_atoba ()

    GByteArray *        nm_utils_hwaddr_atoba               (const char *asc,
                                                             int type);

Parses `asc` and converts it to binary form in a GByteArray. See `nm_utils_hwaddr_aton()` if you don't want a GByteArray.

`asc` : | the ASCII representation of a hardware address
`type` : | the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`
Returns : | a new GByteArray, or `NULL` if `asc` couldn't be parsed. [transfer full]

### nm_utils_hwaddr_aton ()

    guint8 *            nm_utils_hwaddr_aton                (const char *asc,
                                                             int type,
                                                             gpointer buffer);

Parses `asc` and converts it to binary form in `buffer`. See `nm_utils_hwaddr_atoba()` if you'd rather have the result in a GByteArray.

See also `nm_utils_hwaddr_aton_len()`, which takes an output length instead of a type.

`asc` : | the ASCII representation of a hardware address
`type` : | the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`
`buffer` : | buffer to store the result into
Returns : | `buffer`, or `NULL` if `asc` couldn't be parsed

### nm_utils_hwaddr_ntoa_len ()

    char *              nm_utils_hwaddr_ntoa_len            (gconstpointer addr,
                                                             gsize length);

Converts `addr` to textual form.

`addr` : | a binary hardware address
`length` : | the length of `addr`
Returns : | the textual form of `addr`. [transfer full]

Since 0.9.10

### nm_utils_hwaddr_aton_len ()

    guint8 *            nm_utils_hwaddr_aton_len            (const char *asc,
                                                             gpointer buffer,
                                                             gsize length);

Parses `asc` and converts it to binary form in `buffer`. Bytes in `asc` can be sepatared by colons (:), or hyphens (-), but not mixed.

`asc` : | the ASCII representation of a hardware address
`buffer` : | buffer to store the result into
`length` : | the expected length in bytes of the result and the size of the buffer in bytes.
Returns : | `buffer`, or `NULL` if `asc` couldn't be parsed or would be shorter or longer than `length`.

Since 0.9.10

### nm_utils_hwaddr_valid ()

    gboolean            nm_utils_hwaddr_valid               (const char *asc);

Parses `asc` to see if it is a valid hardware address of some type.

`asc` : | the ASCII representation of a hardware address
Returns : | `TRUE` if `asc` appears to be a valid hardware address of some type, `FALSE` if not.

Since 0.9.10

### nm_utils_bin2hexstr ()

    char *              nm_utils_bin2hexstr                 (const char *bytes,
                                                             int len,
                                                             int final_len);

Converts a byte-array `bytes` into a hexadecimal string. If `final_len` is greater than -1, the returned string is terminated at that index (returned_string[final_len] == '\0'),

`bytes` : | an array of bytes
`len` : | the length of the `bytes` array
`final_len` : | an index where to cut off the returned string, or -1
Returns : | the textual form of `bytes`. [transfer full]

Since 0.9.10

### nm_utils_hex2byte ()

    int                 nm_utils_hex2byte                   (const char *hex);

Converts a hex string (2 characters) into its byte representation.

`hex` : | a string representing a hex byte
Returns : | a byte, or -1 if `hex` doesn't represent a hex byte

Since 0.9.10

### nm_utils_hexstr2bin ()

    char *              nm_utils_hexstr2bin                 (const char *hex,
                                                             size_t len);

Converts a hexadecimal string `hex` into a byte-array. The returned array length is `len`/2.

`hex` : | an hex string
`len` : | the length of the `hex` string (it has to be even)
Returns : | a array of bytes, or `NULL` on error. [transfer full]

Since 0.9.10

### nm_utils_iface_valid_name ()

    gboolean            nm_utils_iface_valid_name           (const char *name);

This function is a 1:1 copy of the kernel's interface validation function in net/core/dev.c.

`name` : | Name of interface
Returns : | `TRUE` if interface name is valid, otherwise `FALSE` is returned.

Since 0.9.8

### nm_utils_is_uuid ()

    gboolean            nm_utils_is_uuid                    (const char *str);

Checks if `str` is a UUID

`str` : | a string that might be a UUID
Returns : | `TRUE` if `str` is a UUID, `FALSE` if not

Since 0.9.8

### NM_UTILS_INET_ADDRSTRLEN

    #define NM_UTILS_INET_ADDRSTRLEN     INET6_ADDRSTRLEN

Defines the minimal length for a char buffer that is suitable as `dst` argument for both `nm_utils_inet4_ntop()` and `nm_utils_inet6_ntop()`.

### nm_utils_inet4_ntop ()

    const char *        nm_utils_inet4_ntop                 (in_addr_t inaddr,
                                                             char *dst);

Wrapper for inet_ntop.

`inaddr` : | the address that should be converted to string.
`dst` : | the destination buffer, it must contain at least `INET_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` characters. If set to `NULL`, it will return a pointer to an internal, static buffer (shared with `nm_utils_inet6_ntop()`). Beware, that the internal buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or `nm_utils_inet6_ntop()` that does not provied it's own `dst` buffer. Also, using the internal buffer is not thread safe. When in doubt, pass your own `dst` buffer to avoid these issues.
Returns : | the input buffer `dst`, or a pointer to an internal, static buffer. This function cannot fail.

Since 0.9.10

### nm_utils_inet6_ntop ()

    const char *        nm_utils_inet6_ntop                 (const struct in6_addr *in6addr,
                                                             char *dst);

Wrapper for inet_ntop.

`in6addr` : | the address that should be converted to string.
`dst` : | the destination buffer, it must contain at least `INET6_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` characters. If set to `NULL`, it will return a pointer to an internal, static buffer (shared with `nm_utils_inet4_ntop()`). Beware, that the internal buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or `nm_utils_inet6_ntop()` that does not provied it's own `dst` buffer. Also, using the internal buffer is not thread safe. When in doubt, pass your own `dst` buffer to avoid these issues.
Returns : | the input buffer `dst`, or a pointer to an internal, static buffer. `NULL` is not allowed as `in6addr`, otherwise, this function cannot fail.

Since 0.9.10

### nm_utils_check_virtual_device_compatibility ()

    gboolean            nm_utils_check_virtual_device_compatibility
                                                            (GType virtual_type,
                                                             GType other_type);

Determines if a connection of type `virtual_type` can (in the general case) work with connections of type `other_type`.

If `virtual_type` is `NM_TYPE_SETTING_VLAN`, then this checks if `other_type` is a valid type for the parent of a VLAN.

If `virtual_type` is a "master" type (eg, `NM_TYPE_SETTING_BRIDGE`), then this checks if `other_type` is a valid type for a slave of that master.

Note that even if this returns `TRUE` it is not guaranteed that every connection of type `other_type` is compatible with `virtual_type`; it may depend on the exact configuration of the two connections, or on the capabilities of an underlying device driver.

`virtual_type` : | a virtual connection type
`other_type` : | a connection type to test against `virtual_type`
Returns : | `TRUE` or `FALSE`

Since 0.9.10