1/* SPDX-License-Identifier: LGPL-2.1-or-later */
2/*
3 * Copyright (C) 2007 - 2011 Red Hat, Inc.
4 * Copyright (C) 2007 - 2008 Novell, Inc.
5 */
6
7#ifndef __NM_SETTING_H__
8#define __NM_SETTING_H__
9
10#if !defined(__NETWORKMANAGER_H_INSIDE__) && !defined(NETWORKMANAGER_COMPILATION)
11#error "Only <NetworkManager.h> can be included directly."
12#endif
13
14#include "nm-core-types.h"
15
16G_BEGIN_DECLS
17
18#define NM_TYPE_SETTING (nm_setting_get_type())
19#define NM_SETTING(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), NM_TYPE_SETTING, NMSetting))
20#define NM_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), NM_TYPE_SETTING, NMSettingClass))
21#define NM_IS_SETTING(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), NM_TYPE_SETTING))
22#define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), NM_TYPE_SETTING))
23#define NM_SETTING_GET_CLASS(obj) \
24 (G_TYPE_INSTANCE_GET_CLASS((obj), NM_TYPE_SETTING, NMSettingClass))
25
26/* The property of the #NMSetting is required for the setting to be valid */
27#define NM_SETTING_PARAM_REQUIRED 0x200
28
29/* The property of the #NMSetting is a secret */
30#define NM_SETTING_PARAM_SECRET 0x400
31
32/* The property of the #NMSetting should be ignored during comparisons that
33 * use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
34 */
35#define NM_SETTING_PARAM_FUZZY_IGNORE 0x800
36
37/* Note: all non-glib GParamFlags bits are reserved by NetworkManager */
38
39#define NM_SETTING_NAME "name"
40
41/**
42 * NMSettingSecretFlags:
43 * @NM_SETTING_SECRET_FLAG_NONE: the system is responsible for providing and
44 * storing this secret (default)
45 * @NM_SETTING_SECRET_FLAG_AGENT_OWNED: a user secret agent is responsible
46 * for providing and storing this secret; when it is required agents will be
47 * asked to retrieve it
48 * @NM_SETTING_SECRET_FLAG_NOT_SAVED: this secret should not be saved, but
49 * should be requested from the user each time it is needed
50 * @NM_SETTING_SECRET_FLAG_NOT_REQUIRED: in situations where it cannot be
51 * automatically determined that the secret is required (some VPNs and PPP
52 * providers don't require all secrets) this flag indicates that the specific
53 * secret is not required
54 *
55 * These flags indicate specific behavior related to handling of a secret. Each
56 * secret has a corresponding set of these flags which indicate how the secret
57 * is to be stored and/or requested when it is needed.
58 *
59 **/
60typedef enum /*< flags >*/ {
61 NM_SETTING_SECRET_FLAG_NONE = 0x00000000,
62 NM_SETTING_SECRET_FLAG_AGENT_OWNED = 0x00000001,
63 NM_SETTING_SECRET_FLAG_NOT_SAVED = 0x00000002,
64 NM_SETTING_SECRET_FLAG_NOT_REQUIRED = 0x00000004
65
66 /* NOTE: if adding flags, update nm-core-internal.h as well */
67} NMSettingSecretFlags;
68
69/**
70 * NMSettingCompareFlags:
71 * @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
72 * @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
73 * type, security settings, etc. Does not match, for example, connection ID
74 * or UUID.
75 * @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
76 * @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore all secrets
77 * @NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS: ignore secrets for which
78 * the secret's flags indicate the secret is owned by a user secret agent
79 * (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_AGENT_OWNED)
80 * @NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS: ignore secrets for which
81 * the secret's flags indicate the secret should not be saved to persistent
82 * storage (ie, the secret's flag includes @NM_SETTING_SECRET_FLAG_NOT_SAVED)
83 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT: if this flag is set,
84 * nm_setting_diff() and nm_connection_diff() will also include properties that
85 * are set to their default value. See also @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT.
86 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT: if this flag is set,
87 * nm_setting_diff() and nm_connection_diff() will not include properties that
88 * are set to their default value. This is the opposite of
89 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT. If both flags are set together,
90 * @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT wins. If both flags are unset,
91 * this means to exclude default properties if there is a setting to compare,
92 * but include all properties, if the setting 'b' is missing. This is the legacy
93 * behaviour of libnm-util, where nm_setting_diff() behaved differently depending
94 * on whether the setting 'b' was available. If @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT
95 * is set, nm_setting_diff() will also set the flags @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT
96 * and @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT, if the values are default values.
97 * @NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP: ignore the connection's timestamp
98 *
99 * These flags modify the comparison behavior when comparing two settings or
100 * two connections.
101 *
102 **/
103typedef enum {
104 NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
105 NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
106 NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
107 NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004,
108 NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS = 0x00000008,
109 NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS = 0x00000010,
110 NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT = 0x00000020,
111 NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT = 0x00000040,
112 NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP = 0x00000080,
113
114 /* Higher flags like 0x80000000 and 0x40000000 are used internally as private flags */
115} NMSettingCompareFlags;
116
117/**
118 * NMSettingMacRandomization:
119 * @NM_SETTING_MAC_RANDOMIZATION_DEFAULT: the default value, which unless
120 * overridden by user-controlled defaults configuration, is "never".
121 * @NM_SETTING_MAC_RANDOMIZATION_NEVER: the device's MAC address is always used.
122 * @NM_SETTING_MAC_RANDOMIZATION_ALWAYS: a random MAC address is used.
123 *
124 * Controls if and how the MAC address of a device is randomzied.
125 *
126 * Since: 1.2
127 **/
128typedef enum {
129 NM_SETTING_MAC_RANDOMIZATION_DEFAULT = 0,
130 NM_SETTING_MAC_RANDOMIZATION_NEVER,
131 NM_SETTING_MAC_RANDOMIZATION_ALWAYS,
132} NMSettingMacRandomization;
133
134/**
135 * NMSettingClearSecretsWithFlagsFn:
136 * @setting: The setting for which secrets are being iterated
137 * @secret: The secret's name
138 * @flags: The secret's flags, eg %NM_SETTING_SECRET_FLAG_AGENT_OWNED
139 * @user_data: User data passed to nm_connection_clear_secrets_with_flags()
140 *
141 * Returns: %TRUE to clear the secret, %FALSE to not clear the secret
142 */
143typedef gboolean (*NMSettingClearSecretsWithFlagsFn)(NMSetting *setting,
144 const char *secret,
145 NMSettingSecretFlags flags,
146 gpointer user_data);
147
148struct _NMMetaSettingInfo;
149struct _NMSettInfoSetting;
150struct _NMSettInfoProperty;
151
152/**
153 * NMSettingValueIterFn:
154 * @setting: The setting for which properties are being iterated, given to
155 * nm_setting_enumerate_values()
156 * @key: The value/property name
157 * @value: The property's value
158 * @flags: The property's flags, like %NM_SETTING_PARAM_SECRET
159 * @user_data: User data passed to nm_setting_enumerate_values()
160 */
161typedef void (*NMSettingValueIterFn)(NMSetting *setting,
162 const char *key,
163 const GValue *value,
164 GParamFlags flags,
165 gpointer user_data);
166
167typedef struct _NMSettingClass NMSettingClass;
168
169GType nm_setting_get_type(void);
170
171GType nm_setting_lookup_type(const char *name);
172
173NMSetting *nm_setting_duplicate(NMSetting *setting);
174
175const char *nm_setting_get_name(NMSetting *setting);
176
177gboolean nm_setting_verify(NMSetting *setting, NMConnection *connection, GError **error);
178
179NM_AVAILABLE_IN_1_2
180gboolean nm_setting_verify_secrets(NMSetting *setting, NMConnection *connection, GError **error);
181
182gboolean nm_setting_compare(NMSetting *a, NMSetting *b, NMSettingCompareFlags flags);
183
184/**
185 * NMSettingDiffResult:
186 * @NM_SETTING_DIFF_RESULT_UNKNOWN: unknown result
187 * @NM_SETTING_DIFF_RESULT_IN_A: the property is present in setting A
188 * @NM_SETTING_DIFF_RESULT_IN_B: the property is present in setting B
189 * @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT: the property is present in
190 * setting A but is set to the default value. This flag is only set,
191 * if you specify @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT.
192 * @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT: analog to @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT.
193 *
194 * These values indicate the result of a setting difference operation.
195 **/
196typedef enum {
197 NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
198 NM_SETTING_DIFF_RESULT_IN_A = 0x00000001,
199 NM_SETTING_DIFF_RESULT_IN_B = 0x00000002,
200 NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
201 NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000008,
202} NMSettingDiffResult;
203
204gboolean nm_setting_diff(NMSetting *a,
205 NMSetting *b,
206 NMSettingCompareFlags flags,
207 gboolean invert_results,
208 GHashTable **results);
209
210void nm_setting_enumerate_values(NMSetting *setting, NMSettingValueIterFn func, gpointer user_data);
211
212char *nm_setting_to_string(NMSetting *setting);
213
214/*****************************************************************************/
215
216gboolean nm_setting_get_secret_flags(NMSetting *setting,
217 const char *secret_name,
218 NMSettingSecretFlags *out_flags,
219 GError **error);
220
221gboolean nm_setting_set_secret_flags(NMSetting *setting,
222 const char *secret_name,
223 NMSettingSecretFlags flags,
224 GError **error);
225
226/*****************************************************************************/
227
228NM_AVAILABLE_IN_1_26
229GVariant *nm_setting_option_get(NMSetting *setting, const char *opt_name);
230
231NM_AVAILABLE_IN_1_26
232gboolean
233nm_setting_option_get_boolean(NMSetting *setting, const char *opt_name, gboolean *out_value);
234
235NM_AVAILABLE_IN_1_26
236gboolean nm_setting_option_get_uint32(NMSetting *setting, const char *opt_name, guint32 *out_value);
237
238NM_AVAILABLE_IN_1_26
239void nm_setting_option_set(NMSetting *setting, const char *opt_name, GVariant *variant);
240
241NM_AVAILABLE_IN_1_26
242void nm_setting_option_set_uint32(NMSetting *setting, const char *opt_name, guint32 value);
243
244NM_AVAILABLE_IN_1_26
245void nm_setting_option_set_boolean(NMSetting *setting, const char *opt_name, gboolean value);
246
247NM_AVAILABLE_IN_1_26
248const char *const *nm_setting_option_get_all_names(NMSetting *setting, guint *out_len);
249
250NM_AVAILABLE_IN_1_26
251void nm_setting_option_clear_by_name(NMSetting *setting, NMUtilsPredicateStr predicate);
252
253/*****************************************************************************/
254
255const GVariantType *nm_setting_get_dbus_property_type(NMSetting *setting,
256 const char *property_name);
257
258NM_AVAILABLE_IN_1_46
259GType nm_setting_get_enum_property_type(GType setting_type, const char *property_name);
260
261/*****************************************************************************/
262
263typedef struct _NMRange NMRange;
264
265NM_AVAILABLE_IN_1_42
266GType nm_range_get_type(void);
267NM_AVAILABLE_IN_1_42
268NMRange *nm_range_new(guint64 start, guint64 end);
269NM_AVAILABLE_IN_1_42
270NMRange *nm_range_ref(const NMRange *range);
271NM_AVAILABLE_IN_1_42
272void nm_range_unref(const NMRange *range);
273NM_AVAILABLE_IN_1_42
274int nm_range_cmp(const NMRange *a, const NMRange *b);
275NM_AVAILABLE_IN_1_42
276gboolean nm_range_get_range(const NMRange *range, guint64 *start, guint64 *end);
277NM_AVAILABLE_IN_1_42
278char *nm_range_to_str(const NMRange *range);
279NM_AVAILABLE_IN_1_42
280NMRange *nm_range_from_str(const char *str, GError **error);
281
282G_END_DECLS
283
284#endif /* __NM_SETTING_H__ */
285

source code of include/libnm/nm-setting.h