![]() |
![]() |
![]() |
libnm-util Reference Manual | |
---|---|---|---|---|
#include <nm-utils.h> #define nm_print_backtrace () #define nm_get_timestamp (timestamp) #define nm_info (fmt, args...) #define nm_info_str (fmt_str, args...) #define nm_debug (fmt, args...) #define nm_debug_str (fmt_str, args...) #define nm_warning (fmt, args...) #define nm_warning_str (fmt_str, args...) #define nm_error (fmt, args...) #define nm_error_str (fmt_str, args...) 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 char *ssid, guint32 len); 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, guint32 wifi_caps, gboolean have_ap, gboolean adhoc, guint32 ap_flags, guint32 ap_wpa, guint32 ap_rsn); 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); char* nm_utils_uuid_generate (void); char* nm_utils_uuid_generate_from_string (const char *s);
A collection of utility functions for working SSIDs, IP addresses, WiFi access points and devices, among other things.
#define nm_print_backtrace()
Prints a backtrace of the calling process to the logging location.
#define nm_get_timestamp(timestamp)
For debugging only.
|
location in which to place the current timestamp |
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.
|
location to store error, or NULL
|
Returns : |
TRUE if the initialization was successful, FALSE on failure. |
void nm_utils_deinit (void);
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.
|
pointer to a buffer containing the SSID data |
|
length of the SSID data in ssid
|
Returns : |
TRUE if the SSID is "empty", FALSE if it is not |
gboolean nm_utils_is_empty_ssid (const guint8 *ssid, int len);
|
|
|
|
Returns : |
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.
|
pointer to a buffer containing the SSID data |
|
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 |
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.
|
first SSID data to compare |
|
second SSID data to compare |
|
TRUE to ignore one trailing NULL byte |
Returns : |
TRUE if the SSIDs are the same, FALSE if they are not |
char* nm_utils_ssid_to_utf8 (const char *ssid, guint32 len);
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_.
|
pointer to a buffer containing the SSID data |
|
length of the SSID data in ssid
|
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.
|
GHashTable* nm_utils_gvalue_hash_dup (GHashTable *hash);
Utility function to duplicate a hash table of GValues.
|
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()
|
void nm_utils_slist_free (GSList *list, GDestroyNotify elem_destroy_fn);
Utility function to free a GSList.
|
a GSList |
|
user function called for each element in list
|
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;
gboolean nm_utils_security_valid (NMUtilsSecurityType type, guint32 wifi_caps, gboolean have_ap, gboolean adhoc, guint32 ap_flags, guint32 ap_wpa, guint32 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.
|
the security type to check AP flags and device capabilties against, e.g. NMU_SEC_STATIC_WEP |
|
bitfield of the capabilities of the specific WiFi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40 |
|
whether the ap_flags , ap_wpa , and ap_rsn arguments are valid
|
|
whether the capabilities being tested are from an Ad-Hoc AP (IBSS) |
|
bitfield of AP capabilities, e.g. NM_802_11_AP_FLAGS_PRIVACY |
|
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) |
|
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
|
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.
|
gvalue containing a GPtrArray of GArrays of guint32s |
Returns : |
a newly allocated GSList of NMIP4Address objects |
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.
|
a list of NMIP4Address objects |
|
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() .
|
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.
|
gvalue containing a GPtrArray of GArrays of guint32s |
Returns : |
a newly allocated GSList of NMIP4Route objects |
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.
|
a list of NMIP4Route objects |
|
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() .
|
guint32 nm_utils_ip4_netmask_to_prefix (guint32 netmask);
|
an IPv4 netmask in network byte order |
Returns : |
the CIDR prefix represented by the netmask |
guint32 nm_utils_ip4_prefix_to_netmask (guint32 prefix);
|
a CIDR prefix |
Returns : |
the netmask represented by the prefix |
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()
|
char* nm_utils_uuid_generate_from_string (const char *s);
For a given s
, this function will always return the same UUID.
|
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 |