GNOME.org
 

NetworkManager r4321 - in trunk: . libnm-util

Author: dcbw
Date: Thu Nov 20 21:07:03 2008
New Revision: 4321
URL: http://svn.gnome.org/viewvc/NetworkManager?rev=4321&view=rev

Log:
2008-11-20  Dan Williams  <dcbw redhat com>

	* libnm-util/nm-utils.c
	  libnm-util/nm-utils.h
		- More documentation updates



Modified:
   trunk/ChangeLog
   trunk/libnm-util/nm-utils.c
   trunk/libnm-util/nm-utils.h

Modified: trunk/libnm-util/nm-utils.c
==============================================================================
--- trunk/libnm-util/nm-utils.c	(original)
+++ trunk/libnm-util/nm-utils.c	Thu Nov 20 21:07:03 2008
@@ -812,9 +812,30 @@
 	return (have_pair && have_group);
 }
 
+/**
+ * nm_utils_security_valid:
+ * @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)
+ * @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)
+ *
+ * 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.
+ *
+ * Returns: TRUE if the device capabilities and AP capabilties intersect and are
+ * compatible with the desired @type, FALSE if they are not
+ **/
 gboolean
 nm_utils_security_valid (NMUtilsSecurityType type,
-                         guint32 dev_caps,
+                         guint32 wifi_caps,
                          gboolean have_ap,
                          gboolean adhoc,
                          guint32 ap_flags,
@@ -829,7 +850,7 @@
 		if (   (type == NMU_SEC_STATIC_WEP)
 		    || ((type == NMU_SEC_DYNAMIC_WEP) && !adhoc)
 		    || ((type == NMU_SEC_LEAP) && !adhoc)) {
-			if (dev_caps & (NM_WIFI_DEVICE_CAP_CIPHER_WEP40 | NM_WIFI_DEVICE_CAP_CIPHER_WEP104))
+			if (wifi_caps & (NM_WIFI_DEVICE_CAP_CIPHER_WEP40 | NM_WIFI_DEVICE_CAP_CIPHER_WEP104))
 				return TRUE;
 		}
 	}
@@ -851,8 +872,8 @@
 		if (!(ap_flags & NM_802_11_AP_FLAGS_PRIVACY))
 			return FALSE;
 		if (ap_wpa || ap_rsn) {
-			if (!device_supports_ap_ciphers (dev_caps, ap_wpa, TRUE))
-				if (!device_supports_ap_ciphers (dev_caps, ap_rsn, TRUE))
+			if (!device_supports_ap_ciphers (wifi_caps, ap_wpa, TRUE))
+				if (!device_supports_ap_ciphers (wifi_caps, ap_rsn, TRUE))
 					return FALSE;
 		}
 		break;
@@ -866,12 +887,12 @@
 		if (ap_wpa) {
 			if (!(ap_wpa & NM_802_11_AP_SEC_KEY_MGMT_802_1X))
 				return FALSE;
-			if (!device_supports_ap_ciphers (dev_caps, ap_wpa, FALSE))
+			if (!device_supports_ap_ciphers (wifi_caps, ap_wpa, FALSE))
 				return FALSE;
 		}
 		break;
 	case NMU_SEC_WPA_PSK:
-		if (!(dev_caps & NM_WIFI_DEVICE_CAP_WPA))
+		if (!(wifi_caps & NM_WIFI_DEVICE_CAP_WPA))
 			return FALSE;
 		if (have_ap) {
 			if (!(ap_flags & NM_802_11_AP_FLAGS_PRIVACY))
@@ -879,17 +900,17 @@
 
 			if (ap_wpa & NM_802_11_AP_SEC_KEY_MGMT_PSK) {
 				if (   (ap_wpa & NM_802_11_AP_SEC_PAIR_TKIP)
-				    && (dev_caps & NM_WIFI_DEVICE_CAP_CIPHER_TKIP))
+				    && (wifi_caps & NM_WIFI_DEVICE_CAP_CIPHER_TKIP))
 					return TRUE;
 				if (   (ap_wpa & NM_802_11_AP_SEC_PAIR_CCMP)
-				    && (dev_caps & NM_WIFI_DEVICE_CAP_CIPHER_CCMP))
+				    && (wifi_caps & NM_WIFI_DEVICE_CAP_CIPHER_CCMP))
 					return TRUE;
 			}
 			return FALSE;
 		}
 		break;
 	case NMU_SEC_WPA2_PSK:
-		if (!(dev_caps & NM_WIFI_DEVICE_CAP_RSN))
+		if (!(wifi_caps & NM_WIFI_DEVICE_CAP_RSN))
 			return FALSE;
 		if (have_ap) {
 			if (!(ap_flags & NM_802_11_AP_FLAGS_PRIVACY))
@@ -897,10 +918,10 @@
 
 			if (ap_rsn & NM_802_11_AP_SEC_KEY_MGMT_PSK) {
 				if (   (ap_rsn & NM_802_11_AP_SEC_PAIR_TKIP)
-				    && (dev_caps & NM_WIFI_DEVICE_CAP_CIPHER_TKIP))
+				    && (wifi_caps & NM_WIFI_DEVICE_CAP_CIPHER_TKIP))
 					return TRUE;
 				if (   (ap_rsn & NM_802_11_AP_SEC_PAIR_CCMP)
-				    && (dev_caps & NM_WIFI_DEVICE_CAP_CIPHER_CCMP))
+				    && (wifi_caps & NM_WIFI_DEVICE_CAP_CIPHER_CCMP))
 					return TRUE;
 			}
 			return FALSE;
@@ -909,7 +930,7 @@
 	case NMU_SEC_WPA_ENTERPRISE:
 		if (adhoc)
 			return FALSE;
-		if (!(dev_caps & NM_WIFI_DEVICE_CAP_WPA))
+		if (!(wifi_caps & NM_WIFI_DEVICE_CAP_WPA))
 			return FALSE;
 		if (have_ap) {
 			if (!(ap_flags & NM_802_11_AP_FLAGS_PRIVACY))
@@ -917,14 +938,14 @@
 			if (!(ap_wpa & NM_802_11_AP_SEC_KEY_MGMT_802_1X))
 				return FALSE;
 			/* Ensure at least one WPA cipher is supported */
-			if (!device_supports_ap_ciphers (dev_caps, ap_wpa, FALSE))
+			if (!device_supports_ap_ciphers (wifi_caps, ap_wpa, FALSE))
 				return FALSE;
 		}
 		break;
 	case NMU_SEC_WPA2_ENTERPRISE:
 		if (adhoc)
 			return FALSE;
-		if (!(dev_caps & NM_WIFI_DEVICE_CAP_RSN))
+		if (!(wifi_caps & NM_WIFI_DEVICE_CAP_RSN))
 			return FALSE;
 		if (have_ap) {
 			if (!(ap_flags & NM_802_11_AP_FLAGS_PRIVACY))
@@ -932,7 +953,7 @@
 			if (!(ap_rsn & NM_802_11_AP_SEC_KEY_MGMT_802_1X))
 				return FALSE;
 			/* Ensure at least one WPA cipher is supported */
-			if (!device_supports_ap_ciphers (dev_caps, ap_rsn, FALSE))
+			if (!device_supports_ap_ciphers (wifi_caps, ap_rsn, FALSE))
 				return FALSE;
 		}
 		break;
@@ -944,6 +965,18 @@
 	return good;
 }
 
+/**
+ * nm_utils_ip4_addresses_from_gvalue:
+ * @value: gvalue containing a GPtrArray of GArrays of guint32s
+ *
+ * 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.
+ *
+ * Returns: a newly allocated #GSList of #NMIP4Address objects
+ **/
 GSList *
 nm_utils_ip4_addresses_from_gvalue (const GValue *value)
 {
@@ -956,7 +989,7 @@
 		GArray *array = (GArray *) g_ptr_array_index (addresses, i);
 		NMIP4Address *addr;
 
-		if (array->len != 3) {
+		if (array->len < 3) {
 			nm_warning ("Ignoring invalid IP4 address");
 			continue;
 		}
@@ -971,6 +1004,19 @@
 	return g_slist_reverse (list);
 }
 
+/**
+ * nm_utils_ip4_addresses_to_gvalue:
+ * @list: a list of #NMIP4Address objects
+ * @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().
+ *
+ * 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.
+ **/
 void
 nm_utils_ip4_addresses_to_gvalue (GSList *list, GValue *value)
 {
@@ -1001,6 +1047,18 @@
 	g_value_take_boxed (value, addresses);
 }
 
+/**
+ * nm_utils_ip4_routes_from_gvalue:
+ * @value: gvalue containing a GPtrArray of GArrays of guint32s
+ *
+ * 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.
+ *
+ * Returns: a newly allocated #GSList of #NMIP4Route objects
+ **/
 GSList *
 nm_utils_ip4_routes_from_gvalue (const GValue *value)
 {
@@ -1013,7 +1071,7 @@
 		GArray *array = (GArray *) g_ptr_array_index (routes, i);
 		NMIP4Route *route;
 
-		if (array->len != 4) {
+		if (array->len < 4) {
 			nm_warning ("Ignoring invalid IP4 route");
 			continue;
 		}
@@ -1029,6 +1087,19 @@
 	return g_slist_reverse (list);
 }
 
+/**
+ * nm_utils_ip4_routes_to_gvalue:
+ * @list: a list of #NMIP4Route objects
+ * @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().
+ *
+ * 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.
+ **/
 void
 nm_utils_ip4_routes_to_gvalue (GSList *list, GValue *value)
 {
@@ -1062,13 +1133,12 @@
 	g_value_take_boxed (value, routes);
 }
 
-/*
- * nm_utils_ip4_netmask_to_prefix
- *
- * Figure out the network prefix from a netmask.  Netmask
- * MUST be in network byte order.
+/**
+ * nm_utils_ip4_netmask_to_prefix:
+ * @netmask: an IPv4 netmask in network byte order
  *
- */
+ * Returns: the CIDR prefix represented by the netmask
+ **/
 guint32
 nm_utils_ip4_netmask_to_prefix (guint32 netmask)
 {
@@ -1095,12 +1165,12 @@
 	return prefix;
 }
 
-/*
- * nm_utils_ip4_prefix_to_netmask
+/**
+ * nm_utils_ip4_prefix_to_netmask:
+ * @prefix: a CIDR prefix
  *
- * Figure out the netmask from a prefix.
- *
- */
+ * Returns: the netmask represented by the prefix
+ **/
 guint32
 nm_utils_ip4_prefix_to_netmask (guint32 prefix)
 {
@@ -1116,6 +1186,7 @@
 	return (guint32) htonl (netmask);
 }
 
+
 GSList *
 nm_utils_ip6_addresses_from_gvalue (const GValue *value)
 {
@@ -1255,6 +1326,12 @@
 	g_value_take_boxed (value, dns);
 }
 
+/**
+ * nm_utils_uuid_generate:
+ *
+ * Returns: a newly allocated UUID suitable for use as the #NMSettingConnection
+ * object's #NMSettingConnection:id: property.  Should be freed with g_free()
+ **/
 char *
 nm_utils_uuid_generate (void)
 {
@@ -1267,6 +1344,15 @@
 	return buf;
 }
 
+/**
+ * nm_utils_uuid_generate_from_string:
+ * @s: a string to use as the seed for the UUID
+ *
+ * For a given @s, this function will always return the same UUID.
+ *
+ * Returns: a newly allocated UUID suitable for use as the #NMSettingConnection
+ * object's #NMSettingConnection:id: property
+ **/
 char *
 nm_utils_uuid_generate_from_string (const char *s)
 {

Modified: trunk/libnm-util/nm-utils.h
==============================================================================
--- trunk/libnm-util/nm-utils.h	(original)
+++ trunk/libnm-util/nm-utils.h	Thu Nov 20 21:07:03 2008
@@ -168,7 +168,7 @@
 } NMUtilsSecurityType;
 
 gboolean nm_utils_security_valid (NMUtilsSecurityType type,
-                                  guint32 dev_caps,
+                                  guint32 wifi_caps,
                                   gboolean have_ap,
                                   gboolean adhoc,
                                   guint32 ap_flags,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]