2020-09-29 16:42:22 +02:00
|
|
|
/* SPDX-License-Identifier: LGPL-2.1+ */
|
2014-07-24 08:53:33 -04:00
|
|
|
/*
|
2019-10-01 09:20:35 +02:00
|
|
|
* Copyright (C) 2007 - 2011 Red Hat, Inc.
|
|
|
|
|
* Copyright (C) 2007 - 2008 Novell, Inc.
|
2014-07-24 08:53:33 -04:00
|
|
|
*/
|
|
|
|
|
|
all: fix up multiple-include-guard defines
Previously, src/nm-ip4-config.h, libnm/nm-ip4-config.h, and
libnm-glib/nm-ip4-config.h all used "NM_IP4_CONFIG_H" as an include
guard, which meant that nm-test-utils.h could not tell which of them
was being included (and so, eg, if you tried to include
nm-ip4-config.h in a libnm test, it would fail to compile because
nm-test-utils.h was referring to symbols in src/nm-ip4-config.h).
Fix this by changing the include guards in the non-API-stable parts of
the tree:
- libnm-glib/nm-ip4-config.h remains NM_IP4_CONFIG_H
- libnm/nm-ip4-config.h now uses __NM_IP4_CONFIG_H__
- src/nm-ip4-config.h now uses __NETWORKMANAGER_IP4_CONFIG_H__
And likewise for all other headers.
The two non-"nm"-prefixed headers, libnm/NetworkManager.h and
src/NetworkManagerUtils.h are now __NETWORKMANAGER_H__ and
__NETWORKMANAGER_UTILS_H__ respectively, which, while not entirely
consistent with the general scheme, do still mostly make sense in
isolation.
2014-08-13 14:10:11 -04:00
|
|
|
#ifndef __NM_SETTING_H__
|
|
|
|
|
#define __NM_SETTING_H__
|
2014-07-24 08:53:33 -04:00
|
|
|
|
2014-07-06 16:53:02 -04:00
|
|
|
#if !defined(__NETWORKMANAGER_H_INSIDE__) && !defined(NETWORKMANAGER_COMPILATION)
|
|
|
|
|
#error "Only <NetworkManager.h> can be included directly."
|
|
|
|
|
#endif
|
|
|
|
|
|
2017-03-09 13:02:20 +01:00
|
|
|
#include "nm-core-types.h"
|
2014-07-24 08:53:33 -04:00
|
|
|
|
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
|
|
|
|
|
|
#define NM_TYPE_SETTING (nm_setting_get_type())
|
|
|
|
|
#define NM_SETTING(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), NM_TYPE_SETTING, NMSetting))
|
|
|
|
|
#define NM_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), NM_TYPE_SETTING, NMSettingClass))
|
|
|
|
|
#define NM_IS_SETTING(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), NM_TYPE_SETTING))
|
|
|
|
|
#define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), NM_TYPE_SETTING))
|
|
|
|
|
#define NM_SETTING_GET_CLASS(obj) \
|
|
|
|
|
(G_TYPE_INSTANCE_GET_CLASS((obj), NM_TYPE_SETTING, NMSettingClass))
|
|
|
|
|
|
|
|
|
|
/* The property of the #NMSetting is required for the setting to be valid */
|
|
|
|
|
#define NM_SETTING_PARAM_REQUIRED (1 << (1 + G_PARAM_USER_SHIFT))
|
|
|
|
|
|
|
|
|
|
/* The property of the #NMSetting is a secret */
|
|
|
|
|
#define NM_SETTING_PARAM_SECRET (1 << (2 + G_PARAM_USER_SHIFT))
|
|
|
|
|
|
|
|
|
|
/* The property of the #NMSetting should be ignored during comparisons that
|
|
|
|
|
* use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
|
|
|
|
|
*/
|
|
|
|
|
#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
|
|
|
|
|
|
|
|
|
|
/* Note: all non-glib GParamFlags bits are reserved by NetworkManager */
|
|
|
|
|
|
|
|
|
|
#define NM_SETTING_NAME "name"
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* NMSettingSecretFlags:
|
|
|
|
|
* @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
|
2018-09-15 07:20:54 -04:00
|
|
|
* providers don't require all secrets) this flag indicates that the specific
|
2014-07-24 08:53:33 -04:00
|
|
|
* secret is not required
|
|
|
|
|
*
|
|
|
|
|
* 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.
|
|
|
|
|
*
|
|
|
|
|
**/
|
2014-06-26 16:47:46 -04:00
|
|
|
typedef enum { /*< flags >*/
|
2014-07-24 08:53:33 -04:00
|
|
|
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
|
|
|
|
|
|
2014-08-11 18:21:53 +02:00
|
|
|
/* NOTE: if adding flags, update nm-core-internal.h as well */
|
2014-07-24 08:53:33 -04:00
|
|
|
} NMSettingSecretFlags;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* NMSettingCompareFlags:
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
|
|
|
|
|
* type, security settings, etc. Does not match, for example, connection ID
|
|
|
|
|
* or UUID.
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore all secrets
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_IGNORE_AGENT_OWNED_SECRETS: ignore secrets for which
|
2014-11-18 14:06:21 +01:00
|
|
|
* 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)
|
2014-07-24 08:53:33 -04:00
|
|
|
* @NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS: ignore secrets for which
|
2014-11-18 14:06:21 +01:00
|
|
|
* 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)
|
2014-02-26 11:26:25 +01:00
|
|
|
* @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT: if this flag is set,
|
2014-11-18 14:06:21 +01:00
|
|
|
* nm_setting_diff() and nm_connection_diff() will also include properties that
|
|
|
|
|
* are set to their default value. See also @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT.
|
2014-02-26 11:26:25 +01:00
|
|
|
* @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT: if this flag is set,
|
2014-11-18 14:06:21 +01:00
|
|
|
* nm_setting_diff() and nm_connection_diff() will not include properties that
|
|
|
|
|
* are set to their default value. This is the opposite of
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT. If both flags are set together,
|
|
|
|
|
* @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT wins. If both flags are unset,
|
|
|
|
|
* this means to exclude default properties if there is a setting to compare,
|
|
|
|
|
* but include all properties, if the setting 'b' is missing. This is the legacy
|
|
|
|
|
* behaviour of libnm-util, where nm_setting_diff() behaved differently depending
|
|
|
|
|
* on whether the setting 'b' was available. If @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT
|
|
|
|
|
* is set, nm_setting_diff() will also set the flags @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT
|
|
|
|
|
* and @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT, if the values are default values.
|
2014-11-18 14:20:12 +01:00
|
|
|
* @NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP: ignore the connection's timestamp
|
2014-07-24 08:53:33 -04:00
|
|
|
*
|
|
|
|
|
* These flags modify the comparison behavior when comparing two settings or
|
|
|
|
|
* two connections.
|
|
|
|
|
*
|
|
|
|
|
**/
|
|
|
|
|
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,
|
2014-02-26 11:26:25 +01:00
|
|
|
NM_SETTING_COMPARE_FLAG_IGNORE_NOT_SAVED_SECRETS = 0x00000010,
|
|
|
|
|
NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT = 0x00000020,
|
|
|
|
|
NM_SETTING_COMPARE_FLAG_DIFF_RESULT_NO_DEFAULT = 0x00000040,
|
2014-11-18 14:20:12 +01:00
|
|
|
NM_SETTING_COMPARE_FLAG_IGNORE_TIMESTAMP = 0x00000080,
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2015-09-18 17:21:34 +02:00
|
|
|
/* Higher flags like 0x80000000 and 0x40000000 are used internally as private flags */
|
2014-07-24 08:53:33 -04:00
|
|
|
} NMSettingCompareFlags;
|
|
|
|
|
|
2015-10-06 17:42:15 -04:00
|
|
|
/**
|
|
|
|
|
* NMSettingMacRandomization:
|
|
|
|
|
* @NM_SETTING_MAC_RANDOMIZATION_DEFAULT: the default value, which unless
|
|
|
|
|
* overridden by user-controlled defaults configuration, is "never".
|
|
|
|
|
* @NM_SETTING_MAC_RANDOMIZATION_NEVER: the device's MAC address is always used.
|
|
|
|
|
* @NM_SETTING_MAC_RANDOMIZATION_ALWAYS: a random MAC address is used.
|
|
|
|
|
*
|
|
|
|
|
* Controls if and how the MAC address of a device is randomzied.
|
|
|
|
|
**/
|
|
|
|
|
typedef enum {
|
|
|
|
|
NM_SETTING_MAC_RANDOMIZATION_DEFAULT = 0,
|
|
|
|
|
NM_SETTING_MAC_RANDOMIZATION_NEVER,
|
|
|
|
|
NM_SETTING_MAC_RANDOMIZATION_ALWAYS,
|
|
|
|
|
} NMSettingMacRandomization;
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
/**
|
|
|
|
|
* NMSetting:
|
|
|
|
|
*
|
|
|
|
|
* The NMSetting struct contains only private data.
|
|
|
|
|
* It should only be accessed through the functions described below.
|
|
|
|
|
*/
|
2014-10-21 22:09:52 -04:00
|
|
|
struct _NMSetting {
|
2014-07-24 08:53:33 -04:00
|
|
|
GObject parent;
|
2014-10-21 22:09:52 -04:00
|
|
|
};
|
2014-07-24 08:53:33 -04:00
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* NMSettingClearSecretsWithFlagsFn:
|
|
|
|
|
* @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
|
|
|
|
|
* @user_data: User data passed to nm_connection_clear_secrets_with_flags()
|
|
|
|
|
*
|
|
|
|
|
* Returns: %TRUE to clear the secret, %FALSE to not clear the secret
|
|
|
|
|
*/
|
|
|
|
|
typedef gboolean (*NMSettingClearSecretsWithFlagsFn)(NMSetting * setting,
|
|
|
|
|
const char * secret,
|
|
|
|
|
NMSettingSecretFlags flags,
|
|
|
|
|
gpointer user_data);
|
|
|
|
|
|
libnm: use NMMetaSettingInfo for tracking setting priority
Previously, each (non abstract) NMSetting class had to register
its name and priority via _nm_register_setting().
Note, that libnm-core.la already links against "nm-meta-setting.c",
which also redundantly keeps track of the settings name and gtype
as well.
Re-use NMMetaSettingInfo also in libnm-core.la, to track this meta
data.
The goal is to get rid of private data structures that track
meta data about NMSetting classes. In this case, "registered_settings"
hash. Instead, we should have one place where all this meta data
is tracked. This was, it is also accessible as internal API,
which can be useful (for keyfile).
Note that NMSettingClass has some overlap with NMMetaSettingInfo.
One difference is, that NMMetaSettingInfo is const, while NMSettingClass
is only initialized during the class_init() method. Appart from that,
it's mostly a matter of taste, whether we attach meta data to
NMSettingClass, to NMMetaSettingInfo, or to a static-array indexed
by NMMetaSettingType.
Note, that previously, _nm_register_setting() was private API. That
means, no user could subclass a functioning NMSetting instance. The same
is still true: NMMetaSettingInfo is internal API and users cannot access
it to create their own NMSetting subclasses. But that is almost desired.
libnm is not designed, to be extensible via subclassing, nor is it
clear why that would be a useful thing to do. One day, we should remove
the NMSetting and NMSettingClass definitions from public headers. Their
only use is subclassing the types, which however does not work.
While libnm-core was linking already against nm-meta-setting.c,
nm_meta_setting_infos was unreferenced. So, this change increases
the binary size of libnm and NetworkManager (1032 bytes). Note however
that roughly the same information was previously allocated at runtime.
2018-07-27 14:08:14 +02:00
|
|
|
struct _NMMetaSettingInfo;
|
libnm: rework compare_property() implementation for NMSetting
NMSetting's compare_property() has and had two callers:
nm_setting_compare() and nm_setting_diff().
compare_property() accepts a NMSettingCompareFlags argument, but
at the same time, both callers have another complex (and
inconsistent!) set of pre-checks for shortcuting the call of
compare_property(): should_compare_prop().
Merge should_compare_prop() into compare_property(). This way,
nm_setting_compare() and nm_setting_diff() has less additional
code, and are simpler to follow. Especially nm_setting_compare()
is now trivial. And nm_setting_diff() is still complicated, but
not related to the question how the property compares or whether
it should be compared at all.
If you want to know whether it should be compared, all you need to do
now is follow NMSettingClass.compare_property().
This changes function pointer NMSettingClass.compare_property(),
which is public API. However, no user can actually use this (and shall
not!), because _nm_setting_class_commit_full() etc. is private API. A
user outside of libnm-core cannot create his/her own subclasses of
NMSetting, and never could in the past. So, this API/ABI change doesn't
matter.
2019-01-09 09:08:39 +01:00
|
|
|
struct _NMSettInfoSetting;
|
2019-01-21 08:10:14 +01:00
|
|
|
struct _NMSettInfoProperty;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* NMSettingValueIterFn:
|
|
|
|
|
* @setting: The setting for which properties are being iterated, given to
|
|
|
|
|
* nm_setting_enumerate_values()
|
|
|
|
|
* @key: The value/property name
|
|
|
|
|
* @value: The property's value
|
|
|
|
|
* @flags: The property's flags, like %NM_SETTING_PARAM_SECRET
|
|
|
|
|
* @user_data: User data passed to nm_setting_enumerate_values()
|
|
|
|
|
*/
|
|
|
|
|
typedef void (*NMSettingValueIterFn)(NMSetting * setting,
|
|
|
|
|
const char * key,
|
|
|
|
|
const GValue *value,
|
|
|
|
|
GParamFlags flags,
|
|
|
|
|
gpointer user_data);
|
libnm: use NMMetaSettingInfo for tracking setting priority
Previously, each (non abstract) NMSetting class had to register
its name and priority via _nm_register_setting().
Note, that libnm-core.la already links against "nm-meta-setting.c",
which also redundantly keeps track of the settings name and gtype
as well.
Re-use NMMetaSettingInfo also in libnm-core.la, to track this meta
data.
The goal is to get rid of private data structures that track
meta data about NMSetting classes. In this case, "registered_settings"
hash. Instead, we should have one place where all this meta data
is tracked. This was, it is also accessible as internal API,
which can be useful (for keyfile).
Note that NMSettingClass has some overlap with NMMetaSettingInfo.
One difference is, that NMMetaSettingInfo is const, while NMSettingClass
is only initialized during the class_init() method. Appart from that,
it's mostly a matter of taste, whether we attach meta data to
NMSettingClass, to NMMetaSettingInfo, or to a static-array indexed
by NMMetaSettingType.
Note, that previously, _nm_register_setting() was private API. That
means, no user could subclass a functioning NMSetting instance. The same
is still true: NMMetaSettingInfo is internal API and users cannot access
it to create their own NMSetting subclasses. But that is almost desired.
libnm is not designed, to be extensible via subclassing, nor is it
clear why that would be a useful thing to do. One day, we should remove
the NMSetting and NMSettingClass definitions from public headers. Their
only use is subclassing the types, which however does not work.
While libnm-core was linking already against nm-meta-setting.c,
nm_meta_setting_infos was unreferenced. So, this change increases
the binary size of libnm and NetworkManager (1032 bytes). Note however
that roughly the same information was previously allocated at runtime.
2018-07-27 14:08:14 +02:00
|
|
|
|
2019-01-31 09:38:58 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
typedef gboolean (*_NMConnectionForEachSecretFunc)(NMSettingSecretFlags flags, gpointer user_data);
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
typedef struct {
|
|
|
|
|
GObjectClass parent;
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
/* Virtual functions */
|
all: don't use gchar/gshort/gint/glong but C types
We commonly don't use the glib typedefs for char/short/int/long,
but their C types directly.
$ git grep '\<g\(char\|short\|int\|long\|float\|double\)\>' | wc -l
587
$ git grep '\<\(char\|short\|int\|long\|float\|double\)\>' | wc -l
21114
One could argue that using the glib typedefs is preferable in
public API (of our glib based libnm library) or where it clearly
is related to glib, like during
g_object_set (obj, PROPERTY, (gint) value, NULL);
However, that argument does not seem strong, because in practice we don't
follow that argument today, and seldomly use the glib typedefs.
Also, the style guide for this would be hard to formalize, because
"using them where clearly related to a glib" is a very loose suggestion.
Also note that glib typedefs will always just be typedefs of the
underlying C types. There is no danger of glib changing the meaning
of these typedefs (because that would be a major API break of glib).
A simple style guide is instead: don't use these typedefs.
No manual actions, I only ran the bash script:
FILES=($(git ls-files '*.[hc]'))
sed -i \
-e 's/\<g\(char\|short\|int\|long\|float\|double\)\>\( [^ ]\)/\1\2/g' \
-e 's/\<g\(char\|short\|int\|long\|float\|double\)\> /\1 /g' \
-e 's/\<g\(char\|short\|int\|long\|float\|double\)\>/\1/g' \
"${FILES[@]}"
2018-07-11 07:40:19 +02:00
|
|
|
int (*verify)(NMSetting *setting, NMConnection *connection, GError **error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2015-11-10 14:36:20 +01:00
|
|
|
gboolean (*verify_secrets)(NMSetting *setting, NMConnection *connection, GError **error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
GPtrArray *(*need_secrets)(NMSetting *setting);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
int (*update_one_secret)(NMSetting *setting, const char *key, GVariant *value, GError **error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
gboolean (*get_secret_flags)(NMSetting * setting,
|
|
|
|
|
const char * secret_name,
|
|
|
|
|
NMSettingSecretFlags *out_flags,
|
|
|
|
|
GError ** error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
gboolean (*set_secret_flags)(NMSetting * setting,
|
|
|
|
|
const char * secret_name,
|
|
|
|
|
NMSettingSecretFlags flags,
|
|
|
|
|
GError ** error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-01-13 21:23:02 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
gboolean (*clear_secrets)(const struct _NMSettInfoSetting *sett_info,
|
|
|
|
|
guint property_idx,
|
|
|
|
|
NMSetting * setting,
|
|
|
|
|
NMSettingClearSecretsWithFlagsFn func,
|
|
|
|
|
gpointer user_data);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
libnm: rework compare_property() implementation for NMSetting
NMSetting's compare_property() has and had two callers:
nm_setting_compare() and nm_setting_diff().
compare_property() accepts a NMSettingCompareFlags argument, but
at the same time, both callers have another complex (and
inconsistent!) set of pre-checks for shortcuting the call of
compare_property(): should_compare_prop().
Merge should_compare_prop() into compare_property(). This way,
nm_setting_compare() and nm_setting_diff() has less additional
code, and are simpler to follow. Especially nm_setting_compare()
is now trivial. And nm_setting_diff() is still complicated, but
not related to the question how the property compares or whether
it should be compared at all.
If you want to know whether it should be compared, all you need to do
now is follow NMSettingClass.compare_property().
This changes function pointer NMSettingClass.compare_property(),
which is public API. However, no user can actually use this (and shall
not!), because _nm_setting_class_commit_full() etc. is private API. A
user outside of libnm-core cannot create his/her own subclasses of
NMSetting, and never could in the past. So, this API/ABI change doesn't
matter.
2019-01-09 09:08:39 +01:00
|
|
|
/* compare_property() returns a ternary, where DEFAULT means that the property should not
|
|
|
|
|
* be compared due to the compare @flags. A TRUE/FALSE result means that the property is
|
|
|
|
|
* equal/not-equal.
|
|
|
|
|
*
|
|
|
|
|
* @other may be %NULL, in which case the function only determines whether
|
|
|
|
|
* the setting should be compared (TRUE) or not (DEFAULT). */
|
|
|
|
|
/*< private >*/
|
|
|
|
|
NMTernary (*compare_property)(const struct _NMSettInfoSetting *sett_info,
|
|
|
|
|
guint property_idx,
|
2019-04-25 10:17:47 +02:00
|
|
|
NMConnection * con_a,
|
|
|
|
|
NMSetting * set_a,
|
|
|
|
|
NMConnection * con_b,
|
|
|
|
|
NMSetting * set_b,
|
libnm: rework compare_property() implementation for NMSetting
NMSetting's compare_property() has and had two callers:
nm_setting_compare() and nm_setting_diff().
compare_property() accepts a NMSettingCompareFlags argument, but
at the same time, both callers have another complex (and
inconsistent!) set of pre-checks for shortcuting the call of
compare_property(): should_compare_prop().
Merge should_compare_prop() into compare_property(). This way,
nm_setting_compare() and nm_setting_diff() has less additional
code, and are simpler to follow. Especially nm_setting_compare()
is now trivial. And nm_setting_diff() is still complicated, but
not related to the question how the property compares or whether
it should be compared at all.
If you want to know whether it should be compared, all you need to do
now is follow NMSettingClass.compare_property().
This changes function pointer NMSettingClass.compare_property(),
which is public API. However, no user can actually use this (and shall
not!), because _nm_setting_class_commit_full() etc. is private API. A
user outside of libnm-core cannot create his/her own subclasses of
NMSetting, and never could in the past. So, this API/ABI change doesn't
matter.
2019-01-09 09:08:39 +01:00
|
|
|
NMSettingCompareFlags flags);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-01-11 15:16:33 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
void (*duplicate_copy_properties)(const struct _NMSettInfoSetting *sett_info,
|
|
|
|
|
NMSetting * src,
|
|
|
|
|
NMSetting * dst);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-01-21 08:10:14 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
void (*enumerate_values)(const struct _NMSettInfoProperty *property_info,
|
|
|
|
|
NMSetting * setting,
|
|
|
|
|
NMSettingValueIterFn func,
|
|
|
|
|
gpointer user_data);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-01-21 08:46:41 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
gboolean (*aggregate)(NMSetting *setting, int type_i, gpointer arg);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2014-05-15 09:55:18 -04:00
|
|
|
/*< private >*/
|
2019-01-31 09:38:58 +01:00
|
|
|
void (*for_each_secret)(NMSetting * setting,
|
|
|
|
|
const char * secret_name,
|
|
|
|
|
GVariant * val,
|
|
|
|
|
gboolean remove_non_secrets,
|
|
|
|
|
_NMConnectionForEachSecretFunc callback,
|
|
|
|
|
gpointer callback_data,
|
|
|
|
|
GVariantBuilder * setting_builder);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
libnm: use NMMetaSettingInfo for tracking setting priority
Previously, each (non abstract) NMSetting class had to register
its name and priority via _nm_register_setting().
Note, that libnm-core.la already links against "nm-meta-setting.c",
which also redundantly keeps track of the settings name and gtype
as well.
Re-use NMMetaSettingInfo also in libnm-core.la, to track this meta
data.
The goal is to get rid of private data structures that track
meta data about NMSetting classes. In this case, "registered_settings"
hash. Instead, we should have one place where all this meta data
is tracked. This was, it is also accessible as internal API,
which can be useful (for keyfile).
Note that NMSettingClass has some overlap with NMMetaSettingInfo.
One difference is, that NMMetaSettingInfo is const, while NMSettingClass
is only initialized during the class_init() method. Appart from that,
it's mostly a matter of taste, whether we attach meta data to
NMSettingClass, to NMMetaSettingInfo, or to a static-array indexed
by NMMetaSettingType.
Note, that previously, _nm_register_setting() was private API. That
means, no user could subclass a functioning NMSetting instance. The same
is still true: NMMetaSettingInfo is internal API and users cannot access
it to create their own NMSetting subclasses. But that is almost desired.
libnm is not designed, to be extensible via subclassing, nor is it
clear why that would be a useful thing to do. One day, we should remove
the NMSetting and NMSettingClass definitions from public headers. Their
only use is subclassing the types, which however does not work.
While libnm-core was linking already against nm-meta-setting.c,
nm_meta_setting_infos was unreferenced. So, this change increases
the binary size of libnm and NetworkManager (1032 bytes). Note however
that roughly the same information was previously allocated at runtime.
2018-07-27 14:08:14 +02:00
|
|
|
/*< private >*/
|
2019-05-13 12:22:40 +02:00
|
|
|
gboolean (*init_from_dbus)(NMSetting * setting,
|
|
|
|
|
GHashTable * keys,
|
|
|
|
|
GVariant * setting_dict,
|
|
|
|
|
GVariant * connection_dict,
|
|
|
|
|
guint /* NMSettingParseFlags */ parse_flags,
|
|
|
|
|
GError ** error);
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-05-13 12:22:40 +02:00
|
|
|
/*< private >*/
|
|
|
|
|
gpointer padding[1];
|
2020-09-28 16:03:33 +02:00
|
|
|
|
2019-01-31 09:38:58 +01:00
|
|
|
/*< private >*/
|
|
|
|
|
const struct _NMMetaSettingInfo *setting_info;
|
2014-07-24 08:53:33 -04:00
|
|
|
} NMSettingClass;
|
|
|
|
|
|
|
|
|
|
GType nm_setting_get_type(void);
|
|
|
|
|
|
2014-08-12 17:25:26 -04:00
|
|
|
GType nm_setting_lookup_type(const char *name);
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
NMSetting *nm_setting_duplicate(NMSetting *setting);
|
|
|
|
|
|
|
|
|
|
const char *nm_setting_get_name(NMSetting *setting);
|
|
|
|
|
|
2014-10-21 22:30:31 -04:00
|
|
|
gboolean nm_setting_verify(NMSetting *setting, NMConnection *connection, GError **error);
|
2014-07-24 08:53:33 -04:00
|
|
|
|
2015-11-10 14:36:20 +01:00
|
|
|
NM_AVAILABLE_IN_1_2
|
|
|
|
|
gboolean nm_setting_verify_secrets(NMSetting *setting, NMConnection *connection, GError **error);
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
gboolean nm_setting_compare(NMSetting *a, NMSetting *b, NMSettingCompareFlags flags);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* NMSettingDiffResult:
|
|
|
|
|
* @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
|
2014-02-26 11:26:25 +01:00
|
|
|
* @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT: the property is present in
|
|
|
|
|
* setting A but is set to the default value. This flag is only set,
|
|
|
|
|
* if you specify @NM_SETTING_COMPARE_FLAG_DIFF_RESULT_WITH_DEFAULT.
|
|
|
|
|
* @NM_SETTING_DIFF_RESULT_IN_B_DEFAULT: analog to @NM_SETTING_DIFF_RESULT_IN_A_DEFAULT.
|
2014-07-24 08:53:33 -04:00
|
|
|
*
|
|
|
|
|
* These values indicate the result of a setting difference operation.
|
|
|
|
|
**/
|
|
|
|
|
typedef enum {
|
|
|
|
|
NM_SETTING_DIFF_RESULT_UNKNOWN = 0x00000000,
|
|
|
|
|
NM_SETTING_DIFF_RESULT_IN_A = 0x00000001,
|
|
|
|
|
NM_SETTING_DIFF_RESULT_IN_B = 0x00000002,
|
2014-02-26 11:26:25 +01:00
|
|
|
NM_SETTING_DIFF_RESULT_IN_A_DEFAULT = 0x00000004,
|
2019-01-09 16:06:40 +01:00
|
|
|
NM_SETTING_DIFF_RESULT_IN_B_DEFAULT = 0x00000008,
|
2014-07-24 08:53:33 -04:00
|
|
|
} 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);
|
|
|
|
|
|
libnm: add generic-data for implementing NMSetting
Add a new way how NMSetting subclasses can be implemented.
Currently, most NMSetting implementations realize all their properties
via GObject properties. That has some downsides:
- the biggest one, is the large effort to add new properties.
Most of them are implemented on a one-by-one basis and they come
with additional API (like native getter functions).
It makes it cumbersome to add more properties.
- for certain properties, it's hard to encode them entirely in
a GObject property. That results in unusable API like
NM_SETTING_IP_CONFIG_ADDRESSES, NM_SETTING_BOND_OPTIONS,
NM_SETTING_USER_DATA. These complex valued properties only
exist, because we currently always need GObject properties
to even implement simple functionality. For example,
nm_setting_duplicate() is entirely implemented via
nm_setting_enumerate_values(), which can only iterate
GObject properies. There is no reason why this is necessary.
Note also how nmcli badly handles bond options and VPN
data. That is only a shortcoming of nmcli and wouldn't
need to be that way. But it happend, because we didn't
keep an open mind that settings might be more than just
accessing GObject properties.
- a major point of NMSetting is to convert to/from a GVariant
from the D-Bus API. As NMSetting needs to squeeze all values
into the static GObject structure, there is no place to
encode invalid or unknown properties. Optimally,
_nm_setting_new_from_dbus() does not loose any information
and a subsequent _nm_setting_to_dbus() can restore the original
variant. That is interesting, because we want that an older
libnm client can talk to a newer NetworkManager version. The
client needs to handle unknown properties gracefully to stay
forward compatible. However, it also should not just drop the
properties on the floor.
Note however, optimally we want that nm_setting_verify() still
can reject settings that have such unknown/invalid values. So,
it should be possible to create an NMSetting instance without
error or loosing information. But verify() should be usable to
identify such settings as invalid.
They also have a few upsides.
- libnm is heavily oriented around GObject. So, we generate
our nm-settings manual based on the gtk-doc. Note however,
how we fail to generate a useful manual for bond.options.
Also note, that there is no reason we couldn't generate
great documentation, even if the properties are not GObject
properties.
- GObject properties do give some functionality like meta-data,
data binding and notification. However, the meta-data is not
sufficient on its own. Note how keyfile and nmcli need extensive
descriptor tables on top of GObject properties, to make this
useful. Note how GObject notifications for NMSetting instances
are usually not useful, aside for data binding like nmtui does.
Also note how NMSettingBond already follows a different paradigm
than using GObject properties. Nowdays, NMSettingBond is considered
a mistake (related bug rh#1032808). Many ideas of NMSettingBond
are flawed, like exposing an inferiour API that reduces everything
to a string hash. Also, it only implemented the options hash inside
NMSettingBond. That means, if we would consider this a good style,
we would have to duplicate this approach in each new setting
implementation.
Add a new style to track data for NMSetting subclasses. It keeps
an internal hash table with all GVariant properies. Also, the
functionality is hooked into NMSetting base class, so all future
subclasses that follow this way, can benefit from this. This approach
has a few similiarties with NMSettingBond, but avoids its flaws.
With this, we also no longer need GObject properties (if we would
also implement generating useful documentation based on non-gkt-doc).
They may be added as accessors if they are useful, but there is no
need for them.
Also, handling the properties as a hash of variants invites for a
more generic approach when handling them. While we still could add
accessors that operate on a one-by-one bases, this leads to a more
generic usage where we apply common functionality to a set of properties.
Also, this is for the moment entirely internal and an implementation
detail. It's entirely up to the NMSetting subclass to make use of this
new style. Also, there are little hooks for the subclass available.
If they turn out to be necessary, they might be added. However, for
the moment, the functionality is restricted to what is useful and
necessary.
2018-07-27 10:05:40 +02:00
|
|
|
/*****************************************************************************/
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
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);
|
|
|
|
|
|
libnm: add generic-data for implementing NMSetting
Add a new way how NMSetting subclasses can be implemented.
Currently, most NMSetting implementations realize all their properties
via GObject properties. That has some downsides:
- the biggest one, is the large effort to add new properties.
Most of them are implemented on a one-by-one basis and they come
with additional API (like native getter functions).
It makes it cumbersome to add more properties.
- for certain properties, it's hard to encode them entirely in
a GObject property. That results in unusable API like
NM_SETTING_IP_CONFIG_ADDRESSES, NM_SETTING_BOND_OPTIONS,
NM_SETTING_USER_DATA. These complex valued properties only
exist, because we currently always need GObject properties
to even implement simple functionality. For example,
nm_setting_duplicate() is entirely implemented via
nm_setting_enumerate_values(), which can only iterate
GObject properies. There is no reason why this is necessary.
Note also how nmcli badly handles bond options and VPN
data. That is only a shortcoming of nmcli and wouldn't
need to be that way. But it happend, because we didn't
keep an open mind that settings might be more than just
accessing GObject properties.
- a major point of NMSetting is to convert to/from a GVariant
from the D-Bus API. As NMSetting needs to squeeze all values
into the static GObject structure, there is no place to
encode invalid or unknown properties. Optimally,
_nm_setting_new_from_dbus() does not loose any information
and a subsequent _nm_setting_to_dbus() can restore the original
variant. That is interesting, because we want that an older
libnm client can talk to a newer NetworkManager version. The
client needs to handle unknown properties gracefully to stay
forward compatible. However, it also should not just drop the
properties on the floor.
Note however, optimally we want that nm_setting_verify() still
can reject settings that have such unknown/invalid values. So,
it should be possible to create an NMSetting instance without
error or loosing information. But verify() should be usable to
identify such settings as invalid.
They also have a few upsides.
- libnm is heavily oriented around GObject. So, we generate
our nm-settings manual based on the gtk-doc. Note however,
how we fail to generate a useful manual for bond.options.
Also note, that there is no reason we couldn't generate
great documentation, even if the properties are not GObject
properties.
- GObject properties do give some functionality like meta-data,
data binding and notification. However, the meta-data is not
sufficient on its own. Note how keyfile and nmcli need extensive
descriptor tables on top of GObject properties, to make this
useful. Note how GObject notifications for NMSetting instances
are usually not useful, aside for data binding like nmtui does.
Also note how NMSettingBond already follows a different paradigm
than using GObject properties. Nowdays, NMSettingBond is considered
a mistake (related bug rh#1032808). Many ideas of NMSettingBond
are flawed, like exposing an inferiour API that reduces everything
to a string hash. Also, it only implemented the options hash inside
NMSettingBond. That means, if we would consider this a good style,
we would have to duplicate this approach in each new setting
implementation.
Add a new style to track data for NMSetting subclasses. It keeps
an internal hash table with all GVariant properies. Also, the
functionality is hooked into NMSetting base class, so all future
subclasses that follow this way, can benefit from this. This approach
has a few similiarties with NMSettingBond, but avoids its flaws.
With this, we also no longer need GObject properties (if we would
also implement generating useful documentation based on non-gkt-doc).
They may be added as accessors if they are useful, but there is no
need for them.
Also, handling the properties as a hash of variants invites for a
more generic approach when handling them. While we still could add
accessors that operate on a one-by-one bases, this leads to a more
generic usage where we apply common functionality to a set of properties.
Also, this is for the moment entirely internal and an implementation
detail. It's entirely up to the NMSetting subclass to make use of this
new style. Also, there are little hooks for the subclass available.
If they turn out to be necessary, they might be added. However, for
the moment, the functionality is restricted to what is useful and
necessary.
2018-07-27 10:05:40 +02:00
|
|
|
/*****************************************************************************/
|
|
|
|
|
|
libnm: add API for setting gendata options to NMSetting (nm_setting_option_get())
NMSettingEthtool is implemented using "gendata", meaning a hash
of GVariant. This is different from most other settings that have
properties implemented as GObject properties. There are two reasons
for this approach:
- The setting is transferred via D-Bus as "a{sv}" dictionary.
By unpacking the dictionary into GObject properties, the setting
cannot handle unknown properties. To be forward compatible (and
due to sloppy programming), unknown dictionary keys are silently
ignored when parsing a NMSetting. That is error prone and also
prevents settings to be treated loss-less.
Instead, we should at first accept all values from the dictionary.
Only in a second step, nm_connection_verify() rejects invalid settings
with an error reason. This way, the user can create a NMSetting,
but in a separate step handle if the setting doesn't verify.
"gendata" solves this by tracking the full GVariant dictionary.
This is still not entirely lossless, because multiple keys are
combined.
This is for example interesting if an libnm client fetches a connection
from a newer NetworkManager version. Now the user can modify the
properties that she knows about, while leaving all unknown
properties (from newer versions) in place.
- the approach aims to reduce the necessary boiler plate to create
GObject properties. Adding a new property should require less new code.
This approach was always be intended to be suitable for all settings, not only
NMSettingEthtool. We should not once again try to add API like
nm_setting_ethtool_set_feature(), nm_setting_ethtool_set_coalesce(), etc.
Note that the option name already fully encodes whether it is a feature,
a coalesce option, or whatever. We should not have
"nm_setting_set_$SUB_GROUP (setting, $ONE_NAME_FROM_GROUP)" API, but
simply "nm_setting_option_set (setting, $OPTION)" accessors.
Also, when parsing a NMSettingEthtool from a GVariant, then a feature
option can be any kind of variant. Only nm_setting_verify() rejects
variants of the wrong type. As such, nm_setting_option_set*() also
doesn't validate whether the variant type matches the option. Of course,
if you set a value of wrong type, verify() will reject the setting.
Add new general purpose API for this and expose it for NMSetting.
2020-05-14 09:16:32 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
GVariant *nm_setting_option_get(NMSetting *setting, const char *opt_name);
|
|
|
|
|
|
2020-05-14 09:16:32 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
gboolean
|
|
|
|
|
nm_setting_option_get_boolean(NMSetting *setting, const char *opt_name, gboolean *out_value);
|
|
|
|
|
|
2020-05-20 16:31:30 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
gboolean nm_setting_option_get_uint32(NMSetting *setting, const char *opt_name, guint32 *out_value);
|
|
|
|
|
|
2020-05-14 09:16:32 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
void nm_setting_option_set(NMSetting *setting, const char *opt_name, GVariant *variant);
|
|
|
|
|
|
2020-05-20 16:31:30 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
void nm_setting_option_set_uint32(NMSetting *setting, const char *opt_name, guint32 value);
|
|
|
|
|
|
2020-05-14 09:16:32 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
void nm_setting_option_set_boolean(NMSetting *setting, const char *opt_name, gboolean value);
|
libnm: add API for setting gendata options to NMSetting (nm_setting_option_get())
NMSettingEthtool is implemented using "gendata", meaning a hash
of GVariant. This is different from most other settings that have
properties implemented as GObject properties. There are two reasons
for this approach:
- The setting is transferred via D-Bus as "a{sv}" dictionary.
By unpacking the dictionary into GObject properties, the setting
cannot handle unknown properties. To be forward compatible (and
due to sloppy programming), unknown dictionary keys are silently
ignored when parsing a NMSetting. That is error prone and also
prevents settings to be treated loss-less.
Instead, we should at first accept all values from the dictionary.
Only in a second step, nm_connection_verify() rejects invalid settings
with an error reason. This way, the user can create a NMSetting,
but in a separate step handle if the setting doesn't verify.
"gendata" solves this by tracking the full GVariant dictionary.
This is still not entirely lossless, because multiple keys are
combined.
This is for example interesting if an libnm client fetches a connection
from a newer NetworkManager version. Now the user can modify the
properties that she knows about, while leaving all unknown
properties (from newer versions) in place.
- the approach aims to reduce the necessary boiler plate to create
GObject properties. Adding a new property should require less new code.
This approach was always be intended to be suitable for all settings, not only
NMSettingEthtool. We should not once again try to add API like
nm_setting_ethtool_set_feature(), nm_setting_ethtool_set_coalesce(), etc.
Note that the option name already fully encodes whether it is a feature,
a coalesce option, or whatever. We should not have
"nm_setting_set_$SUB_GROUP (setting, $ONE_NAME_FROM_GROUP)" API, but
simply "nm_setting_option_set (setting, $OPTION)" accessors.
Also, when parsing a NMSettingEthtool from a GVariant, then a feature
option can be any kind of variant. Only nm_setting_verify() rejects
variants of the wrong type. As such, nm_setting_option_set*() also
doesn't validate whether the variant type matches the option. Of course,
if you set a value of wrong type, verify() will reject the setting.
Add new general purpose API for this and expose it for NMSetting.
2020-05-14 09:16:32 +02:00
|
|
|
|
2020-05-14 09:16:33 +02:00
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
const char *const *nm_setting_option_get_all_names(NMSetting *setting, guint *out_len);
|
2020-05-14 09:16:33 +02:00
|
|
|
|
|
|
|
|
NM_AVAILABLE_IN_1_26
|
|
|
|
|
void nm_setting_option_clear_by_name(NMSetting *setting, NMUtilsPredicateStr predicate);
|
|
|
|
|
|
libnm: add API for setting gendata options to NMSetting (nm_setting_option_get())
NMSettingEthtool is implemented using "gendata", meaning a hash
of GVariant. This is different from most other settings that have
properties implemented as GObject properties. There are two reasons
for this approach:
- The setting is transferred via D-Bus as "a{sv}" dictionary.
By unpacking the dictionary into GObject properties, the setting
cannot handle unknown properties. To be forward compatible (and
due to sloppy programming), unknown dictionary keys are silently
ignored when parsing a NMSetting. That is error prone and also
prevents settings to be treated loss-less.
Instead, we should at first accept all values from the dictionary.
Only in a second step, nm_connection_verify() rejects invalid settings
with an error reason. This way, the user can create a NMSetting,
but in a separate step handle if the setting doesn't verify.
"gendata" solves this by tracking the full GVariant dictionary.
This is still not entirely lossless, because multiple keys are
combined.
This is for example interesting if an libnm client fetches a connection
from a newer NetworkManager version. Now the user can modify the
properties that she knows about, while leaving all unknown
properties (from newer versions) in place.
- the approach aims to reduce the necessary boiler plate to create
GObject properties. Adding a new property should require less new code.
This approach was always be intended to be suitable for all settings, not only
NMSettingEthtool. We should not once again try to add API like
nm_setting_ethtool_set_feature(), nm_setting_ethtool_set_coalesce(), etc.
Note that the option name already fully encodes whether it is a feature,
a coalesce option, or whatever. We should not have
"nm_setting_set_$SUB_GROUP (setting, $ONE_NAME_FROM_GROUP)" API, but
simply "nm_setting_option_set (setting, $OPTION)" accessors.
Also, when parsing a NMSettingEthtool from a GVariant, then a feature
option can be any kind of variant. Only nm_setting_verify() rejects
variants of the wrong type. As such, nm_setting_option_set*() also
doesn't validate whether the variant type matches the option. Of course,
if you set a value of wrong type, verify() will reject the setting.
Add new general purpose API for this and expose it for NMSetting.
2020-05-14 09:16:32 +02:00
|
|
|
/*****************************************************************************/
|
|
|
|
|
|
2014-11-16 16:13:06 -05:00
|
|
|
const GVariantType *nm_setting_get_dbus_property_type(NMSetting * setting,
|
|
|
|
|
const char *property_name);
|
|
|
|
|
|
libnm: add generic-data for implementing NMSetting
Add a new way how NMSetting subclasses can be implemented.
Currently, most NMSetting implementations realize all their properties
via GObject properties. That has some downsides:
- the biggest one, is the large effort to add new properties.
Most of them are implemented on a one-by-one basis and they come
with additional API (like native getter functions).
It makes it cumbersome to add more properties.
- for certain properties, it's hard to encode them entirely in
a GObject property. That results in unusable API like
NM_SETTING_IP_CONFIG_ADDRESSES, NM_SETTING_BOND_OPTIONS,
NM_SETTING_USER_DATA. These complex valued properties only
exist, because we currently always need GObject properties
to even implement simple functionality. For example,
nm_setting_duplicate() is entirely implemented via
nm_setting_enumerate_values(), which can only iterate
GObject properies. There is no reason why this is necessary.
Note also how nmcli badly handles bond options and VPN
data. That is only a shortcoming of nmcli and wouldn't
need to be that way. But it happend, because we didn't
keep an open mind that settings might be more than just
accessing GObject properties.
- a major point of NMSetting is to convert to/from a GVariant
from the D-Bus API. As NMSetting needs to squeeze all values
into the static GObject structure, there is no place to
encode invalid or unknown properties. Optimally,
_nm_setting_new_from_dbus() does not loose any information
and a subsequent _nm_setting_to_dbus() can restore the original
variant. That is interesting, because we want that an older
libnm client can talk to a newer NetworkManager version. The
client needs to handle unknown properties gracefully to stay
forward compatible. However, it also should not just drop the
properties on the floor.
Note however, optimally we want that nm_setting_verify() still
can reject settings that have such unknown/invalid values. So,
it should be possible to create an NMSetting instance without
error or loosing information. But verify() should be usable to
identify such settings as invalid.
They also have a few upsides.
- libnm is heavily oriented around GObject. So, we generate
our nm-settings manual based on the gtk-doc. Note however,
how we fail to generate a useful manual for bond.options.
Also note, that there is no reason we couldn't generate
great documentation, even if the properties are not GObject
properties.
- GObject properties do give some functionality like meta-data,
data binding and notification. However, the meta-data is not
sufficient on its own. Note how keyfile and nmcli need extensive
descriptor tables on top of GObject properties, to make this
useful. Note how GObject notifications for NMSetting instances
are usually not useful, aside for data binding like nmtui does.
Also note how NMSettingBond already follows a different paradigm
than using GObject properties. Nowdays, NMSettingBond is considered
a mistake (related bug rh#1032808). Many ideas of NMSettingBond
are flawed, like exposing an inferiour API that reduces everything
to a string hash. Also, it only implemented the options hash inside
NMSettingBond. That means, if we would consider this a good style,
we would have to duplicate this approach in each new setting
implementation.
Add a new style to track data for NMSetting subclasses. It keeps
an internal hash table with all GVariant properies. Also, the
functionality is hooked into NMSetting base class, so all future
subclasses that follow this way, can benefit from this. This approach
has a few similiarties with NMSettingBond, but avoids its flaws.
With this, we also no longer need GObject properties (if we would
also implement generating useful documentation based on non-gkt-doc).
They may be added as accessors if they are useful, but there is no
need for them.
Also, handling the properties as a hash of variants invites for a
more generic approach when handling them. While we still could add
accessors that operate on a one-by-one bases, this leads to a more
generic usage where we apply common functionality to a set of properties.
Also, this is for the moment entirely internal and an implementation
detail. It's entirely up to the NMSetting subclass to make use of this
new style. Also, there are little hooks for the subclass available.
If they turn out to be necessary, they might be added. However, for
the moment, the functionality is restricted to what is useful and
necessary.
2018-07-27 10:05:40 +02:00
|
|
|
/*****************************************************************************/
|
|
|
|
|
|
2014-07-24 08:53:33 -04:00
|
|
|
G_END_DECLS
|
|
|
|
|
|
all: fix up multiple-include-guard defines
Previously, src/nm-ip4-config.h, libnm/nm-ip4-config.h, and
libnm-glib/nm-ip4-config.h all used "NM_IP4_CONFIG_H" as an include
guard, which meant that nm-test-utils.h could not tell which of them
was being included (and so, eg, if you tried to include
nm-ip4-config.h in a libnm test, it would fail to compile because
nm-test-utils.h was referring to symbols in src/nm-ip4-config.h).
Fix this by changing the include guards in the non-API-stable parts of
the tree:
- libnm-glib/nm-ip4-config.h remains NM_IP4_CONFIG_H
- libnm/nm-ip4-config.h now uses __NM_IP4_CONFIG_H__
- src/nm-ip4-config.h now uses __NETWORKMANAGER_IP4_CONFIG_H__
And likewise for all other headers.
The two non-"nm"-prefixed headers, libnm/NetworkManager.h and
src/NetworkManagerUtils.h are now __NETWORKMANAGER_H__ and
__NETWORKMANAGER_UTILS_H__ respectively, which, while not entirely
consistent with the general scheme, do still mostly make sense in
isolation.
2014-08-13 14:10:11 -04:00
|
|
|
#endif /* __NM_SETTING_H__ */
|
