## NMSetting

NMSetting — Describes related configuration information

## Synopsis

    #include <nm-setting.h>

    enum                NMSettingError;
    #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
    enum                NMSettingSecretFlags;
    enum                NMSettingCompareFlags;
                        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);
    enum                NMSettingHashFlags;
    GHashTable *        nm_setting_to_hash                  (NMSetting *setting,
                                                             NMSettingHashFlags flags);
    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);
    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);
    void                nm_setting_clear_secrets            (NMSetting *setting);
    void                nm_setting_clear_secrets_with_flags (NMSetting *setting,
                                                             NMSettingClearSecretsWithFlagsFn func,
                                                             gpointer user_data);
    GPtrArray *         nm_setting_need_secrets             (NMSetting *setting);
    gboolean            nm_setting_update_secrets           (NMSetting *setting,
                                                             GHashTable *secrets,
                                                             GError **error);
    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 char *        nm_setting_get_virtual_iface_name   (NMSetting *setting);

## Object Hierarchy

      GEnum
       +----NMSettingError

      GEnum
       +----NMSettingSecretFlags

      GEnum
       +----NMSettingCompareFlags

      GObject
       +----NMSetting
             +----NMSetting8021x
             +----NMSettingAdsl
             +----NMSettingBluetooth
             +----NMSettingBond
             +----NMSettingBridge
             +----NMSettingBridgePort
             +----NMSettingConnection
             +----NMSettingInfiniband
             +----NMSettingIP4Config
             +----NMSettingVlan
             +----NMSettingIP6Config
             +----NMSettingPPP
             +----NMSettingPPPOE
             +----NMSettingSerial
             +----NMSettingGsm
             +----NMSettingCdma
             +----NMSettingOlpcMesh
             +----NMSettingWimax
             +----NMSettingWired
             +----NMSettingWireless
             +----NMSettingWirelessSecurity
             +----NMSettingVPN

      GEnum
       +----NMSettingHashFlags

      GEnum
       +----NMSettingDiffResult

## 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,           /*< nick=UnknownError >*/
    	NM_SETTING_ERROR_PROPERTY_NOT_FOUND,    /*< nick=PropertyNotFound >*/
    	NM_SETTING_ERROR_PROPERTY_NOT_SECRET,   /*< nick=PropertyNotSecret >*/
    	NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH /*< nick=PropertyTypeMismatch >*/
    } 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_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"

### enum NMSettingSecretFlags

    typedef enum {
    	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-setting-private.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
    } 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`)

### NMSetting

    typedef struct _NMSetting 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 */
    	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);

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

    	/* 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);

    	void        (*clear_secrets_with_flags) (NMSetting *setting,
    	                                         GParamSpec *pspec,
    	                                         NMSettingClearSecretsWithFlagsFn func,
    	                                         gpointer user_data);

    	const char *(*get_virtual_iface_name) (NMSetting *setting);

    	/* Padding for future expansion */
    	void (*_reserved1) (void);
    } 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()`

### enum NMSettingHashFlags

    typedef enum {
    	NM_SETTING_HASH_FLAG_ALL = 0x00000000,
    	NM_SETTING_HASH_FLAG_NO_SECRETS = 0x00000001,
    	NM_SETTING_HASH_FLAG_ONLY_SECRETS = 0x00000002,
    } NMSettingHashFlags;

These flags determine which properties are added to the resulting hash when calling `nm_setting_to_hash()`.

`NM_SETTING_HASH_FLAG_ALL` | hash all properties (including secrets)
`NM_SETTING_HASH_FLAG_NO_SECRETS` | do not include secrets
`NM_SETTING_HASH_FLAG_ONLY_SECRETS` | only hash secrets

### nm_setting_to_hash ()

    GHashTable *        nm_setting_to_hash                  (NMSetting *setting,
                                                             NMSettingHashFlags flags);

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

`setting` : | the NMSetting
`flags` : | hash flags, e.g. `NM_SETTING_HASH_FLAG_ALL`
Returns : | a new GHashTable describing the setting's properties. [transfer full][element-type utf8 GObject.Value]

### 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 to GValue mapping of properties that apply to the setting. [element-type utf8 GObject.Value]
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. [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,
                                                             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. [element-type NMSetting]
`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,
    } 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 ()

    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-util 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_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_clear_secrets_with_flags ()

    void                nm_setting_clear_secrets_with_flags (NMSetting *setting,
                                                             NMSettingClearSecretsWithFlagsFn func,
                                                             gpointer user_data);

Clears and frees secrets determined by `func`.

`setting` : | the NMSetting
`func` : | function to be called to determine whether a specific secret should be cleared or not. [scope call]
`user_data` : | caller-supplied data passed to `func`

### 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 it with `g_ptr_array_free()`, but must not free the elements. [transfer container][element-type utf8]

### 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 to GValue of setting property names and secrets. [element-type utf8 GObject.Value]
`error` : | location to store error, or `NULL`
Returns : | `TRUE` if the secrets were successfully updated, `FALSE` on failure to update one or more of the secrets.

### 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, retrieves 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_virtual_iface_name ()

    const char *        nm_setting_get_virtual_iface_name   (NMSetting *setting);

Returns the name of the virtual kernel interface which the connection needs to use if specified in the settings.

`setting` : | the NMSetting
Returns : | Name of the virtual interface or `NULL` if the setting does not support this feature

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