nm-setting.h 14 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
/* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */

/*
 * 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.
 *
19 20
 * Copyright 2007 - 2011 Red Hat, Inc.
 * Copyright 2007 - 2008 Novell, Inc.
21
 */
22

23 24 25
#ifndef NM_SETTING_H
#define NM_SETTING_H

26
#include <glib.h>
27
#include <glib-object.h>
28

29
#include "nm-version.h"
30

31 32
G_BEGIN_DECLS

33 34 35 36
#define NM_TYPE_SETTING            (nm_setting_get_type ())
#define NM_SETTING(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SETTING, NMSetting))
#define NM_SETTING_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SETTING, NMSettingClass))
#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

Dan Williams's avatar
Dan Williams committed
40 41 42 43 44 45 46 47 48 49 50 51 52 53
/**
 * NMSettingError:
 * @NM_SETTING_ERROR_UNKNOWN: unknown or unclassified error
 * @NM_SETTING_ERROR_PROPERTY_NOT_FOUND: a property required by the operation
 *   was not found; for example, an attempt to update an invalid secret
 * @NM_SETTING_ERROR_PROPERTY_NOT_SECRET: an operation which requires a secret
 *   was attempted on a non-secret property
 * @NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH: the operation requires a property
 *   of a specific type, or the value couldn't be transformed to the same type
 *   as the property being acted upon
 *
 * Describes errors that may result from operations involving a #NMSetting.
 *
 **/
54 55
typedef enum
{
56 57 58 59
	NM_SETTING_ERROR_UNKNOWN = 0,           /*< nick=UnknownError >*/
	NM_SETTING_ERROR_PROPERTY_NOT_FOUND,    /*< nick=PropertyNotFound >*/
	NM_SETTING_ERROR_PROPERTY_NOT_SECRET,   /*< nick=PropertyNotSecret >*/
	NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH /*< nick=PropertyTypeMismatch >*/
60 61 62 63 64
} NMSettingError;

#define NM_SETTING_ERROR nm_setting_error_quark ()
GQuark nm_setting_error_quark (void);

65
/* DEPRECATED AND UNUSED */
66
#define NM_SETTING_PARAM_SERIALIZE    (1 << (0 + G_PARAM_USER_SHIFT))
Dan Williams's avatar
Dan Williams committed
67 68

/* The property of the #NMSetting is required for the setting to be valid */
69
#define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))
Dan Williams's avatar
Dan Williams committed
70 71

/* The property of the #NMSetting is a secret */
72
#define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))
Dan Williams's avatar
Dan Williams committed
73 74 75 76

/* The property of the #NMSetting should be ignored during comparisons that
 * use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
 */
77
#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
78

79 80
/* Note: all non-glib GParamFlags bits are reserved by NetworkManager */

81
#define NM_SETTING_NAME "name"
82

83 84
/**
 * NMSettingSecretFlags:
85 86
 * @NM_SETTING_SECRET_FLAG_NONE: the system is responsible for providing and
 * storing this secret (default)
87 88 89 90 91
 * @NM_SETTING_SECRET_FLAG_AGENT_OWNED: a user secret agent is responsible
 * for providing and storing this secret; when it is required agents will be
 * asked to retrieve it
 * @NM_SETTING_SECRET_FLAG_NOT_SAVED: this secret should not be saved, but
 * should be requested from the user each time it is needed
92 93 94 95
 * @NM_SETTING_SECRET_FLAG_NOT_REQUIRED: in situations where it cannot be
 * automatically determined that the secret is required (some VPNs and PPP
 * providers dont require all secrets) this flag indicates that the specific
 * secret is not required
96 97 98 99 100 101 102
 *
 * These flags indicate specific behavior related to handling of a secret.  Each
 * secret has a corresponding set of these flags which indicate how the secret
 * is to be stored and/or requested when it is needed.
 *
 **/
typedef enum {
103
	NM_SETTING_SECRET_FLAG_NONE         = 0x00000000,
104
	NM_SETTING_SECRET_FLAG_AGENT_OWNED  = 0x00000001,
105 106
	NM_SETTING_SECRET_FLAG_NOT_SAVED    = 0x00000002,
	NM_SETTING_SECRET_FLAG_NOT_REQUIRED = 0x00000004
107 108 109 110

	/* NOTE: if adding flags, update nm-setting-private.h as well */
} NMSettingSecretFlags;

111 112 113 114 115 116 117 118 119 120 121 122 123 124
/**
 * NMSettingCompareFlags:
 * @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
 * @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
 *   type, security settings, etc.  Does not match, for example, connection ID
 *   or UUID.
 * @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
 * @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore all secrets
 * @NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS: ignore secrets for which
 * the secret's flags indicate the secret is owned by a user secret agent
 * (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_AGENT_OWNED)
 * @NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS: ignore secrets for which
 * the secret's flags indicate the secret should not be saved to persistent
 * storage (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_NOT_SAVED)
125 126 127 128 129 130 131 132 133 134 135 136 137 138
 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT: if this flag is set,
 * nm_setting_diff() and nm_connection_diff() will also include properties that
 * are set to their default value. See also @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT.
 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT: if this flag is set,
 * nm_setting_diff() and nm_connection_diff() will not include properties that
 * are set to their default value. This is the opposite of
 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT. If both flags are set together,
 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT wins. If both flags are unset,
 * this means to exclude default properties if there is a setting to compare,
 * but include all properties, if the setting 'b' is missing. This is the legacy
 * behaviour of libnm-util, where nm_setting_diff() behaved differently depending
 * on whether the setting 'b' was available. If @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT
 * is set, nm_setting_diff() will also set the flags @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT
 * and @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT, if the values are default values.
139 140 141 142 143 144 145 146 147 148 149
 *
 * These flags modify the comparison behavior when comparing two settings or
 * two connections.
 *
 **/
typedef enum {
	NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
	NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
	NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
	NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004,
	NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS = 0x00000008,
150 151 152
	NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS = 0x00000010,
	NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT = 0x00000020,
	NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT = 0x00000040,
153 154

	/* 0x80000000 is used for a private flag */
155 156
} NMSettingCompareFlags;

Dan Williams's avatar
Dan Williams committed
157 158 159 160 161 162
/**
 * NMSetting:
 *
 * The NMSetting struct contains only private data.
 * It should only be accessed through the functions described below.
 */
163
typedef struct {
164 165
	GObject parent;
} NMSetting;
166

167 168 169 170 171 172 173 174 175 176 177 178 179 180
/**
 * NMSettingClearSecretsWithFlagsFn:
 * @setting: The setting for which secrets are being iterated
 * @secret: The secret's name
 * @flags: The secret's flags, eg %NM_SETTING_SECRET_FLAG_AGENT_OWNED
 * @user_data: User data passed to nm_connection_clear_secrets_with_flags()
 *
 * Returns: %TRUE to clear the secret, %FALSE to not clear the secret
 */
typedef gboolean (*NMSettingClearSecretsWithFlagsFn) (NMSetting *setting,
                                                      const char *secret,
                                                      NMSettingSecretFlags flags,
                                                      gpointer user_data);

181
typedef struct {
182
	GObjectClass parent;
183

184
	/* Virtual functions */
185
	gint        (*verify)            (NMSetting  *setting,
186 187
	                                  GSList     *all_settings,
	                                  GError     **error);
188

189 190
	GPtrArray  *(*need_secrets)      (NMSetting  *setting);

191
	int         (*update_one_secret) (NMSetting  *setting,
192
	                                  const char *key,
193 194
	                                  GValue     *value,
	                                  GError    **error);
195

196 197
	gboolean    (*get_secret_flags)  (NMSetting  *setting,
	                                  const char *secret_name,
198
	                                  gboolean verify_secret,
199 200 201 202 203
	                                  NMSettingSecretFlags *out_flags,
	                                  GError **error);

	gboolean    (*set_secret_flags)  (NMSetting  *setting,
	                                  const char *secret_name,
204
	                                  gboolean verify_secret,
205 206 207
	                                  NMSettingSecretFlags flags,
	                                  GError **error);

208 209 210 211 212 213
	/* Returns TRUE if the given property contains the same value in both settings */
	gboolean    (*compare_property)  (NMSetting *setting,
	                                  NMSetting *other,
	                                  const GParamSpec *prop_spec,
	                                  NMSettingCompareFlags flags);

214
	gboolean    (*clear_secrets_with_flags) (NMSetting *setting,
215 216 217 218
	                                         GParamSpec *pspec,
	                                         NMSettingClearSecretsWithFlagsFn func,
	                                         gpointer user_data);

219 220
	const char *(*get_virtual_iface_name) (NMSetting *setting);

221 222
	/* Padding for future expansion */
	void (*_reserved1) (void);
223
} NMSettingClass;
224

225 226 227 228 229 230 231 232 233
/**
 * NMSettingValueIterFn:
 * @setting: The setting for which properties are being iterated, given to
 * nm_setting_enumerate_values()
 * @key: The value/property name
 * @value: The property's value
 * @flags: The property's flags, like %NM_SETTING_PARAM_SECRET
 * @user_data: User data passed to nm_setting_enumerate_values()
 */
234
typedef void (*NMSettingValueIterFn) (NMSetting *setting,
235 236 237 238
                                      const char *key,
                                      const GValue *value,
                                      GParamFlags flags,
                                      gpointer user_data);
239

240
GType nm_setting_get_type (void);
241

242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
/**
 * NMSettingHashFlags:
 * @NM_SETTING_HASH_FLAG_ALL: hash all properties (including secrets)
 * @NM_SETTING_HASH_FLAG_NO_SECRETS: do not include secrets
 * @NM_SETTING_HASH_FLAG_ONLY_SECRETS: only hash secrets
 *
 * These flags determine which properties are added to the resulting hash
 * when calling nm_setting_to_hash().
 *
 **/
typedef enum {
	NM_SETTING_HASH_FLAG_ALL = 0x00000000,
	NM_SETTING_HASH_FLAG_NO_SECRETS = 0x00000001,
	NM_SETTING_HASH_FLAG_ONLY_SECRETS = 0x00000002,
} NMSettingHashFlags;

GHashTable *nm_setting_to_hash       (NMSetting *setting,
                                      NMSettingHashFlags flags);

261 262
NMSetting  *nm_setting_new_from_hash (GType setting_type,
                                      GHashTable *hash);
263

264 265
NMSetting *nm_setting_duplicate      (NMSetting *setting);

266
const char *nm_setting_get_name      (NMSetting *setting);
267

268
gboolean    nm_setting_verify        (NMSetting *setting,
269 270
                                      GSList    *all_settings,
                                      GError    **error);
271

Dan Williams's avatar
Dan Williams committed
272 273
gboolean    nm_setting_compare       (NMSetting *a,
                                      NMSetting *b,
274
                                      NMSettingCompareFlags flags);
275

276 277 278 279 280
/**
 * NMSettingDiffResult:
 * @NM_SETTING_DIFF_RESULT_UNKNOWN: unknown result
 * @NM_SETTING_DIFF_RESULT_IN_A: the property is present in setting A
 * @NM_SETTING_DIFF_RESULT_IN_B: the property is present in setting B
281 282 283 284
 * @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT: the property is present in
 * setting A but is set to the default value. This flag is only set,
 * if you specify @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT.
 * @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT: analog to @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT.
285 286 287 288 289 290 291
 *
 * These values indicate the result of a setting difference operation.
 **/
typedef enum {
	NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
	NM_SETTING_DIFF_RESULT_IN_A =    0x00000001,
	NM_SETTING_DIFF_RESULT_IN_B =    0x00000002,
292 293
	NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
	NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000004,
294 295 296 297 298 299 300 301
} NMSettingDiffResult;

gboolean    nm_setting_diff          (NMSetting *a,
                                      NMSetting *b,
                                      NMSettingCompareFlags flags,
                                      gboolean invert_results,
                                      GHashTable **results);

302 303 304
void        nm_setting_enumerate_values (NMSetting *setting,
                                         NMSettingValueIterFn func,
                                         gpointer user_data);
305

306
char       *nm_setting_to_string      (NMSetting *setting);
307

308 309
/* Secrets */
void        nm_setting_clear_secrets  (NMSetting *setting);
310 311 312 313 314

void        nm_setting_clear_secrets_with_flags (NMSetting *setting,
                                                 NMSettingClearSecretsWithFlagsFn func,
                                                 gpointer user_data);

315
GPtrArray  *nm_setting_need_secrets   (NMSetting *setting);
316 317 318
gboolean    nm_setting_update_secrets (NMSetting *setting,
                                       GHashTable *secrets,
                                       GError **error);
319

320 321 322 323 324 325 326 327 328 329
gboolean    nm_setting_get_secret_flags (NMSetting *setting,
                                         const char *secret_name,
                                         NMSettingSecretFlags *out_flags,
                                         GError **error);

gboolean    nm_setting_set_secret_flags (NMSetting *setting,
                                         const char *secret_name,
                                         NMSettingSecretFlags flags,
                                         GError **error);

330 331
const char *nm_setting_get_virtual_iface_name (NMSetting *setting);

332
G_END_DECLS
333

334
#endif /* NM_SETTING_H */