nm_utils_init ()

gboolean            nm_utils_init                       (GError **error);

Initializes libnm-util; should be called when starting any program that uses libnm-util. This function can be called more than once.

nm_utils_deinit ()

void                nm_utils_deinit                     (void);

No-op. Although this function still exists for ABI compatibility reasons, it does not have any effect, and does not ever need to be called.

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.

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.

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.

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_.

nm_utils_gvalue_hash_dup ()

GHashTable *        nm_utils_gvalue_hash_dup            (GHashTable *hash);

Utility function to duplicate a hash table of GValues.

nm_utils_slist_free ()

void                nm_utils_slist_free                 (GSList *list,
                                                         GDestroyNotify elem_destroy_fn);

Utility function to free a GSList.

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.

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.

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.

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

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

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.

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.

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.

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.

nm_utils_ip4_netmask_to_prefix ()

guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);

nm_utils_ip4_prefix_to_netmask ()

guint32             nm_utils_ip4_prefix_to_netmask      (guint32 prefix);

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.

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.

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.

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.

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.

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_addrs.

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.

nm_utils_uuid_generate ()

char *              nm_utils_uuid_generate              (void);

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.

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.

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.

nm_utils_file_is_pkcs12 ()

gboolean            nm_utils_file_is_pkcs12             (const char *filename);

Utility function to find out if the filename is in PKCS#12 format.

NMUtilsFileSearchInPathsPredicate ()

gboolean            (*NMUtilsFileSearchInPathsPredicate)
                                                        (const char *filename,
                                                         gpointer user_data);

nm_utils_file_search_in_paths ()

const char *        nm_utils_file_search_in_paths       (const char *progname,
                                                         const char *try_first,
                                                         const char *const *paths,
                                                         GFileTest file_test_flags,
                                                         NMUtilsFileSearchInPathsPredicate predicate,
                                                         gpointer user_data,
                                                         GError **error);

Searches for a progname file in a list of search paths.

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.

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.

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.

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.

NM_UTILS_HWADDR_LEN_MAX

#define NM_UTILS_HWADDR_LEN_MAX 20 /* INFINIBAND_ALEN */

The maximum length of hardware addresses handled by NetworkManager itself, nm_utils_hwaddr_len(), and 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.

nm_utils_hwaddr_type ()

int                 nm_utils_hwaddr_type                (int len);

Returns the type (either ARPHRD_ETHER or ARPHRD_INFINIBAND) of the raw address given its 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.

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.

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.

nm_utils_hwaddr_ntoa_len ()

char *              nm_utils_hwaddr_ntoa_len            (gconstpointer addr,
                                                         gsize length);

Converts addr to textual form.

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.

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.

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'),

Since 0.9.10

nm_utils_hex2byte ()

int                 nm_utils_hex2byte                   (const char *hex);

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

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.

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.

Since 0.9.8

nm_utils_is_uuid ()

gboolean            nm_utils_is_uuid                    (const char *str);

Checks if str is a UUID

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.

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.

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.

Since 0.9.10