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

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

	/* Padding for future expansion */
	void (*_reserved1) (void);
	void (*_reserved2) (void);
} NMSettingClass;

NMSettingClearSecretsWithFlagsFn ()

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

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.

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.

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.

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

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.

NMSettingValueIterFn ()

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

NM_SETTING_NAME

#define NM_SETTING_NAME "name"

NM_SETTING_PARAM_FUZZY_IGNORE

#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + 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_SERIALIZE

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

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.

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.

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.

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.

nm_setting_duplicate ()

NMSetting *         nm_setting_duplicate                (NMSetting *setting);

Duplicates a NMSetting.

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.

nm_setting_error_quark ()

GQuark              nm_setting_error_quark              (void);

Registers an error quark for NMSetting if necessary.

nm_setting_get_name ()

const char *        nm_setting_get_name                 (NMSetting *setting);

Returns the type name of the NMSetting object

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.

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.

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.

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.

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.

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.

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

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.

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