From 33491bc4279481db8ae47213e34a6d695a0e8830 Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Sun, 6 Jul 2014 02:16:10 +0200 Subject: Imported Upstream version 0.9.10.0 --- docs/libnm-util/html/NMSetting.html | 1828 ++++++++++++++++------------------- 1 file changed, 830 insertions(+), 998 deletions(-) (limited to 'docs/libnm-util/html/NMSetting.html') diff --git a/docs/libnm-util/html/NMSetting.html b/docs/libnm-util/html/NMSetting.html index ae62da3e..d6e1af38 100644 --- a/docs/libnm-util/html/NMSetting.html +++ b/docs/libnm-util/html/NMSetting.html @@ -2,28 +2,34 @@ -libnm-util Reference Manual: NMSetting +NMSetting - + - - - - - - - + + + + + + + + + +
@@ -31,305 +37,219 @@

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

Functions

-
+

Object Hierarchy

+
+  GEnum
+   +----NMSettingError
+
+
+  GEnum
+   +----NMSettingSecretFlags
+
+
+  GEnum
+   +----NMSettingCompareFlags
+
+
+  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
+
+
+  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 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. +

+
+
+

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

+
--++ - - - - - - - - - - - - - - - - - - - - - - + - - + - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
-GQuark - -nm_setting_error_quark () -
#defineNM_SETTING_PARAM_SERIALIZE
#defineNM_SETTING_PARAM_REQUIRED
#defineNM_SETTING_PARAM_SECRET
#defineNM_SETTING_PARAM_FUZZY_IGNORE
-gboolean - -(*NMSettingClearSecretsWithFlagsFn) () +

NM_SETTING_ERROR_UNKNOWN

unknown or unclassified error
-void - -(*NMSettingValueIterFn) () +

NM_SETTING_ERROR_PROPERTY_NOT_FOUND

a property required by the operation + was not found; for example, an attempt to update an invalid secret
-GHashTable * - -nm_setting_to_hash () +

NM_SETTING_ERROR_PROPERTY_NOT_SECRET

an operation which requires a secret + was attempted on a non-secret property
-NMSetting * - -nm_setting_new_from_hash () -
-NMSetting * - -nm_setting_duplicate () -
const char * - -nm_setting_get_name () -
-gboolean - -nm_setting_verify () -
-gboolean - -nm_setting_compare () -
-gboolean - -nm_setting_diff () -
-void - -nm_setting_enumerate_values () -
-char * - -nm_setting_to_string () -
-void - -nm_setting_clear_secrets () -
-void - -nm_setting_clear_secrets_with_flags () -
-GPtrArray * - -nm_setting_need_secrets () -
-gboolean - -nm_setting_update_secrets () -
-gboolean - -nm_setting_get_secret_flags () -
-gboolean - -nm_setting_set_secret_flags () -
const char * - -nm_setting_get_virtual_iface_name () +

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

Properties

-
+
+
+

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

+
---++ - - - + +
-gchar *nameRead / Write

Returns :

the error quark used for NMSetting errors.
-
-

Types and Values

-
---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
enumNMSettingError
#defineNM_SETTING_ERROR
#defineNM_SETTING_NAME
enumNMSettingSecretFlags
enumNMSettingCompareFlags
 NMSetting
enumNMSettingHashFlags
enumNMSettingDiffResult
-
-
-

Object Hierarchy

-
    GEnum
-    ├── NMSettingCompareFlags
-    ├── NMSettingDiffResult
-    ├── NMSettingError
-    ├── NMSettingHashFlags
-    ╰── NMSettingSecretFlags
-    GObject
-    ╰── NMSetting
-        ├── NMSetting8021x
-        ├── NMSettingAdsl
-        ├── NMSettingBluetooth
-        ├── NMSettingBond
-        ├── NMSettingBridge
-        ├── NMSettingBridgePort
-        ├── NMSettingConnection
-        ├── NMSettingInfiniband
-        ├── NMSettingIP4Config
-        ├── NMSettingVlan
-        ├── NMSettingIP6Config
-        ├── NMSettingPPP
-        ├── NMSettingPPPOE
-        ├── NMSettingSerial
-        ├── 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 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.

-
-
-

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.

-

-
-

NM_SETTING_PARAM_SERIALIZE

@@ -364,1012 +284,924 @@ nm_setting_error_quark (void
-

NMSettingClearSecretsWithFlagsFn ()

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

Parameters

-
+

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

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

setting

The setting for which secrets are being iterated

 

NM_SETTING_SECRET_FLAG_NONE

the system is responsible for providing and +storing this secret (default) +

secret

The secret's name

 

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 +

flags

The secret's flags, eg NM_SETTING_SECRET_FLAG_AGENT_OWNED

 

NM_SETTING_SECRET_FLAG_NOT_SAVED

this secret should not be saved, but +should be requested from the user each time it is needed +

user_data

User data passed to nm_connection_clear_secrets_with_flags()

 

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

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

-
+

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
+
+	/* 0x80000000 is used for a private flag */
+} NMSettingCompareFlags;
+
+

+These flags modify the comparison behavior when comparing two settings or +two connections. +

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

setting

The setting for which properties are being iterated, given to -nm_setting_enumerate_values()

 

NM_SETTING_COMPARE_FLAG_EXACT

match all properties exactly +

key

The value/property name

 

NM_SETTING_COMPARE_FLAG_FUZZY

match only important attributes, like SSID, + type, security settings, etc. Does not match, for example, connection ID + or UUID. +

value

The property's value

 

NM_SETTING_COMPARE_FLAG_IGNORE_ID

ignore the connection's ID +

flags

The property's flags, like NM_SETTING_PARAM_SECRET

 

NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS

ignore all secrets +

user_data

User data passed to nm_setting_enumerate_values()

 

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

-

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

-
+

NMSettingClearSecretsWithFlagsFn ()

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

setting

the NMSetting

 

setting :

The setting for which secrets are being iterated

flags

hash flags, e.g. NM_SETTING_HASH_FLAG_ALL

 

secret :

The secret's name
-
-
-

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

 

flags :

The secret's flags, eg NM_SETTING_SECRET_FLAG_AGENT_OWNED +

hash

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

[element-type utf8 GObject.Value]

user_data :

User data passed to nm_connection_clear_secrets_with_flags() +

Returns :

 +TRUE to clear the secret, FALSE to not clear the secret
-
-

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

-

-
+

NMSettingClass

+
typedef struct {
+	GObjectClass parent;
+
+	/* Virtual functions */
+	gboolean    (*verify)            (NMSetting  *setting,
+	                                  GSList     *all_settings,
+	                                  GError     **error);
+
+	GPtrArray  *(*need_secrets)      (NMSetting  *setting);
+
+	int         (*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);
+
+	gboolean    (*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;
+
+

+

-

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

-
+

NMSettingValueIterFn ()

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

setting

the NMSetting to verify

 

setting :

The setting for which properties are being iterated, given to +nm_setting_enumerate_values() +

key :

The value/property name

all_settings

a GSList of all settings -in the connection from which setting -came.

[element-type NMSetting]

value :

The property's value

error

location to store error, or NULL

 

flags :

The property's flags, like NM_SETTING_PARAM_SECRET +

user_data :

User data passed to nm_setting_enumerate_values() +
-
-

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

-
+

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

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

a

a NMSetting

 

NM_SETTING_HASH_FLAG_ALL

hash all properties (including secrets) +

b

a second NMSetting to compare with the first

 

NM_SETTING_HASH_FLAG_NO_SECRETS

do not include secrets +

flags

compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT

 

NM_SETTING_HASH_FLAG_ONLY_SECRETS

only hash secrets +
-
-

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

-
+

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

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

a

a NMSetting

 

b

a second NMSetting to compare with the first

 

flags

compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT

 

setting :

the NMSetting +

invert_results

this parameter is used internally by libnm-util and should -be set to FALSE. If TRUE inverts the meaning of the NMSettingDiffResult.

 

flags :

hash flags, e.g. NM_SETTING_HASH_FLAG_ALL +

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 :

a new GHashTable +describing the setting's properties. [transfer full][element-type utf8 GObject.Value] +
-
-

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

-
+

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

the NMSetting

 

setting_type :

the NMSetting type which the hash contains properties for

func

user-supplied function called for each property of the setting.

[scope call]

hash :

the GHashTable containing a +string to GValue mapping of properties that apply to the setting. [element-type utf8 GObject.Value] +

user_data

user data passed to func -at each invocation

 

Returns :

a new NMSetting object populated with the properties from the +hash table, or NULL on failure
-
-

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

-
+

nm_setting_duplicate ()

+
NMSetting *         nm_setting_duplicate                (NMSetting *setting);
+

+Duplicates a NMSetting. +

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

setting

the NMSetting

 

setting :

the NMSetting to duplicate

Returns :

a new NMSetting containing the same properties and values as the +source NMSetting. [transfer full] +
-
-

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

-
+

nm_setting_get_name ()

+
const char *        nm_setting_get_name                 (NMSetting *setting);
+

+Returns the type name of the NMSetting object +

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

setting

the NMSetting

 

setting :

the NMSetting +

Returns :

a string containing the type name of the NMSetting object, +like 'ppp' or 'wireless' or 'wired'.
-
-

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

-
+

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

 

setting :

the NMSetting to verify

all_settings :

a GSList of all settings +in the connection from which setting came. [element-type NMSetting] +

func

function to be called to determine whether a -specific secret should be cleared or not.

[scope call]

error :

location to store error, or NULL +

user_data

caller-supplied data passed to func -

 

Returns :

 +TRUE if the setting is valid, FALSE if it is not
-
-

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

-
+

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

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

setting

the NMSetting

 

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

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

-
+

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

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

setting

the NMSetting

 

NM_SETTING_DIFF_RESULT_UNKNOWN

unknown result +

secrets

a GHashTable mapping -string to GValue of setting property names and secrets.

[element-type utf8 GObject.Value]

NM_SETTING_DIFF_RESULT_IN_A

the property is present in setting A +

error

location to store error, or NULL

 

NM_SETTING_DIFF_RESULT_IN_B

the property is present in setting B +
-
-

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

-
+

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

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

setting

the NMSetting

 

a :

a NMSetting +

secret_name

the secret key name to get flags for

 

b :

a second NMSetting to compare with the first

out_flags

on success, the NMSettingSecretFlags for the secret

 

flags :

compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT +

error

location to store error, or NULL

 

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

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.

-
-

Parameters

-
+

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

 

setting :

the NMSetting +

func :

user-supplied function called for each property of the setting. [scope call] +

secret_name

the secret key name to set flags for

 

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

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

flags

the NMSettingSecretFlags for the secret

 

setting :

the NMSetting +

error

location to store error, or NULL

 

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

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

-
+

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

 

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

 -

unknown or unclassified error

+

setting :

the NMSetting  

NM_SETTING_ERROR_PROPERTY_NOT_FOUND

 -

a property required by the operation - was not found; for example, an attempt to update an invalid secret

+

func :

function to be called to determine whether a +specific secret should be cleared or not. [scope call]  

NM_SETTING_ERROR_PROPERTY_NOT_SECRET

 -

an operation which requires a secret - was attempted on a non-secret property

+

user_data :

caller-supplied data passed to func  

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

-
#define NM_SETTING_NAME "name"
-
+

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

-
-
-
-

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)

+

setting :

the NMSetting  

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

+

secrets :

a GHashTable mapping +string to GValue of setting property names and secrets. [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

+

error :

location to store error, or NULL  

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

-		 

Returns :

 +TRUE if the secrets were successfully updated, FALSE on failure to +update one or more of the secrets.
-
-

enum NMSettingCompareFlags

-

These flags modify the comparison behavior when comparing two settings or -two connections.

-
-

Members

-
+

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_COMPARE_FLAG_EXACT

 -

match all properties exactly

+

setting :

the NMSetting  

NM_SETTING_COMPARE_FLAG_FUZZY

 -

match only important attributes, like SSID, - type, security settings, etc. Does not match, for example, connection ID - or UUID.

-		 

secret_name :

the secret key name to get flags for

NM_SETTING_COMPARE_FLAG_IGNORE_ID

 -

ignore the connection's ID

-		 

out_flags :

on success, the NMSettingSecretFlags for the secret

NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS

 -

ignore all secrets

+

error :

location to store error, or NULL  

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

-		 

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

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

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

NM_SETTING_HASH_FLAG_ALL

 -

hash all properties (including secrets)

+

setting :

the NMSetting  

NM_SETTING_HASH_FLAG_NO_SECRETS

 -

do not include secrets

-		 

secret_name :

the secret key name to set flags for

NM_SETTING_HASH_FLAG_ONLY_SECRETS

 -

only hash secrets

+

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

enum NMSettingDiffResult

-

These values indicate the result of a setting difference operation.

-
-

Members

-
+

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

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

NM_SETTING_DIFF_RESULT_UNKNOWN

 -

unknown result

+

setting :

the NMSetting  

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

-		 

Returns :

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

Property Details

-

The “name” property

-
  “name”                     gchar *
-

The setting's name, which uniquely identifies the setting within the +

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

-

Flags: Read / Write

+example "ppp" or "wireless" or "wired". +

Default value: NULL

- Generated by GTK-Doc V1.20
+ Generated by GTK-Doc V1.19
\ No newline at end of file -- cgit 1.3.0-6-gf8a5