nm-utils

@@ -132,132 +132,74 @@ access points and devices, among other things.

Details

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;
-

nm_utils_init ()

gboolean            nm_utils_init                       (GError **error);

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

+++ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - + +

`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) +	`error` :	location to store error, or `NULL`
`NMU_SEC_WPA2_ENTERPRISE`	WPA2 is used with 802.1x authentication -	Returns :	TRUE if the initialization was successful, FALSE on failure.

NM_UTILS_HWADDR_LEN_MAX

#define NM_UTILS_HWADDR_LEN_MAX 20 /* INFINIBAND_ALEN */
-

nm_utils_deinit ()

void                nm_utils_deinit                     (void);

-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(). +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_ap_mode_security_valid ()

gboolean            nm_utils_ap_mode_security_valid     (NMUtilsSecurityType type,
-                                                         NMDeviceWifiCapabilities wifi_caps);

nm_utils_is_empty_ssid ()

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

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

+++ - - + + - - + - +

`type` :	the security type to check device capabilties against, -e.g. NMU_SEC_STATIC_WEP -	`ssid` :	pointer to a buffer containing the SSID data
`wifi_caps` :	bitfield of the capabilities of the specific WiFi device, e.g. -NM_WIFI_DEVICE_CAP_CIPHER_WEP40 +	`len` :	length of the SSID data in `ssid`
Returns :	TRUE if the device capabilities are compatible with the desired -`type`, FALSE if they are not.	TRUE if the SSID is "empty", FALSE if it is not

Since 0.9.8

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

@@ -270,8 +212,11 @@ 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.

+++ @@ -292,73 +237,89 @@ and will be overwritten by subsequent calls to this function

nm_utils_file_is_pkcs12 ()

gboolean            nm_utils_file_is_pkcs12             (const char *filename);

nm_utils_same_ssid ()

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

-Utility function to find out if the filename is in PKCS12 format. +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.

ssid :

+++ - - + + - - + + - -

`filename` :	name of the file to test	`ssid1` :	first SSID data to compare
Returns :	TRUE if the file is PKCS12, FALSE if it is not	`ssid2` :	second SSID data to compare

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	`ignore_trailing_null` :	TRUE to ignore one trailing NULL byte
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] -	TRUE if the SSIDs are the same, FALSE if they are not

nm_utils_hwaddr_atoba ()

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

nm_utils_ssid_to_utf8 ()

char *              nm_utils_ssid_to_utf8               (const GByteArray *ssid);

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

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

asc :

the ASCII representation of a hardware address

++++ + - - + + - @@ -366,131 +327,264 @@ be parsed. [ -

nm_utils_hwaddr_aton ()

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

nm_utils_gvalue_hash_dup ()

GHashTable *        nm_utils_gvalue_hash_dup            (GHashTable *hash);

-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. +Utility function to duplicate a hash table of GValues.

`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` -	`ssid` :	a byte array containing the SSID data
Returns :	a new GByteArray, or `NULL` if `asc` couldn't -be parsed. [transfer full] +	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]

+++ - - + + - - + + +

`asc` :	the ASCII representation of a hardware address	`hash` :	a GHashTable mapping string:GValue
`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +	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);

+Utility function to free a GSList. +

++++ + - - + + - - + +

`buffer` :	buffer to store the result into	`list` :	a GSList +
Returns :	-`buffer`, or `NULL` if `asc` couldn't be parsed	`elem_destroy_fn` :	user function called for each element in `list` +

nm_utils_hwaddr_len ()

int                 nm_utils_hwaddr_len                 (int type);

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;
+

-Returns the length in octets of a hardware address of type type. +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.

+++ - - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +	`NMU_SEC_INVALID`	unknown or invalid security, placeholder and not used
Returns :	the length	`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_hwaddr_ntoa ()

char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
-                                                         int type);

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);

-Converts addr to textual form. +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.

+++ - - + + - - + - - + + + + + + + + + + + + + + + + + + + + +

`addr` :	a binary hardware address	`type` :	the security type to check AP flags and device capabilties against, +e.g. NMU_SEC_STATIC_WEP +
`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +	`wifi_caps` :	bitfield of the capabilities of the specific WiFi device, e.g. +NM_WIFI_DEVICE_CAP_CIPHER_WEP40
Returns :	the textual form of `addr`. [transfer full] +	`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_hwaddr_type ()

int                 nm_utils_hwaddr_type                (int len);

nm_utils_ap_mode_security_valid ()

gboolean            nm_utils_ap_mode_security_valid     (NMUtilsSecurityType type,
+                                                         NMDeviceWifiCapabilities wifi_caps);

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

+++ - - + + + + + + - +

`len` :	the length of hardware address in bytes	`type` :	the security type to check device capabilties against, +e.g. NMU_SEC_STATIC_WEP +
`wifi_caps` :	bitfield of the capabilities of the specific WiFi device, e.g. +NM_WIFI_DEVICE_CAP_CIPHER_WEP40 +
Returns :	the type, either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`, or -1 if -the address length was not recognized	TRUE if the device capabilities are compatible with the desired +`type`, FALSE if they are not.

Since 0.9.8

nm_utils_iface_valid_name ()

gboolean            nm_utils_iface_valid_name           (const char *name);

nm_utils_wep_key_valid ()

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

-This function is a 1:1 copy of the kernel's interface validation -function in net/core/dev.c. +Checks if key is a valid WEP key

+++ - - + + + + + + +TRUE if key is a WEP key, FALSE if not

`name` :	Name of interface	`key` :	a string that might be a WEP key
`wep_type` :	the NMWepKeyType type of the WEP key
Returns :	-`TRUE` if interface name is valid, otherwise `FALSE` is returned.

@@ -498,28 +592,29 @@ function in net/core/dev.c.

nm_utils_init ()

gboolean            nm_utils_init                       (GError **error);

nm_utils_wpa_psk_valid ()

gboolean            nm_utils_wpa_psk_valid              (const char *psk);

-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. +Checks if psk is a valid WPA PSK

+++ - - + + - +

`error` :	location to store error, or `NULL` -	`psk` :	a string that might be a WPA PSK
Returns :	TRUE if the initialization was successful, FALSE on failure.	+`TRUE` if `psk` is a WPA PSK, `FALSE` if not

Since 0.9.8

@@ -532,8 +627,11 @@ and prefix) into a GSList of GArray may be extended in the future.

+++ @@ -555,83 +653,26 @@ extended in the future.

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

value :

-- - - - - - - - - - -

`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_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_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);

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

+++ - - + + - - + +

`prefix` :	a CIDR prefix	`list` :	a list of NMIP4Address objects. [element-type NMIP4Address] +
Returns :	the netmask represented by the prefix, in network byte order	`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()`.

@@ -647,8 +688,11 @@ prefix, and metric) into a GSList of +

+++ @@ -674,8 +718,11 @@ 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.

value :

+++ @@ -693,79 +740,97 @@ which should be unset by the caller (when no longer needed) with

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

list :

nm_utils_ip4_netmask_to_prefix ()

guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);

+++ - - + + - +

`value` :	gvalue containing a GPtrArray of GValueArrays of (GArray of guchars) and guint32	`netmask` :	an IPv4 netmask in network byte order
Returns :	a newly allocated GSList of NMIP6Address objects. [transfer full][element-type NetworkManager.IP6Address] -	the CIDR prefix represented by the netmask

nm_utils_ip6_addresses_to_gvalue ()

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

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);

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

+++ - - + + - - + +

`list` :	a list of NMIP6Address objects. [element-type NMIP6Address] -	`ip` :	an IPv4 address (in network byte order)
`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()`.	Returns :	the default class prefix for the given IP

nm_utils_ip6_dns_from_gvalue ()

GSList *            nm_utils_ip6_dns_from_gvalue        (const GValue *value);

nm_utils_ip6_addresses_from_gvalue ()

GSList *            nm_utils_ip6_addresses_from_gvalue  (const GValue *value);

-Converts a GValue containing a GPtrArray of IP6 DNS, represented as -GByteArrays into a GSList of in6_addrs. +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.

+++ - + - @@ -773,26 +838,31 @@ addresses. [ -

nm_utils_ip6_dns_to_gvalue ()

void                nm_utils_ip6_dns_to_gvalue          (GSList *list,
+nm_utils_ip6_addresses_to_gvalue ()
+void                nm_utils_ip6_addresses_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.
+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.
 
-

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

+++ - + - @@ -809,8 +879,11 @@ 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.

`list` :	a list of NMIP6Route objects	a list of NMIP6Address objects. [element-type NMIP6Address] +
`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 +	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()`.

+++ @@ -837,8 +910,11 @@ representing a list of NetworkManager IPv6 routes (which is a tuple of destinati prefix, next hop, and metric). The specific format of this serialization is not guaranteed to be stable and may be extended in the future.

value :

+++ @@ -856,55 +932,103 @@ which should be unset by the caller (when no longer needed) with

nm_utils_is_empty_ssid ()

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

nm_utils_ip6_dns_from_gvalue ()

GSList *            nm_utils_ip6_dns_from_gvalue        (const GValue *value);

-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. +Converts a GValue containing a GPtrArray of IP6 DNS, represented as +GByteArrays into a GSList of in6_addrs.

list :

+++ - - + + - - + + +

`ssid` :	pointer to a buffer containing the SSID data	`value` :	a GValue +
`len` :	length of the SSID data in `ssid` +	Returns :	a GSList of IP6 +addresses. [transfer full][element-type Posix.in6_addr]

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
Returns :	TRUE if the SSID is "empty", FALSE if it is not	`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_is_uuid ()

gboolean            nm_utils_is_uuid                    (const char *str);

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);

-Checks if str is a UUID +For a given s, this function will always return the same UUID.

+++ - - + + - +

`str` :	a string that might be a UUID	`s` :	a string to use as the seed for the UUID
Returns :	-`TRUE` if `str` is a UUID, `FALSE` if not	a newly allocated UUID suitable for use as the NMSettingConnection +object's "id": property

Since 0.9.8

@@ -918,8 +1042,11 @@ 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.

+++ @@ -932,7 +1059,7 @@ suitable for writing to a file. - @@ -951,365 +1078,358 @@ certificate/private key file. [ -

nm_utils_same_ssid ()

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

nm_utils_file_is_pkcs12 ()

gboolean            nm_utils_file_is_pkcs12             (const char *filename);

-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. +Utility function to find out if the filename is in PKCS12 format.

`data` :
`out_password` :	if `in_password` was NULL, a random password will be generated +	if `in_password` was `NULL`, a random password will be generated and returned in this argument. [out][allow-none]

+++ - - - - - - - - - - + + - +

`ssid1` :	first SSID data to compare
`ssid2` :	second SSID data to compare
`ignore_trailing_null` :	TRUE to ignore one trailing NULL byte	`filename` :	name of the file to test
Returns :	TRUE if the SSIDs are the same, FALSE if they are not	TRUE if the file is PKCS12, FALSE if it is not

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

nm_utils_wifi_freq_to_channel ()

guint32             nm_utils_wifi_freq_to_channel       (guint32 freq);

-NOTE: this function cannot handle checking security for AP/Hotspot mode; -use nm_utils_ap_mode_security_valid() instead. +Utility function to translate a WiFi frequency to its corresponding channel.

+++ - - - - - - - - - - - - - - + + - - + + + +

`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 WiFi 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)	`freq` :	frequency
`ap_flags` :	bitfield of AP capabilities, e.g. NM_802_11_AP_FLAGS_PRIVACY -	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 WiFi channel to its corresponding frequency. +

++++ + - - + + - - + + - +

`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)	`channel` :	channel
`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)	`band` :	frequency band for wireless ("a" or "bg")
Returns :	TRUE if the device capabilities and AP capabilties intersect and are -compatible with the desired `type`, FALSE if they are not	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_slist_free ()

void                nm_utils_slist_free                 (GSList *list,
-                                                         GDestroyNotify elem_destroy_fn);

nm_utils_wifi_find_next_channel ()

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

-Utility function to free a GSList. +Utility function to find out next/previous WiFi channel for a channel.

+++ - - + + - - + + + + + + + + + +

`list` :	a GSList -	`channel` :	current channel
`elem_destroy_fn` :	user function called for each element in `list` -	`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_ssid_to_utf8 ()

char *              nm_utils_ssid_to_utf8               (const GByteArray *ssid);

-WiFi 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 '?'. -

nm_utils_wifi_is_channel_valid ()

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

-Again, this function should be used for debugging and display purposes -_only_. +Utility function to verify WiFi channel validity.

+++ - - + + + + + + - +

`ssid` :	a byte array containing the SSID data	`channel` :	channel
`band` :	frequency band for wireless ("a" or "bg")
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] -	TRUE or FALSE

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_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_uuid_generate_from_string ()

char *              nm_utils_uuid_generate_from_string  (const char *s);

nm_utils_hwaddr_len ()

int                 nm_utils_hwaddr_len                 (int type);

-For a given s, this function will always return the same UUID. +Returns the length in octets of a hardware address of type type.

+++ - - + + - +

`s` :	a string to use as the seed for the UUID	`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +
Returns :	a newly allocated UUID suitable for use as the NMSettingConnection -object's "id": property	the length

nm_utils_wep_key_valid ()

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

nm_utils_hwaddr_type ()

int                 nm_utils_hwaddr_type                (int len);

-Checks if key is a valid WEP key +Returns the type (either ARPHRD_ETHER or ARPHRD_INFINIBAND) of the raw +address given its length.

+++ - - - - - - + + - +

`key` :	a string that might be a WEP key
`wep_type` :	the NMWepKeyType type of the WEP key	`len` :	the length of hardware address in bytes
Returns :	-`TRUE` if `key` is a WEP key, `FALSE` if not	the type, either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`, or -1 if +the address length was not recognized

Since 0.9.8

nm_utils_wifi_channel_to_freq ()

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

nm_utils_hwaddr_ntoa ()

char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
+                                                         int type);

-Utility function to translate a WiFi channel to its corresponding frequency. +Converts addr to textual form.

+++ - - + + - - + + - +

`channel` :	channel	`addr` :	a binary hardware address
`band` :	frequency band for wireless ("a" or "bg")	`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +
Returns :	the frequency represented by the channel of the band, -or -1 when the freq is invalid, or 0 when the band -is invalid	the textual form of `addr`. [transfer full] +

nm_utils_wifi_find_next_channel ()

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

nm_utils_hwaddr_atoba ()

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

-Utility function to find out next/previous WiFi channel for a channel. +Parses asc and converts it to binary form in a GByteArray. See +nm_utils_hwaddr_aton() if you don't want a GByteArray.

+++ - - - - - - + + - - + + - +

`channel` :	current channel
`direction` :	whether going downward (0 or less) or upward (1 or more)	`asc` :	the ASCII representation of a hardware address
`band` :	frequency band for wireless ("a" or "bg")	`type` :	the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` +
Returns :	the next channel in the specified direction or 0	a new GByteArray, or `NULL` if `asc` couldn't +be parsed. [transfer full] +

nm_utils_wifi_freq_to_channel ()

guint32             nm_utils_wifi_freq_to_channel       (guint32 freq);

nm_utils_hwaddr_aton ()

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

-Utility function to translate a WiFi frequency to its corresponding channel. +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.

+++ - - + + + + + + + + + + - +

`freq` :	frequency	`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 :	the channel represented by the frequency or 0	+`buffer`, or `NULL` if `asc` couldn't be parsed

nm_utils_wifi_is_channel_valid ()

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

nm_utils_iface_valid_name ()

gboolean            nm_utils_iface_valid_name           (const char *name);

-Utility function to verify WiFi channel validity. +This function is a 1:1 copy of the kernel's interface validation +function in net/core/dev.c.

+++ - - - - - - + + - +

`channel` :	channel
`band` :	frequency band for wireless ("a" or "bg")	`name` :	Name of interface
Returns :	TRUE or FALSE	+`TRUE` if interface name is valid, otherwise `FALSE` is returned.

Since 0.9.8

nm_utils_wpa_psk_valid ()

gboolean            nm_utils_wpa_psk_valid              (const char *psk);

nm_utils_is_uuid ()

gboolean            nm_utils_is_uuid                    (const char *str);

-Checks if psk is a valid WPA PSK +Checks if str is a UUID

+++ - - + + +TRUE if str is a UUID, FALSE if not

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

@@ -1319,6 +1439,6 @@ Checks if psk is a valid WPA PSK

+ Generated by GTK-Doc V1.19