NMSetting

+ + +

NMSetting

NMSetting — Describes related configuration information

Synopsis

+#include <nm-setting.h>
+
+enum                NMSettingError;
+#define             NM_TYPE_SETTING_ERROR
+#define             NM_SETTING_ERROR
+GQuark              nm_setting_error_quark              (void);
+#define             NM_SETTING_PARAM_SERIALIZE
+#define             NM_SETTING_PARAM_REQUIRED
+#define             NM_SETTING_PARAM_SECRET
+#define             NM_SETTING_PARAM_FUZZY_IGNORE
+#define             NM_SETTING_NAME
+                    NMSetting;
+                    NMSettingClass;
+void                (*NMSettingValueIterFn)             (NMSetting *setting,
+                                                         const char *key,
+                                                         const GValue *value,
+                                                         GParamFlags flags,
+                                                         gpointer user_data);
+GType               nm_setting_get_type                 (void);
+GHashTable *        nm_setting_to_hash                  (NMSetting *setting);
+NMSetting *         nm_setting_new_from_hash            (GType setting_type,
+                                                         GHashTable *hash);
+NMSetting *         nm_setting_duplicate                (NMSetting *setting);
+const char *        nm_setting_get_name                 (NMSetting *setting);
+gboolean            nm_setting_verify                   (NMSetting *setting,
+                                                         GSList *all_settings,
+                                                         GError **error);
+enum                NMSettingCompareFlags;
+gboolean            nm_setting_compare                  (NMSetting *a,
+                                                         NMSetting *b,
+                                                         NMSettingCompareFlags flags);
+void                nm_setting_enumerate_values         (NMSetting *setting,
+                                                         NMSettingValueIterFn func,
+                                                         gpointer user_data);
+char *              nm_setting_to_string                (NMSetting *setting);
+void                nm_setting_clear_secrets            (NMSetting *setting);
+GPtrArray *         nm_setting_need_secrets             (NMSetting *setting);
+gboolean            nm_setting_update_secrets           (NMSetting *setting,
+                                                         GHashTable *secrets,
+                                                         GError **error);
+

Object Hierarchy

+  GObject
+   +----NMSetting
+         +----NMSetting8021x
+         +----NMSettingBluetooth
+         +----NMSettingCdma
+         +----NMSettingConnection
+         +----NMSettingGsm
+         +----NMSettingIP4Config
+         +----NMSettingIP6Config
+         +----NMSettingOlpcMesh
+         +----NMSettingPPP
+         +----NMSettingPPPOE
+         +----NMSettingSerial
+         +----NMSettingVPN
+         +----NMSettingWired
+         +----NMSettingWireless
+         +----NMSettingWirelessSecurity
+

Properties

+  "name"                     gchar*                : Read / Write
+

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

enum NMSettingError

typedef enum
+{
+	NM_SETTING_ERROR_UNKNOWN = 0,
+	NM_SETTING_ERROR_PROPERTY_NOT_FOUND,
+	NM_SETTING_ERROR_PROPERTY_NOT_SECRET,
+	NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH
+} NMSettingError;
+

+Describes errors that may result from operations involving a NMSetting. +

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

`NM_SETTING_ERROR_UNKNOWN`	unknown or unclassified error +
`NM_SETTING_ERROR_PROPERTY_NOT_FOUND`	a property required by the operation + was not found; for example, an attempt to update an invalid secret +
`NM_SETTING_ERROR_PROPERTY_NOT_SECRET`	an operation which requires a secret + was attempted on a non-secret property +
`NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH`	the operation requires a property + of a specific type, or the value couldn't be transformed to the same type + as the property being acted upon +

NM_TYPE_SETTING_ERROR

#define NM_TYPE_SETTING_ERROR (nm_setting_error_get_type ()) 
+

NM_SETTING_ERROR

#define NM_SETTING_ERROR nm_setting_error_quark ()
+

nm_setting_error_quark ()

GQuark              nm_setting_error_quark              (void);

+Registers an error quark for NMSetting if necessary. +

++ + + + +

Returns :

the error quark used for NMSetting errors. +

NM_SETTING_PARAM_SERIALIZE

#define NM_SETTING_PARAM_SERIALIZE    (1 << (0 + G_PARAM_USER_SHIFT))
+

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

NMSetting

typedef struct _NMSetting NMSetting;

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

NMSettingClass

typedef struct {
+	GObjectClass parent;
+
+	/* Virtual functions */
+	gboolean    (*verify)            (NMSetting  *setting,
+	                                  GSList     *all_settings,
+	                                  GError     **error);
+
+	GPtrArray  *(*need_secrets)      (NMSetting  *setting);
+
+	gboolean    (*update_one_secret) (NMSetting  *setting,
+	                                  const char *key,
+	                                  GValue     *value,
+	                                  GError    **error);
+
+	/* Padding for future expansion */
+	void (*_reserved1) (void);
+	void (*_reserved2) (void);
+	void (*_reserved3) (void);
+	void (*_reserved4) (void);
+} NMSettingClass;
+

NMSettingValueIterFn ()

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

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

`setting` :	+
`key` :	+
`value` :	+
`flags` :	+
`user_data` :	+

nm_setting_get_type ()

GType               nm_setting_get_type                 (void);

++ + + + +

Returns :

nm_setting_to_hash ()

GHashTable *        nm_setting_to_hash                  (NMSetting *setting);

+Converts the NMSetting into a GHashTable mapping each setting property +name to a GValue describing that property, suitable for marshalling over +D-Bus or serializing. The mapping is string:GValue. +

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

`setting` :	the NMSetting +
Returns :	a new GHashTable describing the setting's properties +

nm_setting_new_from_hash ()

NMSetting *         nm_setting_new_from_hash            (GType setting_type,
+                                                         GHashTable *hash);

+Creates a new NMSetting object and populates that object with the properties +contained in the hash table, using each hash key as the property to set, +and each hash value as the value to set that property to. Setting properties +are strongly typed, thus the GValue type of the hash value must be correct. +See the documentation on each NMSetting object subclass for the correct +property names and value types. +

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

`setting_type` :	the NMSetting type which the hash contains properties for +
`hash` :	the GHashTable containing a string:GValue mapping of properties +that apply to the setting +
Returns :	a new NMSetting object populated with the properties from the +hash table, or NULL on failure +

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 +

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,
+                                                         GSList *all_settings,
+                                                         GError **error);

+Validates the setting. Each setting's properties have allowed values, and +some are dependent on other values (hence the need for all_settings). 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 +
`all_settings` :	a GSList of all settings in the connection from which `setting` +came +
`error` :	location to store error, or `NULL` +
Returns :	`TRUE` if the setting is valid, `FALSE` if it is not +

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
+} 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 secrets +

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 +

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

void                nm_setting_clear_secrets            (NMSetting *setting);

+Resets and clears any secrets in the setting. Secrets should be added to the +setting only when needed, and cleared immediately after use to prevent +leakage of information. +

++ + + + +

setting :

the NMSetting +

nm_setting_need_secrets ()

GPtrArray *         nm_setting_need_secrets             (NMSetting *setting);

+Returns an array of property names for each secret which may be required +to make a successful connection. The returned hints are only intended as a +guide to what secrets may be required, because in some circumstances, there +is no way to conclusively determine exactly which secrets are needed. +

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

`setting` :	the NMSetting +
Returns :	a GPtrArray containing the property names of secrets of the +NMSetting which may be required; the caller owns the array +and must free the each array element with `g_free()`, as well as the array +itself with `g_ptr_array_free()` +

nm_setting_update_secrets ()

gboolean            nm_setting_update_secrets           (NMSetting *setting,
+                                                         GHashTable *secrets,
+                                                         GError **error);

+Update the setting's secrets, given a hash table of secrets intended for that +setting (deserialized from D-Bus for example). +

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

`setting` :	the NMSetting +
`secrets` :	a GHashTable mapping string:GValue of setting property names and +secrets +
`error` :	location to store error, or `NULL` +
Returns :	`TRUE` if the secrets were successfully updated and the connection +is valid, `FALSE` on failure or if the setting was never added to the connection +

Property Details

The `"name"` property

  "name"                     gchar*                : Read / Write

+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-util Reference Manual
+Top + \| + Description + \| + Object Hierarchy + \| + Properties +

NMSetting

Synopsis

Object Hierarchy

Properties

Description

Details

enum NMSettingError

NM_TYPE_SETTING_ERROR

NM_SETTING_ERROR

nm_setting_error_quark ()

NM_SETTING_PARAM_SERIALIZE

NM_SETTING_PARAM_REQUIRED

NM_SETTING_PARAM_SECRET

NM_SETTING_PARAM_FUZZY_IGNORE

NM_SETTING_NAME

NMSetting

NMSettingClass

NMSettingValueIterFn ()

nm_setting_get_type ()

nm_setting_to_hash ()

nm_setting_new_from_hash ()

nm_setting_duplicate ()

nm_setting_get_name ()

nm_setting_verify ()

enum NMSettingCompareFlags

nm_setting_compare ()

nm_setting_enumerate_values ()

nm_setting_to_string ()

nm_setting_clear_secrets ()

nm_setting_need_secrets ()

nm_setting_update_secrets ()

Property Details

The "name" property

The `"name"` property