Properties

@@ -155,166 +152,95 @@ 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))
-

NMSetting

typedef struct _NMSetting NMSetting;

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

NM_SETTING_NAME

#define NM_SETTING_NAME "name"
+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;

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

NMSettingClearSecretsWithFlagsFn ()

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

- - + + - - + + - - + - - + + + + +

`NM_SETTING_SECRET_FLAG_NONE`	the system is responsible for providing and -storing this secret (default) -	`setting` :	The setting for which secrets are being iterated
`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 -	`secret` :	The secret's name
`NM_SETTING_SECRET_FLAG_NOT_SAVED`	this secret should not be saved, but -should be requested from the user each time it is needed +	`flags` :	The secret's flags, eg `NM_SETTING_SECRET_FLAG_AGENT_OWNED`
`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 +	`user_data` :	User data passed to `nm_connection_clear_secrets_with_flags()`
Returns :	+`TRUE` to clear the secret, `FALSE` to not clear the secret

@@ -378,131 +304,75 @@ storage (ie, the secret's flag includes NM_SETTING_S

-NMSetting -typedef struct _NMSetting NMSetting; +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; + -The NMSetting struct contains only private data. -It should only be accessed through the functions described below. +These values indicate the result of a setting difference operation. - - - -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 + NM_SETTING_DIFF_RESULT_UNKNOWN unknown result user_data : User data passed to nm_connection_clear_secrets_with_flags() + NM_SETTING_DIFF_RESULT_IN_A the property is present in setting A Returns : -TRUE to clear the secret, FALSE to not clear the secret NM_SETTING_DIFF_RESULT_IN_B the property is present in setting B + -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; +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. - - - -NMSettingValueIterFn () -void (*NMSettingValueIterFn) (NMSetting *setting, - const char *key, - const GValue *value, - GParamFlags flags, - gpointer user_data); - - + - - - - - - + + - - + - - + @@ -510,13 +380,6 @@ It should only be accessed through the functions described below. -nm_setting_get_type () -GType nm_setting_get_type (void); - - - - - enum NMSettingHashFlags typedef enum { NM_SETTING_HASH_FLAG_ALL = 0x00000000, @@ -551,31 +414,49 @@ when calling -nm_setting_to_hash () -GHashTable * nm_setting_to_hash (NMSetting *setting, - NMSettingHashFlags flags); +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; + -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. +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. setting : The setting for which properties are being iterated, given to -nm_setting_enumerate_values() + NM_SETTING_ERROR_UNKNOWN unknown or unclassified error key : The value/property name value : The property's value NM_SETTING_ERROR_PROPERTY_NOT_FOUND a property required by the operation + was not found; for example, an attempt to update an invalid secret + flags : The property's flags, like NM_SETTING_PARAM_SECRET + NM_SETTING_ERROR_PROPERTY_NOT_SECRET an operation which requires a secret + was attempted on a non-secret property user_data : User data passed to nm_setting_enumerate_values() + 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 - - + - - + - - + + + + + @@ -583,118 +464,127 @@ 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. - +NMSettingValueIterFn () +void (*NMSettingValueIterFn) (NMSetting *setting, + const char *key, + const GValue *value, + GParamFlags flags, + gpointer user_data); setting : the NMSetting + NM_SETTING_SECRET_FLAG_NONE the system is responsible for providing and +storing this secret (default) flags : hash flags, e.g. NM_SETTING_HASH_FLAG_ALL + 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 Returns : a new GHashTable -describing the setting's properties. [transfer full][element-type utf8 GObject.Value] + 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 - - + + - - + + + + + + + + + - - + + setting_type : the NMSetting type which the hash contains properties for setting : The setting for which properties are being iterated, given to +nm_setting_enumerate_values() + hash : the GHashTable containing a -string to GValue mapping of properties that apply to the setting. [element-type utf8 GObject.Value] + key : The value/property name value : The property's value flags : The property's flags, like NM_SETTING_PARAM_SECRET Returns : a new NMSetting object populated with the properties from the -hash table, or NULL on failure user_data : User data passed to nm_setting_enumerate_values() + -nm_setting_duplicate () -NMSetting * nm_setting_duplicate (NMSetting *setting); +NM_SETTING_NAME +#define NM_SETTING_NAME "name" + -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); +NM_SETTING_PARAM_FUZZY_IGNORE +#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT)) + -Returns the type name of the NMSetting object + + + + +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. - - + - - - - - - + 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); +nm_setting_clear_secrets_with_flags () +void nm_setting_clear_secrets_with_flags (NMSetting *setting, + NMSettingClearSecretsWithFlagsFn func, + gpointer user_data); -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. +Clears and frees secrets determined by func. - - - - - - - + - - + + setting : the NMSetting to verify all_settings : a GSList of all settings -in the connection from which setting came. [element-type NMSetting] + the NMSetting error : location to store error, or NULL + func : function to be called to determine whether a +specific secret should be cleared or not. [scope call] Returns : -TRUE if the setting is valid, FALSE if it is not user_data : caller-supplied data passed to func + @@ -737,39 +627,6 @@ for a description of each flag's behavior. -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, @@ -806,18 +663,41 @@ one or more 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] - +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 + + + +

`setting` :	the NMSetting to verify
`all_settings` :	a GSList of all settings -in the connection from which `setting` came. [element-type NMSetting] +	the NMSetting
`error` :	location to store error, or `NULL` +	`func` :	function to be called to determine whether a +specific secret should be cleared or not. [scope call]
Returns :	-`TRUE` if the setting is valid, `FALSE` if it is not	`user_data` :	caller-supplied data passed to `func` +

`func` :	function to be called to determine whether a -specific secret should be cleared or not. [scope call] -	`secret_name` :	the secret key name to get flags for
`user_data` :	caller-supplied data passed to `func` +	`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

`setting` :	the NMSetting -
`secrets` :	a GHashTable mapping -string to GValue of setting property names and secrets. [element-type utf8 GObject.Value] -	`setting_type` :	the NMSetting type which the hash contains properties for
`error` :	location to store error, or `NULL` +	`hash` :	the GHashTable containing a +string to GValue mapping of properties that apply to the setting. [element-type utf8 GObject.Value]
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	a new NMSetting object populated with the properties from the +hash table, or NULL on failure

`secret_name` :	the secret key name to set flags for	`secrets` :	a GHashTable mapping +string to GValue of setting property names and secrets. [element-type utf8 GObject.Value] +
`flags` :	the NMSettingSecretFlags for the secret	`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

`setting` :	the NMSetting to verify
`all_settings` :	a GSList of all settings +in the connection from which `setting` came. [element-type NMSetting] +
`error` :
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	+`TRUE` if the setting is valid, `FALSE` if it is not

`setting` :	The setting for which properties are being iterated, given to -`nm_setting_enumerate_values()` +	`NM_SETTING_ERROR_UNKNOWN`	unknown or unclassified error
`key` :	The value/property name
`value` :	The property's value	`NM_SETTING_ERROR_PROPERTY_NOT_FOUND`	a property required by the operation + was not found; for example, an attempt to update an invalid secret +
`flags` :	The property's flags, like `NM_SETTING_PARAM_SECRET` +	`NM_SETTING_ERROR_PROPERTY_NOT_SECRET`	an operation which requires a secret + was attempted on a non-secret property
`user_data` :	User data passed to `nm_setting_enumerate_values()` +	`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

`setting` :	the NMSetting +	`NM_SETTING_SECRET_FLAG_NONE`	the system is responsible for providing and +storing this secret (default)
`flags` :	hash flags, e.g. `NM_SETTING_HASH_FLAG_ALL` +	`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
Returns :	a new GHashTable -describing the setting's properties. [transfer full][element-type utf8 GObject.Value] +	`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

`setting` :	the NMSetting to duplicate
Returns :	a new NMSetting containing the same properties and values as the -source NMSetting. [transfer full] -

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

Object Hierarchy

Properties

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

NMSetting

NM_SETTING_NAME

NMSettingClass

enum NMSettingSecretFlags

NMSettingClearSecretsWithFlagsFn ()

NMSetting

enum NMSettingDiffResult

NMSettingClearSecretsWithFlagsFn ()

NMSettingClass

enum NMSettingError

NMSettingValueIterFn ()

nm_setting_get_type ()

enum NMSettingHashFlags

nm_setting_to_hash ()

enum NMSettingSecretFlags

nm_setting_new_from_hash ()

NMSettingValueIterFn ()

nm_setting_duplicate ()

NM_SETTING_NAME

nm_setting_get_name ()

NM_SETTING_PARAM_FUZZY_IGNORE

NM_SETTING_PARAM_REQUIRED

NM_SETTING_PARAM_SECRET

NM_SETTING_PARAM_SERIALIZE

nm_setting_clear_secrets ()

nm_setting_verify ()

nm_setting_clear_secrets_with_flags ()

enum NMSettingDiffResult

nm_setting_diff ()

nm_setting_duplicate ()

nm_setting_to_string ()

nm_setting_error_quark ()

nm_setting_clear_secrets ()

nm_setting_get_name ()

nm_setting_clear_secrets_with_flags ()

nm_setting_get_secret_flags ()

nm_setting_update_secrets ()

nm_setting_new_from_hash ()

nm_setting_get_secret_flags ()

nm_setting_set_secret_flags ()

nm_setting_set_secret_flags ()

nm_setting_to_hash ()

nm_setting_to_string ()

nm_setting_update_secrets ()

nm_setting_verify ()