NetworkManager r4319 - in trunk: . libnm-util

[dcbw svn gnome org]

Author: dcbw
Date: Thu Nov 20 20:17:01 2008
New Revision: 4319
URL: http://svn.gnome.org/viewvc/NetworkManager?rev=4319&view=rev

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

	* libnm-util/Makefile.am
	  libnm-util/nm-utils-private.h
		- New header for internal utils private functions

	* libnm-util/libnm-util.ver
	  libnm-util/nm-utils.c
	  libnm-util/nm-utils.h
		- Document some functions
		- (nm_utils_string_in_list, nm_utils_string_list_contains,
		   nm_utils_string_slist_validate): un-export, only used within
			libnm-util or of limited use in general, and very easy to
			re-implement by apps if needed

	* libnm-util/nm-setting-8021x.c
	  libnm-util/nm-setting-wired.c
	  libnm-util/nm-setting-wireless-security.c
	  libnm-util/nm-setting-wireless.c
		- Update for private nm_utils_string_* functions



Added:
   trunk/libnm-util/nm-utils-private.h
Modified:
   trunk/ChangeLog
   trunk/libnm-util/Makefile.am
   trunk/libnm-util/libnm-util.ver
   trunk/libnm-util/nm-setting-8021x.c
   trunk/libnm-util/nm-setting-wired.c
   trunk/libnm-util/nm-setting-wireless-security.c
   trunk/libnm-util/nm-setting-wireless.c
   trunk/libnm-util/nm-utils.c
   trunk/libnm-util/nm-utils.h

Modified: trunk/libnm-util/Makefile.am
==============================================================================
--- trunk/libnm-util/Makefile.am	(original)
+++ trunk/libnm-util/Makefile.am	Thu Nov 20 20:17:01 2008
@@ -47,6 +47,7 @@
 	nm-setting-wireless-security.c	\
 	nm-setting-vpn.c		\
 	nm-utils.c			\
+	nm-utils-private.h \
 	$(libnm_util_include_HEADERS)
 
 libnm_util_la_LIBADD = $(GLIB_LIBS) $(DBUS_LIBS) $(UUID_LIBS)

Modified: trunk/libnm-util/libnm-util.ver
==============================================================================
--- trunk/libnm-util/libnm-util.ver	(original)
+++ trunk/libnm-util/libnm-util.ver	Thu Nov 20 20:17:01 2008
@@ -259,9 +259,6 @@
 	nm_utils_security_valid;
 	nm_utils_slist_free;
 	nm_utils_ssid_to_utf8;
-	nm_utils_string_in_list;
-	nm_utils_string_list_contains;
-	nm_utils_string_slist_validate;
 	nm_utils_uuid_generate;
 	nm_utils_uuid_generate_from_string;
 	nm_ip4_address_compare;

Modified: trunk/libnm-util/nm-setting-8021x.c
==============================================================================
--- trunk/libnm-util/nm-setting-8021x.c	(original)
+++ trunk/libnm-util/nm-setting-8021x.c	Thu Nov 20 20:17:01 2008
@@ -31,6 +31,7 @@
 #include "nm-utils.h"
 #include "nm-dbus-glib-types.h"
 #include "crypto.h"
+#include "nm-utils-private.h"
 
 GQuark
 nm_setting_802_1x_error_quark (void)
@@ -1038,7 +1039,7 @@
 		return FALSE;
 	}
 
-	if (!nm_utils_string_slist_validate (priv->eap, valid_eap)) {
+	if (!_nm_utils_string_slist_validate (priv->eap, valid_eap)) {
 		g_set_error (error,
 		             NM_SETTING_802_1X_ERROR,
 		             NM_SETTING_802_1X_ERROR_INVALID_PROPERTY,
@@ -1062,7 +1063,7 @@
 		}
 	}
 
-	if (priv->phase1_peapver && !nm_utils_string_in_list (priv->phase1_peapver, valid_phase1_peapver)) {
+	if (priv->phase1_peapver && !_nm_utils_string_in_list (priv->phase1_peapver, valid_phase1_peapver)) {
 		g_set_error (error,
 		             NM_SETTING_802_1X_ERROR,
 		             NM_SETTING_802_1X_ERROR_INVALID_PROPERTY,
@@ -1070,7 +1071,7 @@
 		return FALSE;
 	}
 
-	if (priv->phase1_peaplabel && !nm_utils_string_in_list (priv->phase1_peaplabel, valid_phase1_peaplabel)) {
+	if (priv->phase1_peaplabel && !_nm_utils_string_in_list (priv->phase1_peaplabel, valid_phase1_peaplabel)) {
 		g_set_error (error,
 		             NM_SETTING_802_1X_ERROR,
 		             NM_SETTING_802_1X_ERROR_INVALID_PROPERTY,
@@ -1086,7 +1087,7 @@
 		return FALSE;
 	}
 
-	if (priv->phase2_auth && !nm_utils_string_in_list (priv->phase2_auth, valid_phase2_auth)) {
+	if (priv->phase2_auth && !_nm_utils_string_in_list (priv->phase2_auth, valid_phase2_auth)) {
 		g_set_error (error,
 		             NM_SETTING_802_1X_ERROR,
 		             NM_SETTING_802_1X_ERROR_INVALID_PROPERTY,
@@ -1094,7 +1095,7 @@
 		return FALSE;
 	}
 
-	if (priv->phase2_autheap && !nm_utils_string_in_list (priv->phase2_autheap, valid_phase2_autheap)) {
+	if (priv->phase2_autheap && !_nm_utils_string_in_list (priv->phase2_autheap, valid_phase2_autheap)) {
 		g_set_error (error,
 		             NM_SETTING_802_1X_ERROR,
 		             NM_SETTING_802_1X_ERROR_INVALID_PROPERTY,

Modified: trunk/libnm-util/nm-setting-wired.c
==============================================================================
--- trunk/libnm-util/nm-setting-wired.c	(original)
+++ trunk/libnm-util/nm-setting-wired.c	Thu Nov 20 20:17:01 2008
@@ -28,6 +28,7 @@
 #include "nm-setting-wired.h"
 #include "nm-param-spec-specialized.h"
 #include "nm-utils.h"
+#include "nm-utils-private.h"
 
 GQuark
 nm_setting_wired_error_quark (void)
@@ -149,7 +150,7 @@
 	const char *valid_ports[] = { "tp", "aui", "bnc", "mii", NULL };
 	const char *valid_duplex[] = { "half", "full", NULL };
 
-	if (priv->port && !nm_utils_string_in_list (priv->port, valid_ports)) {
+	if (priv->port && !_nm_utils_string_in_list (priv->port, valid_ports)) {
 		g_set_error (error,
 		             NM_SETTING_WIRED_ERROR,
 		             NM_SETTING_WIRED_ERROR_INVALID_PROPERTY,
@@ -157,7 +158,7 @@
 		return FALSE;
 	}
 
-	if (priv->duplex && !nm_utils_string_in_list (priv->duplex, valid_duplex)) {
+	if (priv->duplex && !_nm_utils_string_in_list (priv->duplex, valid_duplex)) {
 		g_set_error (error,
 		             NM_SETTING_WIRED_ERROR,
 		             NM_SETTING_WIRED_ERROR_INVALID_PROPERTY,

Modified: trunk/libnm-util/nm-setting-wireless-security.c
==============================================================================
--- trunk/libnm-util/nm-setting-wireless-security.c	(original)
+++ trunk/libnm-util/nm-setting-wireless-security.c	Thu Nov 20 20:17:01 2008
@@ -31,6 +31,7 @@
 #include "nm-param-spec-specialized.h"
 #include "nm-utils.h"
 #include "nm-dbus-glib-types.h"
+#include "nm-utils-private.h"
 
 GQuark
 nm_setting_wireless_security_error_quark (void)
@@ -565,7 +566,7 @@
 		return FALSE;
 	}
 
-	if (!nm_utils_string_in_list (priv->key_mgmt, valid_key_mgmt)) {
+	if (!_nm_utils_string_in_list (priv->key_mgmt, valid_key_mgmt)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY,
@@ -648,7 +649,7 @@
 		return FALSE;
 	}
 
-	if (priv->auth_alg && !nm_utils_string_in_list (priv->auth_alg, valid_auth_algs)) {
+	if (priv->auth_alg && !_nm_utils_string_in_list (priv->auth_alg, valid_auth_algs)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY,
@@ -656,7 +657,7 @@
 		return FALSE;
 	}
 
-	if (priv->proto && !nm_utils_string_slist_validate (priv->proto, valid_protos)) {
+	if (priv->proto && !_nm_utils_string_slist_validate (priv->proto, valid_protos)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY,
@@ -668,7 +669,7 @@
 		const char *wpa_none[] = { "wpa-none", NULL };
 
 		/* For ad-hoc connections, pairwise must be "none" */
-		if (nm_utils_string_in_list (priv->key_mgmt, wpa_none)) {
+		if (_nm_utils_string_in_list (priv->key_mgmt, wpa_none)) {
 			GSList *iter;
 			gboolean found = FALSE;
 
@@ -689,7 +690,7 @@
 				             NM_SETTING_WIRELESS_SECURITY_PAIRWISE);
 				return FALSE;
 			}
-		} else if (!nm_utils_string_slist_validate (priv->pairwise, valid_pairwise)) {
+		} else if (!_nm_utils_string_slist_validate (priv->pairwise, valid_pairwise)) {
 			g_set_error (error,
 			             NM_SETTING_WIRELESS_SECURITY_ERROR,
 			             NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY,
@@ -698,7 +699,7 @@
 		}
 	}
 
-	if (priv->group && !nm_utils_string_slist_validate (priv->group, valid_groups)) {
+	if (priv->group && !_nm_utils_string_slist_validate (priv->group, valid_groups)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR,
 		             NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY,

Modified: trunk/libnm-util/nm-setting-wireless.c
==============================================================================
--- trunk/libnm-util/nm-setting-wireless.c	(original)
+++ trunk/libnm-util/nm-setting-wireless.c	Thu Nov 20 20:17:01 2008
@@ -34,6 +34,7 @@
 #include "nm-param-spec-specialized.h"
 #include "nm-utils.h"
 #include "nm-dbus-glib-types.h"
+#include "nm-utils-private.h"
 
 GQuark
 nm_setting_wireless_error_quark (void)
@@ -457,7 +458,7 @@
 		return FALSE;
 	}
 
-	if (priv->mode && !nm_utils_string_in_list (priv->mode, valid_modes)) {
+	if (priv->mode && !_nm_utils_string_in_list (priv->mode, valid_modes)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_ERROR,
 		             NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY,
@@ -465,7 +466,7 @@
 		return FALSE;
 	}
 
-	if (priv->band && !nm_utils_string_in_list (priv->band, valid_bands)) {
+	if (priv->band && !_nm_utils_string_in_list (priv->band, valid_bands)) {
 		g_set_error (error,
 		             NM_SETTING_WIRELESS_ERROR,
 		             NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY,

Added: trunk/libnm-util/nm-utils-private.h
==============================================================================
--- (empty file)
+++ trunk/libnm-util/nm-utils-private.h	Thu Nov 20 20:17:01 2008
@@ -0,0 +1,35 @@
+/* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */
+/* NetworkManager -- Network link manager
+ *
+ * Ray Strode <rstrode redhat com>
+ * Dan Williams <dcbw redhat com>
+ * Tambet Ingo <tambet gmail com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301 USA.
+ *
+ * (C) Copyright 2005 - 2008 Red Hat, Inc.
+ */
+
+#ifndef __NM_UTILS_PRIVATE_H__
+#define __NM_UTILS_PRIVATE_H__
+
+gboolean    _nm_utils_string_in_list   (const char *str,
+                                        const char **valid_strings);
+
+gboolean    _nm_utils_string_slist_validate (GSList *list,
+                                             const char **valid_values);
+
+#endif

Modified: trunk/libnm-util/nm-utils.c
==============================================================================
--- trunk/libnm-util/nm-utils.c	(original)
+++ trunk/libnm-util/nm-utils.c	Thu Nov 20 20:17:01 2008
@@ -38,6 +38,7 @@
 #include <uuid/uuid.h>
 
 #include "nm-utils.h"
+#include "nm-utils-private.h"
 #include "NetworkManager.h"
 #include "nm-dbus-glib-types.h"
 #include "nm-setting-ip4-config.h"
@@ -254,19 +255,38 @@
 
 static gboolean initialized = FALSE;
 
+/**
+ * nm_utils_init:
+ * @error: location to store error, or %NULL
+ *
+ * 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.
+ * 
+ * Returns: TRUE if the initialization was successful, FALSE on failure.
+ **/
 gboolean
 nm_utils_init (GError **error)
 {
 	if (!initialized) {
-		if (!crypto_init (error)) {
+		if (!crypto_init (error))
 			return FALSE;
-		}
+
 		atexit (nm_utils_deinit);
 		initialized = TRUE;
 	}
 	return TRUE;
 }
 
+/**
+ * nm_utils_deinit:
+ *
+ * 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.
+ **/
 void
 nm_utils_deinit (void)
 {
@@ -278,6 +298,38 @@
 
 /* ssid helpers */
 
+/**
+ * nm_utils_ssid_to_utf8:
+ * @ssid: pointer to a buffer containing the SSID data
+ * @len: length of the SSID data in @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 '?'.
+ *
+ * Again, this function should be used for debugging and display purposes
+ * _only_.
+ *
+ * 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.
+ **/
 char *
 nm_utils_ssid_to_utf8 (const char *ssid, guint32 len)
 {
@@ -295,6 +347,17 @@
 }
 
 /* Shamelessly ripped from the Linux kernel ieee80211 stack */
+/**
+ * nm_utils_deinit:
+ * @ssid: pointer to a buffer containing the SSID data
+ * @len: length of the SSID data in @ssid
+ *
+ * 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.
+ *
+ * Returns: TRUE if the SSID is "empty", FALSE if it is not
+ **/
 gboolean
 nm_utils_is_empty_ssid (const guint8 * ssid, int len)
 {
@@ -310,6 +373,19 @@
         return TRUE;
 }
 
+/**
+ * nm_utils_escape_ssid:
+ * @ssid: pointer to a buffer containing the SSID data
+ * @len: length of the SSID data in @ssid
+ *
+ * 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.
+ *
+ * Returns: pointer to the escaped SSID, which uses an internal static buffer
+ * and will be overwritten by subsequent calls to this function
+ **/
 const char *
 nm_utils_escape_ssid (const guint8 * ssid, guint32 len)
 {
@@ -336,6 +412,21 @@
 	return escaped;
 }
 
+/**
+ * nm_utils_escape_ssid:
+ * @ssid1: first SSID data to compare
+ * @ssid2: second SSID data to compare
+ * @ignore_trailing_null: TRUE to ignore one trailing NULL byte
+ *
+ * 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.
+ *
+ * Returns: TRUE if the SSIDs are the same, FALSE if they are not
+ **/
 gboolean
 nm_utils_same_ssid (const GByteArray * ssid1,
                     const GByteArray * ssid2,
@@ -386,6 +477,15 @@
 	g_hash_table_insert (table, g_strdup ((char *) key), dup_value);
 }
 
+/**
+ * nm_utils_gvalue_hash_dup:
+ * @hash: a #GHashTable mapping string:GValue
+ *
+ * Utility function to duplicate a hash table of GValues.
+ *
+ * Returns: a newly allocated duplicated #GHashTable, caller must free the
+ * returned hash with g_hash_table_unref() or g_hash_table_destroy()
+ **/
 GHashTable *
 nm_utils_gvalue_hash_dup (GHashTable *hash)
 {
@@ -402,6 +502,13 @@
 	return table;
 }
 
+/**
+ * nm_utils_slist_free:
+ * @list: a #GSList
+ * @elem_destroy_fn: user function called for each element in @list
+ *
+ * Utility function to free a #GSList.
+ **/
 void
 nm_utils_slist_free (GSList *list, GDestroyNotify elem_destroy_fn)
 {
@@ -415,7 +522,7 @@
 }
 
 gboolean
-nm_utils_string_in_list (const char *str, const char **valid_strings)
+_nm_utils_string_in_list (const char *str, const char **valid_strings)
 {
 	int i;
 
@@ -427,25 +534,12 @@
 }
 
 gboolean
-nm_utils_string_list_contains (GSList *list, const char *string)
-{
-	GSList *iter;
-
-	g_return_val_if_fail (string != NULL, FALSE);
-
-	for (iter = list; iter; iter = g_slist_next (iter))
-		if (!strcmp (iter->data, string))
-			return TRUE;
-	return FALSE;
-}
-
-gboolean
-nm_utils_string_slist_validate (GSList *list, const char **valid_values)
+_nm_utils_string_slist_validate (GSList *list, const char **valid_values)
 {
 	GSList *iter;
 
 	for (iter = list; iter; iter = iter->next) {
-		if (!nm_utils_string_in_list ((char *) iter->data, valid_values))
+		if (!_nm_utils_string_in_list ((char *) iter->data, valid_values))
 			return FALSE;
 	}
 

Modified: trunk/libnm-util/nm-utils.h
==============================================================================
--- trunk/libnm-util/nm-utils.h	(original)
+++ trunk/libnm-util/nm-utils.h	Thu Nov 20 20:17:01 2008
@@ -1,5 +1,4 @@
 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */
-
 /* NetworkManager -- Network link manager
  *
  * Ray Strode <rstrode redhat com>
@@ -154,15 +153,6 @@
 void        nm_utils_slist_free       (GSList *list,
 							    GDestroyNotify elem_destroy_fn);
 
-gboolean    nm_utils_string_in_list   (const char *str,
-							    const char **valid_strings);
-
-gboolean    nm_utils_string_list_contains  (GSList *list, 
-								    const char *string);
-
-gboolean    nm_utils_string_slist_validate (GSList *list,
-								    const char **valid_values);
-
 void        nm_utils_register_value_transformations (void);
 
 typedef enum {