NMSetting: libnm Reference Manual

- - -

NMSetting

NMSetting — Describes related configuration information

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-gboolean -	-(*NMSettingClearSecretsWithFlagsFn) () -
-void -	-(*NMSettingValueIterFn) () -
-gboolean -	-(*_NMConnectionForEachSecretFunc) () -
-GType -	-nm_setting_lookup_type () -
-NMSetting * -	-nm_setting_duplicate () -
const char * -	-nm_setting_get_name () -
-gboolean -	-nm_setting_verify () -
-gboolean -	-nm_setting_verify_secrets () -
-gboolean -	-nm_setting_compare () -
-gboolean -	-nm_setting_diff () -
-void -	-nm_setting_enumerate_values () -
-char * -	-nm_setting_to_string () -
-gboolean -	-nm_setting_get_secret_flags () -
-gboolean -	-nm_setting_set_secret_flags () -
-GVariant * -	-nm_setting_option_get () -
-gboolean -	-nm_setting_option_get_boolean () -
-gboolean -	-nm_setting_option_get_uint32 () -
-void -	-nm_setting_option_set () -
-void -	-nm_setting_option_set_uint32 () -
-void -	-nm_setting_option_set_boolean () -
const char const -	-nm_setting_option_get_all_names () -
-void -	-nm_setting_option_clear_by_name () -
const GVariantType * -	-nm_setting_get_dbus_property_type () -

Types and Values

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#define	NM_SETTING_PARAM_REQUIRED
#define	NM_SETTING_PARAM_SECRET
#define	NM_SETTING_PARAM_FUZZY_IGNORE
#define	NM_SETTING_NAME
enum	NMSettingSecretFlags
enum	NMSettingCompareFlags
enum	NMSettingMacRandomization
enum	NMSettingDiffResult

Object Hierarchy

    GEnum
-    ├── NMSettingCompareFlags
-    ├── NMSettingDiffResult
-    ╰── NMSettingMacRandomization
-    GFlags
-    ╰── NMSettingSecretFlags
-

Description

Each NMSetting contains properties that describe configuration that applies -to a specific network layer (like IPv4 or IPv6 configuration) or device type -(like Ethernet, or Wi-Fi). A collection of individual settings together -make up an NMConnection. Each property is strongly typed and usually has -a number of allowed values. See each NMSetting subclass for a description -of properties and allowed values.

Functions

NMSettingClearSecretsWithFlagsFn ()

gboolean
-(*NMSettingClearSecretsWithFlagsFn) (NMSetting *setting,
-                                     const char *secret,
-                                     NMSettingSecretFlags flags,
-                                     gpointer user_data);

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

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

NMSettingValueIterFn ()

void
-(*NMSettingValueIterFn) (NMSetting *setting,
-                         const char *key,
-                         const GValue *value,
-                         GParamFlags flags,
-                         gpointer user_data);

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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()`

_NMConnectionForEachSecretFunc ()

gboolean
-(*_NMConnectionForEachSecretFunc) (NMSettingSecretFlags flags,
-                                   gpointer user_data);

nm_setting_lookup_type ()

GType
-nm_setting_lookup_type (const char *name);

Returns the GType of the setting's class for a given setting name.

Parameters

----- - - - - - -

name

a setting name

Returns

the GType of the setting's class, or G_TYPE_INVALID if -name -is not recognized.

nm_setting_duplicate ()

NMSetting *
-nm_setting_duplicate (NMSetting *setting);

Duplicates a NMSetting.

Parameters

----- - - - - - -

setting

the NMSetting to duplicate

Returns

a new NMSetting containing the same properties and values as the -source NMSetting.

[transfer full]

nm_setting_get_name ()

const char *
-nm_setting_get_name (NMSetting *setting);

Returns the type name of the NMSetting object

Parameters

----- - - - - - -

setting

the NMSetting

Returns

a string containing the type name of the NMSetting object, -like 'ppp' or 'wireless' or 'wired'.

nm_setting_verify ()

gboolean
-nm_setting_verify (NMSetting *setting,
-                   NMConnection *connection,
-                   GError **error);

Validates the setting. Each setting's properties have allowed values, and -some are dependent on other values (hence the need for connection -). The -returned GError contains information about which property of the setting -failed validation, and in what way that property failed validation.

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting to verify
connection	the NMConnection that `setting` -came from, or -`NULL` if `setting` -is being verified in isolation.	[allow-none]
error	location to store error, or `NULL`

Returns

TRUE if the setting is valid, FALSE if it is not

nm_setting_verify_secrets ()

gboolean
-nm_setting_verify_secrets (NMSetting *setting,
-                           NMConnection *connection,
-                           GError **error);

Verifies the secrets in the setting. -The returned GError contains information about which secret of the setting -failed validation, and in what way that secret failed validation. -The secret validation is done separately from main setting validation, because -in some cases connection failure is not desired just for the secrets.

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting to verify secrets in
connection	the NMConnection that `setting` -came from, or -`NULL` if `setting` -is being verified in isolation.	[allow-none]
error	location to store error, or `NULL`

Returns

TRUE if the setting secrets are valid, FALSE if they are not

Since: 1.2

nm_setting_compare ()

gboolean
-nm_setting_compare (NMSetting *a,
-                    NMSetting *b,
-                    NMSettingCompareFlags flags);

Compares two NMSetting objects for similarity, with comparison behavior -modified by a set of flags. See the documentation for NMSettingCompareFlags -for a description of each flag's behavior.

Parameters

----- - - - - - - - - - - - - - - - - - -

a	a NMSetting
b	a second NMSetting to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`

Returns

TRUE if the comparison succeeds, FALSE if it does not

nm_setting_diff ()

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

Compares two NMSetting objects for similarity, with comparison behavior -modified by a set of flags. See the documentation for NMSettingCompareFlags -for a description of each flag's behavior. If the settings differ, the keys -of each setting that differ from the other are added to results -, mapped to -one or more NMSettingDiffResult values.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

a	a NMSetting
b	a second NMSetting to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`
invert_results	this parameter is used internally by libnm and should -be set to `FALSE`. If `TRUE` inverts the meaning of the NMSettingDiffResult.
results	if the -settings differ, on return a hash table mapping the differing keys to one or -more `NMSettingDiffResult` values OR-ed together. If the settings do not -differ, any hash table passed in is unmodified. If no hash table is passed -in and the settings differ, a new one is created and returned.	[inout][transfer full][element-type utf8 guint32]

Returns

TRUE if the settings contain the same values, FALSE if they do not

nm_setting_enumerate_values ()

void
-nm_setting_enumerate_values (NMSetting *setting,
-                             NMSettingValueIterFn func,
-                             gpointer user_data);

Iterates over each property of the NMSetting object, calling the supplied -user function for each property.

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting
func	user-supplied function called for each property of the setting.	[scope call]
user_data	user data passed to `func` -at each invocation

nm_setting_to_string ()

char *
-nm_setting_to_string (NMSetting *setting);

Convert the setting (including secrets!) into a string. For debugging -purposes ONLY, should NOT be used for serialization of the setting, -or machine-parsed in any way. The output format is not guaranteed to -be stable and may change at any time.

Parameters

----- - - - - - -

setting

the NMSetting

Returns

an allocated string containing a textual representation of the -setting's properties and values, which the caller should -free with g_free()

nm_setting_get_secret_flags ()

gboolean
-nm_setting_get_secret_flags (NMSetting *setting,
-                             const char *secret_name,
-                             NMSettingSecretFlags *out_flags,
-                             GError **error);

For a given secret, retrieves the NMSettingSecretFlags describing how to -handle that secret.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

setting	the NMSetting
secret_name	the secret key name to get flags for
out_flags	on success, the NMSettingSecretFlags for the secret
error	location to store error, or `NULL`

Returns

TRUE on success (if the given secret name was a valid property of -this setting, and if that property is secret), FALSE if not

nm_setting_set_secret_flags ()

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

For a given secret, stores the NMSettingSecretFlags describing how to -handle that secret.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

setting	the NMSetting
secret_name	the secret key name to set flags for
flags	the NMSettingSecretFlags for the secret
error	location to store error, or `NULL`

Returns

TRUE on success (if the given secret name was a valid property of -this setting, and if that property is secret), FALSE if not

nm_setting_option_get ()

GVariant *
-nm_setting_option_get (NMSetting *setting,
-                       const char *opt_name);

Parameters

----- - - - - - - - - - - - - -

setting	the NMSetting
opt_name	the option name to request.

Returns

the GVariant or NULL if the option -is not set.

[transfer none]

Since: 1.26

nm_setting_option_get_boolean ()

gboolean
-nm_setting_option_get_boolean (NMSetting *setting,
-                               const char *opt_name,
-                               gboolean *out_value);

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting
opt_name	the option to get
out_value	the optional output value. -If the option is unset, `FALSE` will be returned.	[allow-none][out]

Returns

TRUE if opt_name -is set to a boolean variant.

Since: 1.26

nm_setting_option_get_uint32 ()

gboolean
-nm_setting_option_get_uint32 (NMSetting *setting,
-                              const char *opt_name,
-                              guint32 *out_value);

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting
opt_name	the option to get
out_value	the optional output value. -If the option is unset, 0 will be returned.	[allow-none][out]

Returns

TRUE if opt_name -is set to a uint32 variant.

Since: 1.26

nm_setting_option_set ()

void
-nm_setting_option_set (NMSetting *setting,
-                       const char *opt_name,
-                       GVariant *variant);

If variant - is NULL, this clears the option if it is set. -Otherwise, variant - is set as the option. If variant - is -a floating reference, it will be consumed.

Note that not all setting types support options. It is a bug -setting a variant to a setting that doesn't support it. -Currently, only NMSettingEthtool supports it.

Parameters

----- - - - - - - - - - - - - - - - - - -

setting	the NMSetting
opt_name	the option name to set
variant	the variant to set.	[allow-none]

Since: 1.26

nm_setting_option_set_uint32 ()

void
-nm_setting_option_set_uint32 (NMSetting *setting,
-                              const char *opt_name,
-                              guint32 value);

Like nm_setting_option_set() to set a uint32 GVariant.

Parameters

----- - - - - - - - - - - - - -

setting	the NMSetting
value	the value to set.

Since: 1.26

nm_setting_option_set_boolean ()

void
-nm_setting_option_set_boolean (NMSetting *setting,
-                               const char *opt_name,
-                               gboolean value);

Like nm_setting_option_set() to set a boolean GVariant.

Parameters

----- - - - - - - - - - - - - -

setting	the NMSetting
value	the value to set.

Since: 1.26

nm_setting_option_get_all_names ()

const char *const *
-nm_setting_option_get_all_names (NMSetting *setting,
-                                 guint *out_len);

Gives the name of all set options.

Parameters

----- - - - - - - - - - - - - -

setting	the NMSetting
out_len	.	[allow-none][out]

Returns

A NULL terminated array of key names. If no names are present, this returns -NULL. The returned array and the names are owned by NMSetting and might be invalidated -by the next operation.

[array length=out_len zero-terminated=1][transfer none]

Since: 1.26

nm_setting_option_clear_by_name ()

void
-nm_setting_option_clear_by_name (NMSetting *setting,
-                                 NMUtilsPredicateStr predicate);

Parameters

----- - - - - - - - - - - - - -

setting	the NMSetting
predicate	the predicate for which names -should be clear. -If the predicate returns `TRUE` for an option name, the option -gets removed. If `NULL`, all options will be removed.	[allow-none][scope call]

Since: 1.26

nm_setting_get_dbus_property_type ()

const GVariantType *
-nm_setting_get_dbus_property_type (NMSetting *setting,
-                                   const char *property_name);

Gets the D-Bus marshalling type of a property. property_name - is a D-Bus -property name, which may not necessarily be a GObject property.

Parameters

----- - - - - - - - - - - - - -

setting	an NMSetting
property_name	the property of `setting` -to get the type of

Returns

the D-Bus marshalling type of property -on setting -.

Types and Values

NM_SETTING_PARAM_REQUIRED

#define NM_SETTING_PARAM_REQUIRED 0x200
-

NM_SETTING_PARAM_SECRET

#define NM_SETTING_PARAM_SECRET 0x400
-

NM_SETTING_PARAM_FUZZY_IGNORE

#define NM_SETTING_PARAM_FUZZY_IGNORE 0x800
-

NM_SETTING_NAME

#define NM_SETTING_NAME "name"
-

enum NMSettingSecretFlags

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.

Members

----- - - - - - - - - - - - - - - - - - - - - - - -

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 -

enum NMSettingCompareFlags

These flags modify the comparison behavior when comparing two settings or -two connections.

Members

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -

enum NMSettingMacRandomization

Controls if and how the MAC address of a device is randomzied.

Members

----- - - - - - - - - - - - - - - - - - -

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. -

Since: 1.2

enum NMSettingDiffResult

These values indicate the result of a setting difference operation.

Members

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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` -. -