libnm-util/nm-setting.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */
   2
   3 /*
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17  * Boston, MA 02110-1301 USA.
  18  *
  19  * Copyright 2007 - 2011 Red Hat, Inc.
  20  * Copyright 2007 - 2008 Novell, Inc.
  21  */
  22
  23 #ifndef NM_SETTING_H
  24 #define NM_SETTING_H
  25
  26 #include <glib.h>
  27 #include <glib-object.h>
  28
  29 #include <nm-version.h>
  30
  31 G_BEGIN_DECLS
  32
  33 #define NM_TYPE_SETTING            (nm_setting_get_type ())
  34 #define NM_SETTING(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SETTING, NMSetting))
  35 #define NM_SETTING_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SETTING, NMSettingClass))
  36 #define NM_IS_SETTING(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_SETTING))
  37 #define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SETTING))
  38 #define NM_SETTING_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SETTING, NMSettingClass))
  39
  40 /**
  41  * NMSettingError:
  42  * @NM_SETTING_ERROR_UNKNOWN: unknown or unclassified error
  43  * @NM_SETTING_ERROR_PROPERTY_NOT_FOUND: a property required by the operation
  44  *   was not found; for example, an attempt to update an invalid secret
  45  * @NM_SETTING_ERROR_PROPERTY_NOT_SECRET: an operation which requires a secret
  46  *   was attempted on a non-secret property
  47  * @NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH: the operation requires a property
  48  *   of a specific type, or the value couldn't be transformed to the same type
  49  *   as the property being acted upon
  50  *
  51  * Describes errors that may result from operations involving a #NMSetting.
  52  *
  53  **/
  54 typedef enum
  55 {
  56         NM_SETTING_ERROR_UNKNOWN = 0,           /*< nick=UnknownError >*/
  57         NM_SETTING_ERROR_PROPERTY_NOT_FOUND,    /*< nick=PropertyNotFound >*/
  58         NM_SETTING_ERROR_PROPERTY_NOT_SECRET,   /*< nick=PropertyNotSecret >*/
  59         NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH /*< nick=PropertyTypeMismatch >*/
  60 } NMSettingError;
  61
  62 #define NM_SETTING_ERROR nm_setting_error_quark ()
  63 GQuark nm_setting_error_quark (void);
  64
  65
  66 /* DEPRECATED AND UNUSED */
  67 #define NM_SETTING_PARAM_SERIALIZE    (1 << (0 + G_PARAM_USER_SHIFT))
  68
  69 /* The property of the #NMSetting is required for the setting to be valid */
  70 #define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))
  71
  72 /* The property of the #NMSetting is a secret */
  73 #define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))
  74
  75 /* The property of the #NMSetting should be ignored during comparisons that
  76  * use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
  77  */
  78 #define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
  79
  80 /* Note: all non-glib GParamFlags bits are reserved by NetworkManager */
  81
  82
  83 #define NM_SETTING_NAME "name"
  84
  85 /**
  86  * NMSettingSecretFlags:
  87  * @NM_SETTING_SECRET_FLAG_NONE: the system is responsible for providing and
  88  * storing this secret (default)
  89  * @NM_SETTING_SECRET_FLAG_AGENT_OWNED: a user secret agent is responsible
  90  * for providing and storing this secret; when it is required agents will be
  91  * asked to retrieve it
  92  * @NM_SETTING_SECRET_FLAG_NOT_SAVED: this secret should not be saved, but
  93  * should be requested from the user each time it is needed
  94  * @NM_SETTING_SECRET_FLAG_NOT_REQUIRED: in situations where it cannot be
  95  * automatically determined that the secret is required (some VPNs and PPP
  96  * providers dont require all secrets) this flag indicates that the specific
  97  * secret is not required
  98  *
  99  * These flags indicate specific behavior related to handling of a secret.  Each
 100  * secret has a corresponding set of these flags which indicate how the secret
 101  * is to be stored and/or requested when it is needed.
 102  *
 103  **/
 104 typedef enum {
 105         NM_SETTING_SECRET_FLAG_NONE         = 0x00000000,
 106         NM_SETTING_SECRET_FLAG_AGENT_OWNED  = 0x00000001,
 107         NM_SETTING_SECRET_FLAG_NOT_SAVED    = 0x00000002,
 108         NM_SETTING_SECRET_FLAG_NOT_REQUIRED = 0x00000004
 109
 110         /* NOTE: if adding flags, update nm-setting-private.h as well */
 111 } NMSettingSecretFlags;
 112
 113 /**
 114  * NMSettingCompareFlags:
 115  * @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
 116  * @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
 117  *   type, security settings, etc.  Does not match, for example, connection ID
 118  *   or UUID.
 119  * @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
 120  * @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore all secrets
 121  * @NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS: ignore secrets for which
 122  * the secret's flags indicate the secret is owned by a user secret agent
 123  * (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_AGENT_OWNED)
 124  * @NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS: ignore secrets for which
 125  * the secret's flags indicate the secret should not be saved to persistent
 126  * storage (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_NOT_SAVED)
 127  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT: if this flag is set,
 128  * nm_setting_diff() and nm_connection_diff() will also include properties that
 129  * are set to their default value. See also @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT.
 130  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT: if this flag is set,
 131  * nm_setting_diff() and nm_connection_diff() will not include properties that
 132  * are set to their default value. This is the opposite of
 133  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT. If both flags are set together,
 134  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT wins. If both flags are unset,
 135  * this means to exclude default properties if there is a setting to compare,
 136  * but include all properties, if the setting 'b' is missing. This is the legacy
 137  * behaviour of libnm-util, where nm_setting_diff() behaved differently depending
 138  * on whether the setting 'b' was available. If @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT
 139  * is set, nm_setting_diff() will also set the flags @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT
 140  * and @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT, if the values are default values.
 141  *
 142  * These flags modify the comparison behavior when comparing two settings or
 143  * two connections.
 144  *
 145  **/
 146 typedef enum {
 147         NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
 148         NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
 149         NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
 150         NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004,
 151         NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS = 0x00000008,
 152         NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS = 0x00000010,
 153         NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT = 0x00000020,
 154         NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT = 0x00000040,
 155
 156         /* 0x80000000 is used for a private flag */
 157 } NMSettingCompareFlags;
 158
 159
 160 /**
 161  * NMSetting:
 162  *
 163  * The NMSetting struct contains only private data.
 164  * It should only be accessed through the functions described below.
 165  */
 166 typedef struct {
 167         GObject parent;
 168 } NMSetting;
 169
 170
 171 /**
 172  * NMSettingClearSecretsWithFlagsFn:
 173  * @setting: The setting for which secrets are being iterated
 174  * @secret: The secret's name
 175  * @flags: The secret's flags, eg %NM_SETTING_SECRET_FLAG_AGENT_OWNED
 176  * @user_data: User data passed to nm_connection_clear_secrets_with_flags()
 177  *
 178  * Returns: %TRUE to clear the secret, %FALSE to not clear the secret
 179  */
 180 typedef gboolean (*NMSettingClearSecretsWithFlagsFn) (NMSetting *setting,
 181                                                       const char *secret,
 182                                                       NMSettingSecretFlags flags,
 183                                                       gpointer user_data);
 184
 185 typedef struct {
 186         GObjectClass parent;
 187
 188         /* Virtual functions */
 189         gint        (*verify)            (NMSetting  *setting,
 190                                           GSList     *all_settings,
 191                                           GError     **error);
 192
 193         GPtrArray  *(*need_secrets)      (NMSetting  *setting);
 194
 195         int         (*update_one_secret) (NMSetting  *setting,
 196                                           const char *key,
 197                                           GValue     *value,
 198                                           GError    **error);
 199
 200         gboolean    (*get_secret_flags)  (NMSetting  *setting,
 201                                           const char *secret_name,
 202                                           gboolean verify_secret,
 203                                           NMSettingSecretFlags *out_flags,
 204                                           GError **error);
 205
 206         gboolean    (*set_secret_flags)  (NMSetting  *setting,
 207                                           const char *secret_name,
 208                                           gboolean verify_secret,
 209                                           NMSettingSecretFlags flags,
 210                                           GError **error);
 211
 212         /* Returns TRUE if the given property contains the same value in both settings */
 213         gboolean    (*compare_property)  (NMSetting *setting,
 214                                           NMSetting *other,
 215                                           const GParamSpec *prop_spec,
 216                                           NMSettingCompareFlags flags);
 217
 218         gboolean    (*clear_secrets_with_flags) (NMSetting *setting,
 219                                                  GParamSpec *pspec,
 220                                                  NMSettingClearSecretsWithFlagsFn func,
 221                                                  gpointer user_data);
 222
 223         const char *(*get_virtual_iface_name) (NMSetting *setting);
 224
 225         /* Padding for future expansion */
 226         void (*_reserved1) (void);
 227 } NMSettingClass;
 228
 229 /**
 230  * NMSettingValueIterFn:
 231  * @setting: The setting for which properties are being iterated, given to
 232  * nm_setting_enumerate_values()
 233  * @key: The value/property name
 234  * @value: The property's value
 235  * @flags: The property's flags, like %NM_SETTING_PARAM_SECRET
 236  * @user_data: User data passed to nm_setting_enumerate_values()
 237  */
 238 typedef void (*NMSettingValueIterFn) (NMSetting *setting,
 239                                       const char *key,
 240                                       const GValue *value,
 241                                       GParamFlags flags,
 242                                       gpointer user_data);
 243
 244
 245 GType nm_setting_get_type (void);
 246
 247 /**
 248  * NMSettingHashFlags:
 249  * @NM_SETTING_HASH_FLAG_ALL: hash all properties (including secrets)
 250  * @NM_SETTING_HASH_FLAG_NO_SECRETS: do not include secrets
 251  * @NM_SETTING_HASH_FLAG_ONLY_SECRETS: only hash secrets
 252  *
 253  * These flags determine which properties are added to the resulting hash
 254  * when calling nm_setting_to_hash().
 255  *
 256  **/
 257 typedef enum {
 258         NM_SETTING_HASH_FLAG_ALL = 0x00000000,
 259         NM_SETTING_HASH_FLAG_NO_SECRETS = 0x00000001,
 260         NM_SETTING_HASH_FLAG_ONLY_SECRETS = 0x00000002,
 261 } NMSettingHashFlags;
 262
 263 GHashTable *nm_setting_to_hash       (NMSetting *setting,
 264                                       NMSettingHashFlags flags);
 265
 266 NMSetting  *nm_setting_new_from_hash (GType setting_type,
 267                                       GHashTable *hash);
 268
 269 NMSetting *nm_setting_duplicate      (NMSetting *setting);
 270
 271 const char *nm_setting_get_name      (NMSetting *setting);
 272
 273 gboolean    nm_setting_verify        (NMSetting *setting,
 274                                       GSList    *all_settings,
 275                                       GError    **error);
 276
 277 gboolean    nm_setting_compare       (NMSetting *a,
 278                                       NMSetting *b,
 279                                       NMSettingCompareFlags flags);
 280
 281 /**
 282  * NMSettingDiffResult:
 283  * @NM_SETTING_DIFF_RESULT_UNKNOWN: unknown result
 284  * @NM_SETTING_DIFF_RESULT_IN_A: the property is present in setting A
 285  * @NM_SETTING_DIFF_RESULT_IN_B: the property is present in setting B
 286  * @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT: the property is present in
 287  * setting A but is set to the default value. This flag is only set,
 288  * if you specify @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT.
 289  * @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT: analog to @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT.
 290  *
 291  * These values indicate the result of a setting difference operation.
 292  **/
 293 typedef enum {
 294         NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
 295         NM_SETTING_DIFF_RESULT_IN_A =    0x00000001,
 296         NM_SETTING_DIFF_RESULT_IN_B =    0x00000002,
 297         NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
 298         NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000004,
 299 } NMSettingDiffResult;
 300
 301 gboolean    nm_setting_diff          (NMSetting *a,
 302                                       NMSetting *b,
 303                                       NMSettingCompareFlags flags,
 304                                       gboolean invert_results,
 305                                       GHashTable **results);
 306
 307 void        nm_setting_enumerate_values (NMSetting *setting,
 308                                          NMSettingValueIterFn func,
 309                                          gpointer user_data);
 310
 311 char       *nm_setting_to_string      (NMSetting *setting);
 312
 313 /* Secrets */
 314 void        nm_setting_clear_secrets  (NMSetting *setting);
 315
 316 void        nm_setting_clear_secrets_with_flags (NMSetting *setting,
 317                                                  NMSettingClearSecretsWithFlagsFn func,
 318                                                  gpointer user_data);
 319
 320 GPtrArray  *nm_setting_need_secrets   (NMSetting *setting);
 321 gboolean    nm_setting_update_secrets (NMSetting *setting,
 322                                        GHashTable *secrets,
 323                                        GError **error);
 324
 325 gboolean    nm_setting_get_secret_flags (NMSetting *setting,
 326                                          const char *secret_name,
 327                                          NMSettingSecretFlags *out_flags,
 328                                          GError **error);
 329
 330 gboolean    nm_setting_set_secret_flags (NMSetting *setting,
 331                                          const char *secret_name,
 332                                          NMSettingSecretFlags flags,
 333                                          GError **error);
 334
 335 const char *nm_setting_get_virtual_iface_name (NMSetting *setting);
 336
 337 G_END_DECLS
 338
 339 #endif /* NM_SETTING_H */