NMSetting

NMSetting — Describes related configuration information

Properties

gchar * name Read / Write

Object Hierarchy

    GEnum
    ├── NMSettingCompareFlags
    ├── NMSettingDiffResult
    ├── NMSettingError
    ├── NMSettingHashFlags
    ╰── NMSettingSecretFlags
    GObject
    ╰── NMSetting
        ├── NMSetting8021x
        ├── NMSettingAdsl
        ├── NMSettingBluetooth
        ├── NMSettingBond
        ├── NMSettingTeam
        ├── NMSettingTeamPort
        ├── NMSettingBridge
        ├── NMSettingBridgePort
        ├── NMSettingConnection
        ├── NMSettingDcb
        ├── NMSettingInfiniband
        ├── NMSettingIP4Config
        ├── NMSettingVlan
        ├── NMSettingIP6Config
        ├── NMSettingPPP
        ├── NMSettingPPPOE
        ├── NMSettingSerial
        ├── NMSettingGeneric
        ├── NMSettingGsm
        ├── NMSettingCdma
        ├── NMSettingOlpcMesh
        ├── NMSettingWimax
        ├── NMSettingWired
        ├── NMSettingWireless
        ├── NMSettingWirelessSecurity
        ╰── NMSettingVPN

Includes

#include <nm-setting.h>

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

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.


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

 

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.

Parameters

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.

Parameters

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.

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

Parameters

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.

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

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

Parameters

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 .

Parameters

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.

Parameters

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

Parameters

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.

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

Parameters

setting

the NMSetting

 

Returns

Name of the virtual interface or NULL if the setting does not support this feature

Types and Values

enum NMSettingError

Describes errors that may result from operations involving a NMSetting.

Members

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

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.

 

NMSetting

typedef struct _NMSetting NMSetting;

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


enum NMSettingHashFlags

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

Members

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

 

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 .

 

Property Details

The “name” property

  “name”                     gchar *

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

Owner: NMSetting

Flags: Read / Write

Default value: NULL