NMSetting

@@ -39,12 +39,12 @@

Synopsis

+ #include <nm-setting.h>
 
-enum                NMSettingError;
+enum                NMSettingError;
 #define             NM_TYPE_SETTING_ERROR
 #define             NM_SETTING_ERROR
 GQuark              nm_setting_error_quark              (void);
@@ -53,6 +53,7 @@ enum                NM_SETTING_PARAM_SECRET
 #define             NM_SETTING_PARAM_FUZZY_IGNORE
 #define             NM_SETTING_NAME
+enum                NMSettingSecretFlags;
                     NMSetting;
                     NMSettingClass;
 void                (*NMSettingValueIterFn)             (NMSetting *setting,
@@ -61,7 +62,9 @@ enum                GParamFlags flags,
                                                          gpointer user_data);
 GType               nm_setting_get_type                 (void);
-GHashTable *        nm_setting_to_hash                  (NMSetting *setting);
+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);
@@ -88,10 +91,22 @@ enum                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);

Object Hierarchy

+  GEnum
+   +----NMSettingError
+

   GObject
    +----NMSetting
@@ -107,31 +122,32 @@ enum                NMSettingPPPOE
          +----NMSettingSerial
          +----NMSettingVPN
+         +----NMSettingWimax
          +----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 +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
 {
@@ -175,7 +191,7 @@ Describes errors that may result from operations involving a

NM_TYPE_SETTING_ERROR

#define NM_TYPE_SETTING_ERROR (nm_setting_error_get_type ())

@@ -183,7 +199,7 @@ Describes errors that may result from operations involving a

NM_SETTING_ERROR

#define NM_SETTING_ERROR nm_setting_error_quark ()

@@ -191,7 +207,7 @@ Describes errors that may result from operations involving a

nm_setting_error_quark ()

GQuark              nm_setting_error_quark              (void);

@@ -201,13 +217,12 @@ Registers an error quark for

Returns :

- the error quark used for NMSetting errors. - +the error quark used for NMSetting errors.

NM_SETTING_PARAM_SERIALIZE

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

@@ -215,7 +230,7 @@ Registers an error quark for +

NM_SETTING_PARAM_REQUIRED

#define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))

@@ -223,7 +238,7 @@ Registers an error quark for +

NM_SETTING_PARAM_SECRET

#define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))

@@ -231,7 +246,7 @@ Registers an error quark for +

NM_SETTING_PARAM_FUZZY_IGNORE

#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))

@@ -239,7 +254,7 @@ Registers an error quark for +

NM_SETTING_NAME

#define NM_SETTING_NAME "name"

@@ -247,7 +262,57 @@ Registers an error quark for +

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 +

NMSetting

typedef struct _NMSetting NMSetting;

@@ -256,7 +321,7 @@ It should only be accessed through the functions described below.

NMSettingClass

typedef struct {
 	GObjectClass parent;
@@ -273,6 +338,18 @@ It should only be accessed through the functions described below.
 	                                  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);
+
 	/* Padding for future expansion */
 	void (*_reserved1) (void);
 	void (*_reserved2) (void);
@@ -284,7 +361,7 @@ It should only be accessed through the functions described below.

NMSettingValueIterFn ()

void                (*NMSettingValueIterFn)             (NMSetting *setting,
                                                          const char *key,
@@ -293,56 +370,53 @@ It should only be accessed through the functions described below.
                                                          gpointer user_data);

nm_setting_get_type ()

GType               nm_setting_get_type                 (void);

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

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

`setting` :	+	`NM_SETTING_HASH_FLAG_ALL`	hash all properties (including secrets)
`key` :	+	`NM_SETTING_HASH_FLAG_NO_SECRETS`	do not include secrets
`value` :	-
`flags` :	-
`user_data` :	+	`NM_SETTING_HASH_FLAG_ONLY_SECRETS`	only hash secrets

nm_setting_get_type ()

GType               nm_setting_get_type                 (void);

-- - - - -

Returns :

nm_setting_to_hash ()

GHashTable *        nm_setting_to_hash                  (NMSetting *setting);

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 @@ -357,15 +431,20 @@ D-Bus or serializing. The mapping is string:GValue. +

flags :

+hash flags, e.g. NM_SETTING_HASH_FLAG_ALL + + +

Returns :

- a new GHashTable describing the setting's properties +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);

@@ -382,26 +461,23 @@ property names and value types.

setting_type :

-the NMSetting type which the hash contains properties for - +the NMSetting type which the hash contains properties for

hash :

the GHashTable containing a string:GValue mapping of properties -that apply to the setting - +that apply to the setting

Returns :

- a new NMSetting object populated with the properties from the -hash table, or NULL on failure - +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);

@@ -412,20 +488,19 @@ Duplicates a

setting :

-the NMSetting to duplicate - +the NMSetting to duplicate

Returns :

- a new NMSetting containing the same properties and values as the -source NMSetting +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);

@@ -441,15 +516,14 @@ Returns the type name of the Returns :

- a string containing the type name of the NMSetting object, -like 'ppp' or 'wireless' or 'wired'. - +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,
@@ -465,14 +539,12 @@ failed validation, and in what way that property failed validation.
 
 
 setting :
-the NMSetting to verify
-
+the NMSetting to verify
 
 
 all_settings :
 a GSList of all settings in the connection from which setting
-came
-
+came
 
 
 error :
@@ -481,14 +553,14 @@ came
 
 
 Returns :
- TRUE if the setting is valid, FALSE if it is not
-
+
+TRUE if the setting is valid, FALSE if it is not

enum NMSettingCompareFlags

typedef enum {
 	NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
@@ -530,7 +602,7 @@ two connections.

nm_setting_compare ()

gboolean            nm_setting_compare                  (NMSetting *a,
                                                          NMSetting *b,
@@ -550,8 +622,7 @@ for a description of each flag's behavior.
 
 
 b :
-a second NMSetting to compare with the first
-
+a second NMSetting to compare with the first
 
 
 flags :
@@ -560,14 +631,14 @@ for a description of each flag's behavior.
 
 
 Returns :
- TRUE if the comparison succeeds, FALSE if it does not
-
+
+TRUE if the comparison succeeds, FALSE if it does not

enum NMSettingDiffResult

typedef enum {
 	NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
@@ -600,7 +671,7 @@ These values indicate the result of a setting difference operation.

nm_setting_diff ()

gboolean            nm_setting_diff                     (NMSetting *a,
                                                          NMSetting *b,
@@ -624,8 +695,7 @@ one or more b :
-a second NMSetting to compare with the first
-
+a second NMSetting to compare with the first
 
 
 flags :
@@ -635,12 +705,11 @@ one or more invert_results :
 this parameter is used internally by libnm-util and should
-be set to FALSE.  If TRUE inverts the meaning of the NMSettingDiffResult.
-
+be set to FALSE.  If TRUE inverts the meaning of the NMSettingDiffResult.
 
 
 results :
- if the settings differ, on return a
+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, a new one is created. [element-type utf8 guint32]
@@ -648,14 +717,14 @@ in is unmodified.  If no hash table is passed in, a new one is created. 
 
 Returns :
- TRUE if the settings contain the same values, FALSE if they do not
-
+
+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,
@@ -674,19 +743,18 @@ user function for each property.
 
 
 func :
-user-supplied function called for each property of the setting
+user-supplied function called for each property of the setting. [scope call]
 
 
 
 user_data :
-user data passed to func at each invocation
-
+user data passed to func at each invocation

nm_setting_to_string ()

char *              nm_setting_to_string                (NMSetting *setting);

@@ -704,7 +772,7 @@ output format is not guaranteed to be stable and may change at any time.

Returns :

- an allocated string containing a textual representation of the +an allocated string containing a textual representation of the setting's properties and values (including secrets!), which the caller should free with g_free() @@ -713,7 +781,7 @@ free with +

nm_setting_clear_secrets ()

void                nm_setting_clear_secrets            (NMSetting *setting);

@@ -731,7 +799,7 @@ leakage of information.

nm_setting_need_secrets ()

GPtrArray *         nm_setting_need_secrets             (NMSetting *setting);

@@ -750,17 +818,17 @@ is no way to conclusively determine exactly which secrets are needed.

Returns :

- a GPtrArray containing the property names of secrets of the +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() +itself with g_ptr_array_free(). [transfer full][element-type utf8]

nm_setting_update_secrets ()

gboolean            nm_setting_update_secrets           (NMSetting *setting,
                                                          GHashTable *secrets,
@@ -780,27 +848,106 @@ setting (deserialized from D-Bus for example).
 
 secrets :
 a GHashTable mapping string:GValue of setting property names and
-secrets
+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
+
+
+

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` if the secrets were successfully updated and the connection -is valid, `FALSE` on failure or if the setting was never added to the connection +	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

Property Details

The `"name"` property

  "name"                     gchar*                : Read / Write

@@ -814,6 +961,6 @@ example 'ppp' or 'wireless' or 'wired'.

+ Generated by GTK-Doc V1.17

\ No newline at end of file -- cgit 1.3.0-6-gf8a5

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

enum NMSettingSecretFlags

NMSetting

NMSettingClass

NMSettingValueIterFn ()

nm_setting_get_type ()

enum NMSettingHashFlags

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

enum NMSettingDiffResult

nm_setting_diff ()

nm_setting_enumerate_values ()

nm_setting_to_string ()

nm_setting_clear_secrets ()

nm_setting_need_secrets ()

nm_setting_update_secrets ()

nm_setting_get_secret_flags ()

nm_setting_set_secret_flags ()

Property Details

The "name" property

The `"name"` property