NMSetting

+ + +

NMSetting

NMSetting — Describes related configuration information

Synopsis

#define             NM_SETTING_PARAM_REQUIRED
+#define             NM_SETTING_PARAM_SECRET
+#define             NM_SETTING_PARAM_FUZZY_IGNORE
+#define             NM_SETTING_NAME
+enum                NMSettingSecretFlags;
+enum                NMSettingCompareFlags;
+struct              NMSetting;
+gboolean            (*NMSettingClearSecretsWithFlagsFn) (NMSetting *setting,
+                                                         const char *secret,
+                                                         NMSettingSecretFlags flags,
+                                                         gpointer user_data);
+                    NMSettingClass;
+void                (*NMSettingValueIterFn)             (NMSetting *setting,
+                                                         const char *key,
+                                                         const GValue *value,
+                                                         GParamFlags flags,
+                                                         gpointer user_data);
+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);
+gboolean            nm_setting_compare                  (NMSetting *a,
+                                                         NMSetting *b,
+                                                         NMSettingCompareFlags flags);
+enum                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);
+const GVariantType * nm_setting_get_dbus_property_type  (NMSetting *setting,
+                                                         const char *property_name);
+

Object Hierarchy

+  GFlags
+   +----NMSettingSecretFlags
+

+  GEnum
+   +----NMSettingCompareFlags
+

+  GObject
+   +----NMSetting
+         +----NMSetting8021x
+         +----NMSettingAdsl
+         +----NMSettingBluetooth
+         +----NMSettingBond
+         +----NMSettingBridgePort
+         +----NMSettingBridge
+         +----NMSettingCdma
+         +----NMSettingConnection
+         +----NMSettingDcb
+         +----NMSettingGeneric
+         +----NMSettingGsm
+         +----NMSettingInfiniband
+         +----NMSettingIPConfig
+         +----NMSettingOlpcMesh
+         +----NMSettingPpp
+         +----NMSettingPppoe
+         +----NMSettingSerial
+         +----NMSettingTeamPort
+         +----NMSettingTeam
+         +----NMSettingVlan
+         +----NMSettingVpn
+         +----NMSettingWimax
+         +----NMSettingWired
+         +----NMSettingWirelessSecurity
+         +----NMSettingWireless
+

+  GEnum
+   +----NMSettingDiffResult
+

Properties

+  "name"                     gchar*                : Read
+

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

Details

NM_SETTING_PARAM_REQUIRED

#define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))
+

NM_SETTING_PARAM_SECRET

#define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))
+

NM_SETTING_PARAM_FUZZY_IGNORE

#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
+

NM_SETTING_NAME

#define NM_SETTING_NAME "name"
+

enum NMSettingSecretFlags

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;
+

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

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

`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 dont require all secrets) this flag indicates that the specific +secret is not required +

enum NMSettingCompareFlags

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,
+
+	/* 0x80000000 is used for a private flag */
+} NMSettingCompareFlags;
+

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

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

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

struct NMSetting

struct NMSetting;

+The NMSetting struct contains only private data. +It should only be accessed through the functions described below. +

NMSettingClearSecretsWithFlagsFn ()

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

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

`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

NMSettingClass

typedef struct {
+	GObjectClass parent;
+
+	/* Virtual functions */
+	gint        (*verify)            (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,
+	                                  gboolean verify_secret,
+	                                  NMSettingSecretFlags *out_flags,
+	                                  GError **error);
+
+	gboolean    (*set_secret_flags)  (NMSetting  *setting,
+	                                  const char *secret_name,
+	                                  gboolean verify_secret,
+	                                  NMSettingSecretFlags flags,
+	                                  GError **error);
+
+	gboolean    (*clear_secrets_with_flags) (NMSetting *setting,
+	                                         GParamSpec *pspec,
+	                                         NMSettingClearSecretsWithFlagsFn func,
+	                                         gpointer user_data);
+
+	/* 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);
+} NMSettingClass;
+

NMSettingValueIterFn ()

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

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

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

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

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

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

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

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

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

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

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

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

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

`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

enum NMSettingDiffResult

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 = 0x00000004,
+} NMSettingDiffResult;
+

+These values indicate the result of a setting difference operation. +

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

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

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

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

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

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

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

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

`setting` :	the NMSetting +
Returns :	an allocated string containing a textual representation of the +setting's properties and values (including secrets!), 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. +

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

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

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

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

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

`setting` :	an NMSetting +
`property_name` :	the property of `setting` to get the type of
Returns :	the D-Bus marshalling type of `property` on `setting`.

Property Details

The `"name"` property

  "name"                     gchar*                : Read

+The setting's name, which uniquely identifies the setting within the +connection. Each setting type has a name unique to that type, for +example "ppp" or "wireless" or "wired". +

Default value: NULL

			libnm Reference Manual
+Top + \| + Description + \| + Object Hierarchy + \| + Properties +

NMSetting

Synopsis

Object Hierarchy

Properties

Description

Details

NM_SETTING_PARAM_REQUIRED

NM_SETTING_PARAM_SECRET

NM_SETTING_PARAM_FUZZY_IGNORE

NM_SETTING_NAME

enum NMSettingSecretFlags

enum NMSettingCompareFlags

struct NMSetting

NMSettingClearSecretsWithFlagsFn ()

NMSettingClass

NMSettingValueIterFn ()

nm_setting_lookup_type ()

nm_setting_duplicate ()

nm_setting_get_name ()

nm_setting_verify ()

nm_setting_compare ()

enum NMSettingDiffResult

nm_setting_diff ()

nm_setting_enumerate_values ()

nm_setting_to_string ()

nm_setting_get_secret_flags ()

nm_setting_set_secret_flags ()

nm_setting_get_dbus_property_type ()

Property Details

The "name" property

The `"name"` property