// SPDX-License-Identifier: LGPL-2.1+
/*
* Copyright (C) 2007 - 2011 Red Hat, Inc.
* Copyright (C) 2007 - 2008 Novell, Inc.
*/
#ifndef __NM_SETTING_H__
#define __NM_SETTING_H__
#if !defined (__NETWORKMANAGER_H_INSIDE__) && !defined (NETWORKMANAGER_COMPILATION)
#error "Only <NetworkManager.h> can be included directly."
#endif
#include "nm-core-types.h"
G_BEGIN_DECLS
#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))
#define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SETTING))
#define NM_SETTING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SETTING, NMSettingClass))
/* The property of the #NMSetting is required for the setting to be valid */
#define NM_SETTING_PARAM_REQUIRED (1 << (1 + G_PARAM_USER_SHIFT))
/* The property of the #NMSetting is a secret */
#define NM_SETTING_PARAM_SECRET (1 << (2 + G_PARAM_USER_SHIFT))
/* The property of the #NMSetting should be ignored during comparisons that
* use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
*/
#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
/* Note: all non-glib GParamFlags bits are reserved by NetworkManager */
#define NM_SETTING_NAME "name"
/**
* NMSettingSecretFlags:
* @NM_SETTING_SECRET_FLAG_NONE: the system is responsible for providing and
* storing this secret (default)
* @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
* @NM_SETTING_SECRET_FLAG_NOT_REQUIRED: in situations where it cannot be
* automatically determined that the secret is required (some VPNs and PPP
* providers don't require all secrets) this flag indicates that the specific
* secret is not required
*
* 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 { /*< flags >*/
NM_SETTING_SECRET_FLAG_NONE = 0x00000000,
NM_SETTING_SECRET_FLAG_AGENT_OWNED = 0x00000001,
NM_SETTING_SECRET_FLAG_NOT_SAVED = 0x00000002,
NM_SETTING_SECRET_FLAG_NOT_REQUIRED = 0x00000004
/* NOTE: if adding flags, update nm-core-internal.h as well */
} NMSettingSecretFlags;
/**
* 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)
* @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.
* @NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP: ignore the connection's timestamp
*
* 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,
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,
NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP = 0x00000080,
/* Higher flags like 0x80000000 and 0x40000000 are used internally as private flags */
} NMSettingCompareFlags;
/**
* NMSettingMacRandomization:
* @NM_SETTING_MAC_RANDOMIZATION_DEFAULT: the default value, which unless
* overridden by user-controlled defaults configuration, is "never".
* @NM_SETTING_MAC_RANDOMIZATION_NEVER: the device's MAC address is always used.
* @NM_SETTING_MAC_RANDOMIZATION_ALWAYS: a random MAC address is used.
*
* Controls if and how the MAC address of a device is randomzied.
**/
typedef enum {
NM_SETTING_MAC_RANDOMIZATION_DEFAULT = 0,
NM_SETTING_MAC_RANDOMIZATION_NEVER,
NM_SETTING_MAC_RANDOMIZATION_ALWAYS,
} NMSettingMacRandomization;
/**
* NMSetting:
*
* The NMSetting struct contains only private data.
* It should only be accessed through the functions described below.
*/
struct _NMSetting {
GObject parent;
};
/**
* 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);
struct _NMMetaSettingInfo;
struct _NMSettInfoSetting;
struct _NMSettInfoProperty;
/**
* 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()
*/
typedef void (*NMSettingValueIterFn) (NMSetting *setting,
const char *key,
const GValue *value,
GParamFlags flags,
gpointer user_data);
/*< private >*/
typedef gboolean (*_NMConnectionForEachSecretFunc) (NMSettingSecretFlags flags,
gpointer user_data);
typedef struct {
GObjectClass parent;
/* Virtual functions */
int (*verify) (NMSetting *setting,
NMConnection *connection,
GError **error);
gboolean (*verify_secrets) (NMSetting *setting,
NMConnection *connection,
GError **error);
GPtrArray *(*need_secrets) (NMSetting *setting);
int (*update_one_secret) (NMSetting *setting,
const char *key,
GVariant *value,
GError **error);
gboolean (*get_secret_flags) (NMSetting *setting,
const char *secret_name,
NMSettingSecretFlags *out_flags,
GError **error);
gboolean (*set_secret_flags) (NMSetting *setting,
const char *secret_name,
NMSettingSecretFlags flags,
GError **error);
/*< private >*/
gboolean (*clear_secrets) (const struct _NMSettInfoSetting *sett_info,
guint property_idx,
NMSetting *setting,
NMSettingClearSecretsWithFlagsFn func,
gpointer user_data);
/* compare_property() returns a ternary, where DEFAULT means that the property should not
* be compared due to the compare @flags. A TRUE/FALSE result means that the property is
* equal/not-equal.
*
* @other may be %NULL, in which case the function only determines whether
* the setting should be compared (TRUE) or not (DEFAULT). */
/*< private >*/
NMTernary (*compare_property) (const struct _NMSettInfoSetting *sett_info,
guint property_idx,
NMConnection *con_a,
NMSetting *set_a,
NMConnection *con_b,
NMSetting *set_b,
NMSettingCompareFlags flags);
/*< private >*/
void (*duplicate_copy_properties) (const struct _NMSettInfoSetting *sett_info,
NMSetting *src,
NMSetting *dst);
/*< private >*/
void (*enumerate_values) (const struct _NMSettInfoProperty *property_info,
NMSetting *setting,
NMSettingValueIterFn func,
gpointer user_data);
/*< private >*/
gboolean (*aggregate) (NMSetting *setting,
int type_i,
gpointer arg);
/*< private >*/
void (*for_each_secret) (NMSetting *setting,
const char *secret_name,
GVariant *val,
gboolean remove_non_secrets,
_NMConnectionForEachSecretFunc callback,
gpointer callback_data,
GVariantBuilder *setting_builder);
/*< private >*/
gboolean (*init_from_dbus) (NMSetting *setting,
GHashTable *keys,
GVariant *setting_dict,
GVariant *connection_dict,
guint /* NMSettingParseFlags */ parse_flags,
GError **error);
/*< private >*/
gpointer padding[1];
/*< private >*/
const struct _NMMetaSettingInfo *setting_info;
} NMSettingClass;
GType nm_setting_get_type (void);
GType nm_setting_lookup_type (const char *name);
NMSetting *nm_setting_duplicate (NMSetting *setting);
const char *nm_setting_get_name (NMSetting *setting);
gboolean nm_setting_verify (NMSetting *setting,
NMConnection *connection,
GError **error);
NM_AVAILABLE_IN_1_2
gboolean nm_setting_verify_secrets (NMSetting *setting,
NMConnection *connection,
GError **error);
gboolean nm_setting_compare (NMSetting *a,
NMSetting *b,
NMSettingCompareFlags flags);
/**
* 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
* @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.
*
* 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,
NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000008,
} NMSettingDiffResult;
gboolean nm_setting_diff (NMSetting *a,
NMSetting *b,
NMSettingCompareFlags flags,
gboolean invert_results,
GHashTable **results);
void nm_setting_enumerate_values (NMSetting *setting,
NMSettingValueIterFn func,
gpointer user_data);
char *nm_setting_to_string (NMSetting *setting);
/*****************************************************************************/
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);
/*****************************************************************************/
NM_AVAILABLE_IN_1_26
GVariant *nm_setting_option_get (NMSetting *setting,
const char *opt_name);
NM_AVAILABLE_IN_1_26
gboolean nm_setting_option_get_boolean (NMSetting *setting,
const char *opt_name,
gboolean *out_value);
NM_AVAILABLE_IN_1_26
gboolean nm_setting_option_get_uint32 (NMSetting *setting,
const char *opt_name,
guint32 *out_value);
NM_AVAILABLE_IN_1_26
void nm_setting_option_set (NMSetting *setting,
const char *opt_name,
GVariant *variant);
NM_AVAILABLE_IN_1_26
void nm_setting_option_set_uint32 (NMSetting *setting,
const char *opt_name,
guint32 value);
NM_AVAILABLE_IN_1_26
void nm_setting_option_set_boolean (NMSetting *setting,
const char *opt_name,
gboolean value);
NM_AVAILABLE_IN_1_26
const char *const*nm_setting_option_get_all_names (NMSetting *setting,
guint *out_len);
NM_AVAILABLE_IN_1_26
void nm_setting_option_clear_by_name (NMSetting *setting,
NMUtilsPredicateStr predicate);
/*****************************************************************************/
const GVariantType *nm_setting_get_dbus_property_type (NMSetting *setting,
const char *property_name);
/*****************************************************************************/
G_END_DECLS
#endif /* __NM_SETTING_H__ */