libnm-core/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 #if !defined (__NETWORKMANAGER_H_INSIDE__) && !defined (NETWORKMANAGER_COMPILATION)
  27 #error "Only <NetworkManager.h> can be included directly."
  28 #endif
  29
  30 #include <nm-core-types.h>
  31
  32 G_BEGIN_DECLS
  33
  34 #define NM_TYPE_SETTING            (nm_setting_get_type ())
  35 #define NM_SETTING(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SETTING, NMSetting))
  36 #define NM_SETTING_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SETTING, NMSettingClass))
  37 #define NM_IS_SETTING(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_SETTING))
  38 #define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SETTING))
  39 #define NM_SETTING_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SETTING, NMSettingClass))
  40
  41 /* The property of the #NMSetting is required for the setting to be valid */
  42 #define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))
  43
  44 /* The property of the #NMSetting is a secret */
  45 #define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))
  46
  47 /* The property of the #NMSetting should be ignored during comparisons that
  48  * use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
  49  */
  50 #define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
  51
  52 /* Note: all non-glib GParamFlags bits are reserved by NetworkManager */
  53
  54
  55 #define NM_SETTING_NAME "name"
  56
  57 /**
  58  * NMSettingSecretFlags:
  59  * @NM_SETTING_SECRET_FLAG_NONE: the system is responsible for providing and
  60  * storing this secret (default)
  61  * @NM_SETTING_SECRET_FLAG_AGENT_OWNED: a user secret agent is responsible
  62  * for providing and storing this secret; when it is required agents will be
  63  * asked to retrieve it
  64  * @NM_SETTING_SECRET_FLAG_NOT_SAVED: this secret should not be saved, but
  65  * should be requested from the user each time it is needed
  66  * @NM_SETTING_SECRET_FLAG_NOT_REQUIRED: in situations where it cannot be
  67  * automatically determined that the secret is required (some VPNs and PPP
  68  * providers dont require all secrets) this flag indicates that the specific
  69  * secret is not required
  70  *
  71  * These flags indicate specific behavior related to handling of a secret.  Each
  72  * secret has a corresponding set of these flags which indicate how the secret
  73  * is to be stored and/or requested when it is needed.
  74  *
  75  **/
  76 typedef enum { /*< flags >*/
  77         NM_SETTING_SECRET_FLAG_NONE         = 0x00000000,
  78         NM_SETTING_SECRET_FLAG_AGENT_OWNED  = 0x00000001,
  79         NM_SETTING_SECRET_FLAG_NOT_SAVED    = 0x00000002,
  80         NM_SETTING_SECRET_FLAG_NOT_REQUIRED = 0x00000004
  81
  82         /* NOTE: if adding flags, update nm-core-internal.h as well */
  83 } NMSettingSecretFlags;
  84
  85 /**
  86  * NMSettingCompareFlags:
  87  * @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
  88  * @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
  89  *   type, security settings, etc.  Does not match, for example, connection ID
  90  *   or UUID.
  91  * @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
  92  * @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore all secrets
  93  * @NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS: ignore secrets for which
  94  *   the secret's flags indicate the secret is owned by a user secret agent
  95  *   (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_AGENT_OWNED)
  96  * @NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS: ignore secrets for which
  97  *   the secret's flags indicate the secret should not be saved to persistent
  98  *   storage (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_NOT_SAVED)
  99  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT: if this flag is set,
 100  *   nm_setting_diff() and nm_connection_diff() will also include properties that
 101  *   are set to their default value. See also @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT.
 102  * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT: if this flag is set,
 103  *   nm_setting_diff() and nm_connection_diff() will not include properties that
 104  *   are set to their default value. This is the opposite of
 105  *   @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT. If both flags are set together,
 106  *   @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT wins. If both flags are unset,
 107  *   this means to exclude default properties if there is a setting to compare,
 108  *   but include all properties, if the setting 'b' is missing. This is the legacy
 109  *   behaviour of libnm-util, where nm_setting_diff() behaved differently depending
 110  *   on whether the setting 'b' was available. If @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT
 111  *   is set, nm_setting_diff() will also set the flags @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT
 112  *   and @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT, if the values are default values.
 113  * @NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP: ignore the connection's timestamp
 114  *
 115  * These flags modify the comparison behavior when comparing two settings or
 116  * two connections.
 117  *
 118  **/
 119 typedef enum {
 120         NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
 121         NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
 122         NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
 123         NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004,
 124         NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS = 0x00000008,
 125         NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS = 0x00000010,
 126         NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT = 0x00000020,
 127         NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT = 0x00000040,
 128         NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP = 0x00000080,
 129
 130         /* Higher flags like 0x80000000 and 0x40000000 are used internally as private flags */
 131 } NMSettingCompareFlags;
 132
 133
 134 /**
 135  * NMSettingMacRandomization:
 136  * @NM_SETTING_MAC_RANDOMIZATION_DEFAULT: the default value, which unless
 137  * overridden by user-controlled defaults configuration, is "never".
 138  * @NM_SETTING_MAC_RANDOMIZATION_NEVER: the device's MAC address is always used.
 139  * @NM_SETTING_MAC_RANDOMIZATION_ALWAYS: a random MAC address is used.
 140  *
 141  * Controls if and how the MAC address of a device is randomzied.
 142  **/
 143 typedef enum {
 144         NM_SETTING_MAC_RANDOMIZATION_DEFAULT = 0,
 145         NM_SETTING_MAC_RANDOMIZATION_NEVER,
 146         NM_SETTING_MAC_RANDOMIZATION_ALWAYS,
 147 } NMSettingMacRandomization;
 148
 149
 150 /**
 151  * NMSetting:
 152  *
 153  * The NMSetting struct contains only private data.
 154  * It should only be accessed through the functions described below.
 155  */
 156 struct _NMSetting {
 157         GObject parent;
 158 };
 159
 160
 161 /**
 162  * NMSettingClearSecretsWithFlagsFn:
 163  * @setting: The setting for which secrets are being iterated
 164  * @secret: The secret's name
 165  * @flags: The secret's flags, eg %NM_SETTING_SECRET_FLAG_AGENT_OWNED
 166  * @user_data: User data passed to nm_connection_clear_secrets_with_flags()
 167  *
 168  * Returns: %TRUE to clear the secret, %FALSE to not clear the secret
 169  */
 170 typedef gboolean (*NMSettingClearSecretsWithFlagsFn) (NMSetting *setting,
 171                                                       const char *secret,
 172                                                       NMSettingSecretFlags flags,
 173                                                       gpointer user_data);
 174
 175 typedef struct {
 176         GObjectClass parent;
 177
 178         /* Virtual functions */
 179         gint        (*verify)            (NMSetting     *setting,
 180                                           NMConnection  *connection,
 181                                           GError       **error);
 182
 183         gboolean    (*verify_secrets)    (NMSetting     *setting,
 184                                           NMConnection  *connection,
 185                                           GError       **error);
 186
 187         GPtrArray  *(*need_secrets)      (NMSetting  *setting);
 188
 189         int         (*update_one_secret) (NMSetting  *setting,
 190                                           const char *key,
 191                                           GVariant   *value,
 192                                           GError    **error);
 193
 194         gboolean    (*get_secret_flags)  (NMSetting  *setting,
 195                                           const char *secret_name,
 196                                           gboolean verify_secret,
 197                                           NMSettingSecretFlags *out_flags,
 198                                           GError **error);
 199
 200         gboolean    (*set_secret_flags)  (NMSetting  *setting,
 201                                           const char *secret_name,
 202                                           gboolean verify_secret,
 203                                           NMSettingSecretFlags flags,
 204                                           GError **error);
 205
 206         gboolean    (*clear_secrets_with_flags) (NMSetting *setting,
 207                                                  GParamSpec *pspec,
 208                                                  NMSettingClearSecretsWithFlagsFn func,
 209                                                  gpointer user_data);
 210
 211         /* Returns TRUE if the given property contains the same value in both settings */
 212         gboolean    (*compare_property)  (NMSetting *setting,
 213                                           NMSetting *other,
 214                                           const GParamSpec *prop_spec,
 215                                           NMSettingCompareFlags flags);
 216
 217         /*< private >*/
 218         gpointer padding[7];
 219 } NMSettingClass;
 220
 221 /**
 222  * NMSettingValueIterFn:
 223  * @setting: The setting for which properties are being iterated, given to
 224  * nm_setting_enumerate_values()
 225  * @key: The value/property name
 226  * @value: The property's value
 227  * @flags: The property's flags, like %NM_SETTING_PARAM_SECRET
 228  * @user_data: User data passed to nm_setting_enumerate_values()
 229  */
 230 typedef void (*NMSettingValueIterFn) (NMSetting *setting,
 231                                       const char *key,
 232                                       const GValue *value,
 233                                       GParamFlags flags,
 234                                       gpointer user_data);
 235
 236
 237 GType nm_setting_get_type (void);
 238
 239 GType nm_setting_lookup_type (const char *name);
 240
 241 NMSetting *nm_setting_duplicate      (NMSetting *setting);
 242
 243 const char *nm_setting_get_name      (NMSetting *setting);
 244
 245 gboolean    nm_setting_verify        (NMSetting     *setting,
 246                                       NMConnection  *connection,
 247                                       GError       **error);
 248
 249 NM_AVAILABLE_IN_1_2
 250 gboolean    nm_setting_verify_secrets (NMSetting     *setting,
 251                                        NMConnection  *connection,
 252                                        GError       **error);
 253
 254 gboolean    nm_setting_compare       (NMSetting *a,
 255                                       NMSetting *b,
 256                                       NMSettingCompareFlags flags);
 257
 258 /**
 259  * NMSettingDiffResult:
 260  * @NM_SETTING_DIFF_RESULT_UNKNOWN: unknown result
 261  * @NM_SETTING_DIFF_RESULT_IN_A: the property is present in setting A
 262  * @NM_SETTING_DIFF_RESULT_IN_B: the property is present in setting B
 263  * @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT: the property is present in
 264  * setting A but is set to the default value. This flag is only set,
 265  * if you specify @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT.
 266  * @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT: analog to @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT.
 267  *
 268  * These values indicate the result of a setting difference operation.
 269  **/
 270 typedef enum {
 271         NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
 272         NM_SETTING_DIFF_RESULT_IN_A =    0x00000001,
 273         NM_SETTING_DIFF_RESULT_IN_B =    0x00000002,
 274         NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
 275         NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000004,
 276 } NMSettingDiffResult;
 277
 278 gboolean    nm_setting_diff          (NMSetting *a,
 279                                       NMSetting *b,
 280                                       NMSettingCompareFlags flags,
 281                                       gboolean invert_results,
 282                                       GHashTable **results);
 283
 284 void        nm_setting_enumerate_values (NMSetting *setting,
 285                                          NMSettingValueIterFn func,
 286                                          gpointer user_data);
 287
 288 char       *nm_setting_to_string      (NMSetting *setting);
 289
 290 /* Secrets */
 291 gboolean    nm_setting_get_secret_flags (NMSetting *setting,
 292                                          const char *secret_name,
 293                                          NMSettingSecretFlags *out_flags,
 294                                          GError **error);
 295
 296 gboolean    nm_setting_set_secret_flags (NMSetting *setting,
 297                                          const char *secret_name,
 298                                          NMSettingSecretFlags flags,
 299                                          GError **error);
 300
 301 /* Properties */
 302 const GVariantType *nm_setting_get_dbus_property_type (NMSetting *setting,
 303                                                        const char *property_name);
 304
 305 G_END_DECLS
 306
 307 #endif /* __NM_SETTING_H__ */