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

+ + +

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 () +
+NMRange * +	+nm_range_new () +
+NMRange * +	+nm_range_ref () +
+void +	+nm_range_unref () +
+int +	+nm_range_cmp () +
+gboolean +	+nm_range_get_range () +
+char * +	+nm_range_to_str () +
+NMRange * +	+nm_range_from_str () +

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

    GBoxed
+    ╰── NMRange
+    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 +.

nm_range_new ()

NMRange *
+nm_range_new (guint64 start,
+              guint64 end);

Creates a new NMRange object for the given range. Setting end + +equal to start + creates a single-element range.

Parameters

+++++ + + + + + + + + + + + + +

start	the first element of the range
end	the last element of the range, must be greater than or equal +to `start` +.

Returns

the new NMRange object.

[transfer full]

Since: 1.42

nm_range_ref ()

NMRange *
+nm_range_ref (const NMRange *range);

Increases the reference count of the object. +This is thread-safe.

Parameters

+++++ + + + + + +

range

the NMRange

Returns

the input argument range +object.

Since: 1.42

nm_range_unref ()

void
+nm_range_unref (const NMRange *range);

Decreases the reference count of the object. If the reference count +reaches zero the object will be destroyed. +This is thread-safe.

Parameters

+++++ + + + + + +

range

the NMRange

Since: 1.42

nm_range_cmp ()

int
+nm_range_cmp (const NMRange *a,
+              const NMRange *b);

Compare two ranges.

Parameters

+++++ + + + + + + + + + + + + +

a	a NMRange
b	another NMRange

Returns

zero if the two instances are equivalent or +a non-zero integer otherwise. This defines a total ordering +over the ranges.

Since: 1.42

nm_range_get_range ()

gboolean
+nm_range_get_range (const NMRange *range,
+                    guint64 *start,
+                    guint64 *end);

Gets the start and end values for the range.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

range	the NMRange
start	location to store the start value.	[out]
end	location to store the end value.	[out]

Returns

TRUE if the range contains more than one +element, FALSE otherwise.

Since: 1.42

nm_range_to_str ()

char *
+nm_range_to_str (const NMRange *range);

Convert a NMRange to a string.

Parameters

+++++ + + + + + +

range

the NMRange

Returns

a string representing the range.

[transfer full]

Since: 1.42

nm_range_from_str ()

NMRange *
+nm_range_from_str (const char *str,
+                   GError **error);

Parses the string representation of the range to create a NMRange +instance.

Parameters

+++++ + + + + + + + + + + + + +

str	the string representation of a range
error	location to store the error on failure.	[out][allow-none]

Returns

the NMRange or NULL.

[transfer full]

Since: 1.42

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