libnm-util Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
Synopsis
#include <nm-setting.h> enum NMSettingError; #define NM_TYPE_SETTING_ERROR #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 NMSetting; NMSettingClass; void (*NMSettingValueIterFn) (NMSetting *setting
,const char *key
,const GValue *value
,GParamFlags flags
,gpointer user_data
); GType nm_setting_get_type (void
); GHashTable * nm_setting_to_hash (NMSetting *setting
); 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
); enum NMSettingCompareFlags; 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
); GPtrArray * nm_setting_need_secrets (NMSetting *setting
); gboolean nm_setting_update_secrets (NMSetting *setting
,GHashTable *secrets
,GError **error
);
Object Hierarchy
GObject +----NMSetting +----NMSetting8021x +----NMSettingBluetooth +----NMSettingCdma +----NMSettingConnection +----NMSettingGsm +----NMSettingIP4Config +----NMSettingIP6Config +----NMSettingOlpcMesh +----NMSettingPPP +----NMSettingPPPOE +----NMSettingSerial +----NMSettingVPN +----NMSettingWired +----NMSettingWireless +----NMSettingWirelessSecurity
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.
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.
unknown or unclassified error | |
a property required by the operation was not found; for example, an attempt to update an invalid secret | |
an operation which requires a secret was attempted on a non-secret property | |
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_quark ()
GQuark nm_setting_error_quark (void
);
Registers an error quark for NMSetting if necessary.
Returns : |
the error quark used for NMSetting errors. |
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); /* Padding for future expansion */ void (*_reserved1) (void); void (*_reserved2) (void); void (*_reserved3) (void); void (*_reserved4) (void); } NMSettingClass;
NMSettingValueIterFn ()
void (*NMSettingValueIterFn) (NMSetting *setting
,const char *key
,const GValue *value
,GParamFlags flags
,gpointer user_data
);
|
The setting for which properties are being iterated, given to
nm_setting_enumerate_values()
|
|
The value/property name |
|
The property's value |
|
The property's flags, like NM_SETTING_PARAM_SECRET
|
|
User data passed to nm_setting_enumerate_values()
|
nm_setting_to_hash ()
GHashTable * nm_setting_to_hash (NMSetting *setting
);
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:GValue.
|
the NMSetting |
Returns : |
a new GHashTable 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.
|
the NMSetting type which the hash contains properties for |
|
the GHashTable containing a string:GValue mapping of properties that apply to the setting |
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.
nm_setting_get_name ()
const char * nm_setting_get_name (NMSetting *setting
);
Returns the type name of the NMSetting object
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.
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 } NMSettingCompareFlags;
These flags modify the comparison behavior when comparing two settings or two connections.
match all properties exactly | |
match only important attributes, like SSID, type, security settings, etc. Does not match, for example, connection ID or UUID. | |
ignore the connection's ID | |
ignore secrets |
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.
|
a NMSetting |
|
a second NMSetting to compare with the first |
|
compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT
|
Returns : |
TRUE if the comparison succeeds, FALSE if it does not
|
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 ()
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.
|
a NMSetting |
|
a second NMSetting to compare with the first |
|
compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT
|
|
this parameter is used internally by libnm-util and should
be set to FALSE . If TRUE inverts the meaning of the NMSettingDiffResult.
|
|
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. |
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.
|
the NMSetting |
|
user-supplied function called for each property of the setting |
|
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.
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.
|
the NMSetting |
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.
|
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 the each array element with g_free() , as well as the array
itself with g_ptr_array_free()
|
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).
|
the NMSetting |
|
a GHashTable mapping string:GValue of setting property names and secrets |
|
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
|
Property Details
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