nm-utils

nm-utils — Utility functions

Synopsis

#include <nm-utils.h>

enum                NMUtilsSecurityType;
#define             NM_UTILS_HWADDR_LEN_MAX
void                nm_utils_deinit                     (void);
const char *        nm_utils_escape_ssid                (const guint8 *ssid,
                                                         guint32 len);
GHashTable *        nm_utils_gvalue_hash_dup            (GHashTable *hash);
GByteArray *        nm_utils_hwaddr_atoba               (const char *asc,
                                                         int type);
guint8 *            nm_utils_hwaddr_aton                (const char *asc,
                                                         int type,
                                                         gpointer buffer);
int                 nm_utils_hwaddr_len                 (int type);
char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
                                                         int type);
int                 nm_utils_hwaddr_type                (int len);
gboolean            nm_utils_init                       (GError **error);
GSList *            nm_utils_ip4_addresses_from_gvalue  (const GValue *value);
void                nm_utils_ip4_addresses_to_gvalue    (GSList *list,
                                                         GValue *value);
guint32             nm_utils_ip4_get_default_prefix     (guint32 ip);
guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);
guint32             nm_utils_ip4_prefix_to_netmask      (guint32 prefix);
GSList *            nm_utils_ip4_routes_from_gvalue     (const GValue *value);
void                nm_utils_ip4_routes_to_gvalue       (GSList *list,
                                                         GValue *value);
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_dns_from_gvalue        (const GValue *value);
void                nm_utils_ip6_dns_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);
gboolean            nm_utils_is_empty_ssid              (const guint8 *ssid,
                                                         int len);
GByteArray *        nm_utils_rsa_key_encrypt            (const GByteArray *data,
                                                         const char *in_password,
                                                         char **out_password,
                                                         GError **error);
gboolean            nm_utils_same_ssid                  (const GByteArray *ssid1,
                                                         const GByteArray *ssid2,
                                                         gboolean ignore_trailing_null);
gboolean            nm_utils_security_valid             (NMUtilsSecurityType type,
                                                         NMDeviceWifiCapabilities wifi_caps,
                                                         gboolean have_ap,
                                                         gboolean adhoc,
                                                         NM80211ApFlags ap_flags,
                                                         NM80211ApSecurityFlags ap_wpa,
                                                         NM80211ApSecurityFlags ap_rsn);
void                nm_utils_slist_free                 (GSList *list,
                                                         GDestroyNotify elem_destroy_fn);
char *              nm_utils_ssid_to_utf8               (const GByteArray *ssid);
char *              nm_utils_uuid_generate              (void);
char *              nm_utils_uuid_generate_from_string  (const char *s);
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);
guint32             nm_utils_wifi_freq_to_channel       (guint32 freq);
gboolean            nm_utils_wifi_is_channel_valid      (guint32 channel,
                                                         const char *band);

Object Hierarchy

  GEnum
   +----NMUtilsSecurityType

Description

A collection of utility functions for working SSIDs, IP addresses, WiFi 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;

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

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

nm_utils_hwaddr_ntoa ()

char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
                                                         int type);

Converts addr to textual form.

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_type ()

int                 nm_utils_hwaddr_type                (int len);

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, or -1 if the address length was not recognized

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