From f40a829d31f1809c67b8c695f125e4e71ff98336 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8D=C3=B1igo=20Huguet?= Date: Wed, 29 Nov 2023 12:15:42 +0100 Subject: [PATCH] libnm: document what each flag from NMSettingParseFlags means Specially in the case of BEST_EFFORT it's not completely clear what each flag means. For example: with BEST_EFFORT, in the case of partial success should we return an error value or a success value? Add some comments and documentation to clarify. --- src/libnm-core-intern/nm-core-internal.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/libnm-core-intern/nm-core-internal.h b/src/libnm-core-intern/nm-core-internal.h index dc232f1891..1fc33550c8 100644 --- a/src/libnm-core-intern/nm-core-internal.h +++ b/src/libnm-core-intern/nm-core-internal.h @@ -192,6 +192,21 @@ NM_TERNARY_TO_OPTION_BOOL(NMTernary v) NMSetting **_nm_connection_get_settings_arr(NMConnection *connection); +/** + * NMSettingParseFlags: + * @NM_SETTING_PARSE_FLAGS_NONE: no special handling. + * @NM_SETTING_PARSE_FLAGS_STRICT: be strict about unexpected/invalid settings. + * Such issues cause the parsing method to fail. + * @NM_SETTING_PARSE_FLAGS_BEST_EFFORT: ignore most errors about invalid/unexpected + * settings. This is, in theory, an even less strict mode than NONE (in practice + * we already ignore most errors without BEST_EFFORT, so both are almost the + * same). Only if the property has from_dbus_is_full are errors taken into + * account with this flag set. + * @NM_SETTING_PARSE_FLAGS_NORMALIZE: normalize the connection after loading it. + * A failure to normalize is always an error, even with BEST_EFFORT. + * + * It is an error to set NM_SETTING_PARSE_FLAGS_STRICT | NM_SETTING_PARSE_FLAGS_BEST_EFFORT + */ typedef enum /*< skip >*/ { NM_SETTING_PARSE_FLAGS_NONE = 0, NM_SETTING_PARSE_FLAGS_STRICT = 1LL << 0, @@ -723,6 +738,9 @@ typedef struct { NMSetting *setting, GVariant *connection_dict, GVariant *value, \ NMSettingParseFlags parse_flags, NMTernary *out_is_modified, GError **error + /* If there might be errors, see #NMSettingParseFlags to understand the + * different parsing modes (strict/best effort). + */ gboolean (*from_dbus_fcn)(_NM_SETT_INFO_PROP_FROM_DBUS_FCN_ARGS _nm_nil); #define _NM_SETT_INFO_PROP_MISSING_FROM_DBUS_FCN_ARGS \