From 3bc8b0ca576c3dfe45a853be94862b3da65a74bb Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Thu, 20 Nov 2008 20:17:01 +0000 Subject: [PATCH] 2008-11-20 Dan Williams * 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 git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@4319 4912f4e0-d625-0410-9fb7-b9a5a253dbdc --- ChangeLog | 21 ++++ libnm-util/Makefile.am | 1 + libnm-util/libnm-util.ver | 3 - libnm-util/nm-setting-8021x.c | 11 +- libnm-util/nm-setting-wired.c | 5 +- libnm-util/nm-setting-wireless-security.c | 13 ++- libnm-util/nm-setting-wireless.c | 5 +- libnm-util/nm-utils-private.h | 35 ++++++ libnm-util/nm-utils.c | 130 +++++++++++++++++++--- libnm-util/nm-utils.h | 10 -- 10 files changed, 188 insertions(+), 46 deletions(-) create mode 100644 libnm-util/nm-utils-private.h diff --git a/ChangeLog b/ChangeLog index c72e57510..d795ce8f5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,24 @@ +2008-11-20 Dan Williams + + * 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 + 2008-11-20 Dan Williams * libnm-util/libnm-util.ver diff --git a/libnm-util/Makefile.am b/libnm-util/Makefile.am index 77acdf819..ce72c1627 100644 --- a/libnm-util/Makefile.am +++ b/libnm-util/Makefile.am @@ -47,6 +47,7 @@ libnm_util_la_SOURCES= \ 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) diff --git a/libnm-util/libnm-util.ver b/libnm-util/libnm-util.ver index 836dc045a..00c50120d 100644 --- a/libnm-util/libnm-util.ver +++ b/libnm-util/libnm-util.ver @@ -259,9 +259,6 @@ global: 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; diff --git a/libnm-util/nm-setting-8021x.c b/libnm-util/nm-setting-8021x.c index 7f3ce6cae..04d29057a 100644 --- a/libnm-util/nm-setting-8021x.c +++ b/libnm-util/nm-setting-8021x.c @@ -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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) } } - 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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, diff --git a/libnm-util/nm-setting-wired.c b/libnm-util/nm-setting-wired.c index 2e0e022cf..2912b1531 100644 --- a/libnm-util/nm-setting-wired.c +++ b/libnm-util/nm-setting-wired.c @@ -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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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, diff --git a/libnm-util/nm-setting-wireless-security.c b/libnm-util/nm-setting-wireless-security.c index 4187433f9..9f1604855 100644 --- a/libnm-util/nm-setting-wireless-security.c +++ b/libnm-util/nm-setting-wireless-security.c @@ -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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) } } - 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, diff --git a/libnm-util/nm-setting-wireless.c b/libnm-util/nm-setting-wireless.c index b1776b482..b3b178b58 100644 --- a/libnm-util/nm-setting-wireless.c +++ b/libnm-util/nm-setting-wireless.c @@ -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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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 @@ verify (NMSetting *setting, GSList *all_settings, GError **error) 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, diff --git a/libnm-util/nm-utils-private.h b/libnm-util/nm-utils-private.h new file mode 100644 index 000000000..aa01d74fe --- /dev/null +++ b/libnm-util/nm-utils-private.h @@ -0,0 +1,35 @@ +/* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */ +/* NetworkManager -- Network link manager + * + * Ray Strode + * Dan Williams + * Tambet Ingo + * + * 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 diff --git a/libnm-util/nm-utils.c b/libnm-util/nm-utils.c index 65d228cc8..2c9f4446a 100644 --- a/libnm-util/nm-utils.c +++ b/libnm-util/nm-utils.c @@ -38,6 +38,7 @@ #include #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 @@ string_to_utf8 (const char *str, gsize len) 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 @@ nm_utils_deinit (void) /* 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 @@ nm_utils_ssid_to_utf8 (const char *ssid, guint32 len) } /* 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 @@ nm_utils_is_empty_ssid (const guint8 * ssid, int len) 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 @@ nm_utils_escape_ssid (const guint8 * ssid, guint32 len) 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 @@ value_dup (gpointer key, gpointer val, gpointer user_data) 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 @@ nm_utils_gvalue_hash_dup (GHashTable *hash) 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 @@ nm_utils_slist_free (GSList *list, GDestroyNotify elem_destroy_fn) } 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 @@ nm_utils_string_in_list (const char *str, const char **valid_strings) } 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; } diff --git a/libnm-util/nm-utils.h b/libnm-util/nm-utils.h index 90702647f..2716fe6f0 100644 --- a/libnm-util/nm-utils.h +++ b/libnm-util/nm-utils.h @@ -1,5 +1,4 @@ /* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */ - /* NetworkManager -- Network link manager * * Ray Strode @@ -154,15 +153,6 @@ GHashTable *nm_utils_gvalue_hash_dup (GHashTable *hash); 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 {