keyfile: expose keyfile handling in libnm as public API

8 files changed, 197 insertions, 99 deletions

diff --git a/Makefile.am b/Makefile.am
index 592c3c90b6..9138f96930 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1481,6 +1481,7 @@ nodist_libnm_liblibnm_la_SOURCES = \
 
 libnm_liblibnm_la_LIBADD = \
 	libnm-core/nm-libnm-core-aux/libnm-libnm-core-aux.la \
+	libnm-core/nm-keyfile/libnm-keyfile.la \
 	libnm-core/libnm-core.la \
 	$(libnm_crypto_lib) \
 	libnm-core/nm-libnm-core-intern/libnm-libnm-core-intern.la \
@@ -1574,6 +1575,7 @@ libnm_NM_1_0_gir_FILES = \
 	$(libnm_core_lib_c_real) \
 	$(libnm_lib_h_pub_mkenums) \
 	$(libnm_lib_h_pub_real) \
+	libnm-core/nm-keyfile/nm-keyfile.c \
 	$(libnm_lib_c_mkenums) \
 	$(libnm_lib_c_real)
 libnm_NM_1_0_gir_SCANNERFLAGS = --warn-all --identifier-prefix=NM --symbol-prefix=nm
diff --git a/Makefile.examples b/Makefile.examples
index 385a8353ed..3ac292fdd8 100644
--- a/Makefile.examples
+++ b/Makefile.examples
@@ -178,6 +178,7 @@ EXTRA_DIST += \
 	examples/python/gi/list-connections.py \
 	examples/python/gi/nm-add-connection2.py \
 	examples/python/gi/nm-connection-update-stable-id.py \
+	examples/python/gi/nm-keyfile.py \
 	examples/python/gi/nm-update2.py \
 	examples/python/gi/nm-wg-set \
 	examples/python/gi/setting-user-data.py \
diff --git a/libnm-core/meson.build b/libnm-core/meson.build
index 2df54f918e..a5994db98c 100644
--- a/libnm-core/meson.build
+++ b/libnm-core/meson.build
@@ -235,12 +235,14 @@ libnm_libnm_core_aux_dep = declare_dependency(
   link_with: libnm_libnm_core_aux,
 )
 
+nm_keyfile_source = files(
+  'nm-keyfile/nm-keyfile-utils.c',
+  'nm-keyfile/nm-keyfile.c',
+)
+
 libnm_keyfile = static_library(
   'nm-keyfile',
-  sources: files(
-    'nm-keyfile/nm-keyfile-utils.c',
-    'nm-keyfile/nm-keyfile.c',
-  ) + [libnm_core_enum_sources[1]],
+  sources: nm_keyfile_source + [libnm_core_enum_sources[1]],
   dependencies: libnm_utils_base_dep,
   c_args: [
     '-DG_LOG_DOMAIN="@0@"'.format(libnm_name),
diff --git a/libnm-core/nm-keyfile.h b/libnm-core/nm-keyfile.h
index 1b1058c28c..0967d25495 100644
--- a/libnm-core/nm-keyfile.h
+++ b/libnm-core/nm-keyfile.h
@@ -11,6 +11,155 @@
 
 G_BEGIN_DECLS
 
+/**
+ * NMKeyfileHandlerFlags:
+ * @NM_KEYFILE_HANDLER_FLAGS_NONE: no flags set.
+ *
+ * Flags for customizing nm_keyfile_read() and nm_keyfile_write().
+ *
+ * Currently no flags are implemented.
+ *
+ * Since: 1.30
+ */
+typedef enum { /*< flags >*/
+               NM_KEYFILE_HANDLER_FLAGS_NONE = 0,
+} NMKeyfileHandlerFlags;
+
+/**
+ * NMKeyfileHandlerType:
+ * @NM_KEYFILE_HANDLER_TYPE_WARN: a warning.
+ * @NM_KEYFILE_HANDLER_TYPE_WRITE_CERT: for handling certificates while writing
+ *   a connection to keyfile.
+ *
+ * The type of the callback for %NMKeyfileReadHandler and %NMKeyfileWriteHandler.
+ * Depending on the type, you can interpret %NMKeyfileHandlerData.
+ *
+ * Since: 1.30
+ */
+typedef enum {
+    NM_KEYFILE_HANDLER_TYPE_WARN       = 1,
+    NM_KEYFILE_HANDLER_TYPE_WRITE_CERT = 2,
+} NMKeyfileHandlerType;
+
+/**
+ * NMKeyfileHandlerData:
+ *
+ * Opaque type with parameters for the callback. The actual content
+ * depends on the %NMKeyfileHandlerType.
+ *
+ * Since: 1.30
+ */
+typedef struct _NMKeyfileHandlerData NMKeyfileHandlerData;
+
+/**
+ * NMKeyfileReadHandler:
+ * @keyfile: the #GKeyFile that is currently read
+ * @connection: the #NMConnection that is being constructed.
+ * @handler_type: the %NMKeyfileHandlerType that indicates which type
+ *   the request is.
+ * @handler_data: the #NMKeyfileHandlerData. What you can do with it
+ *   depends on the @handler_type.
+ * @user_data: the user-data argument to nm_keyfile_read().
+ *
+ * Hook to nm_keyfile_read().
+ *
+ * The callee may abort the reading by setting an error via nm_keyfile_handler_data_fail_with_error().
+ *
+ * Returns: the callee should return TRUE, if the event was handled and/or recognized.
+ *   Otherwise, a default action will be performed that depends on the @type.
+ *   For %NM_KEYFILE_HANDLER_TYPE_WARN type, the default action is doing nothing.
+ *
+ * Since: 1.30
+ */
+typedef gboolean (*NMKeyfileReadHandler)(GKeyFile *            keyfile,
+                                         NMConnection *        connection,
+                                         NMKeyfileHandlerType  handler_type,
+                                         NMKeyfileHandlerData *handler_data,
+                                         void *                user_data);
+
+NM_AVAILABLE_IN_1_30
+NMConnection *nm_keyfile_read(GKeyFile *            keyfile,
+                              const char *          base_dir,
+                              NMKeyfileHandlerFlags handler_flags,
+                              NMKeyfileReadHandler  handler,
+                              void *                user_data,
+                              GError **             error);
+
+/**
+ * NMKeyfileWriteHandler:
+ * @connection: the #NMConnection that is currently written.
+ * @keyfile: the #GKeyFile that is currently constructed.
+ * @handler_type: the %NMKeyfileHandlerType that indicates which type
+ *   the request is.
+ * @handler_data: the #NMKeyfileHandlerData. What you can do with it
+ *   depends on the @handler_type.
+ * @user_data: the user-data argument to nm_keyfile_read().
+ *
+ * This is a hook to tweak the serialization.
+ *
+ * Handler for certain properties or events that are not entirely contained
+ * within the keyfile or that might be serialized differently. The @type and
+ * @handler_data arguments tell which kind of argument we have at hand.
+ *
+ * Currently only the type %NM_KEYFILE_HANDLER_TYPE_WRITE_CERT is supported.
+ *
+ * The callee may call nm_keyfile_handler_data_fail_with_error() to abort
+ * the writing with error.
+ *
+ * Returns: the callee should return %TRUE if the event was handled. If the
+ *   event was unhandled, a default action will be performed that depends on
+ *   the @handler_type.
+ *
+ * Since: 1.30
+ */
+typedef gboolean (*NMKeyfileWriteHandler)(NMConnection *        connection,
+                                          GKeyFile *            keyfile,
+                                          NMKeyfileHandlerType  handler_type,
+                                          NMKeyfileHandlerData *handler_data,
+                                          void *                user_data);
+
+NM_AVAILABLE_IN_1_30
+GKeyFile *nm_keyfile_write(NMConnection *        connection,
+                           NMKeyfileHandlerFlags handler_flags,
+                           NMKeyfileWriteHandler handler,
+                           void *                user_data,
+                           GError **             error);
+
+/*****************************************************************************/
+
+NM_AVAILABLE_IN_1_30
+void nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GError *src);
+
+NM_AVAILABLE_IN_1_30
+void nm_keyfile_handler_data_get_context(const NMKeyfileHandlerData *handler_data,
+                                         const char **               out_kf_group_name,
+                                         const char **               out_kf_key_name,
+                                         NMSetting **                out_cur_setting,
+                                         const char **               out_cur_property_name);
+
+/**
+ * NMKeyfileWarnSeverity:
+ * @NM_KEYFILE_WARN_SEVERITY_DEBUG: debug message
+ * @NM_KEYFILE_WARN_SEVERITY_INFO: info message
+ * @NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE: info message about a missing file
+ * @NM_KEYFILE_WARN_SEVERITY_WARN: a warning message
+ *
+ * The severity level of %NM_KEYFILE_HANDLER_TYPE_WARN events.
+ *
+ * Since: 1.30
+ */
+typedef enum {
+    NM_KEYFILE_WARN_SEVERITY_DEBUG             = 1000,
+    NM_KEYFILE_WARN_SEVERITY_INFO              = 2000,
+    NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE = 2901,
+    NM_KEYFILE_WARN_SEVERITY_WARN              = 3000,
+} NMKeyfileWarnSeverity;
+
+NM_AVAILABLE_IN_1_30
+void nm_keyfile_handler_data_warn_get(const NMKeyfileHandlerData *handler_data,
+                                      const char **               out_message,
+                                      NMKeyfileWarnSeverity *     out_severity);
+
 G_END_DECLS
 
 #endif /* __NM_KEYFILE_H__ */
diff --git a/libnm-core/nm-keyfile/nm-keyfile-internal.h b/libnm-core/nm-keyfile/nm-keyfile-internal.h
index 10fc4393be..13f8428252 100644
--- a/libnm-core/nm-keyfile/nm-keyfile-internal.h
+++ b/libnm-core/nm-keyfile/nm-keyfile-internal.h
@@ -33,47 +33,6 @@ char *nm_keyfile_detect_unqualified_path_scheme(const char *  base_dir,
                                                 gboolean      consider_exists,
                                                 gboolean *    out_exists);
 
-typedef enum { /*< flags >*/
-               NM_KEYFILE_HANDLER_FLAGS_NONE = 0,
-} NMKeyfileHandlerFlags;
-
-typedef enum {
-    NM_KEYFILE_HANDLER_TYPE_WARN       = 1,
-    NM_KEYFILE_HANDLER_TYPE_WRITE_CERT = 2,
-} NMKeyfileHandlerType;
-
-typedef struct _NMKeyfileHandlerData NMKeyfileHandlerData;
-
-/**
- * NMKeyfileReadHandler:
- *
- * Hook to nm_keyfile_read(). The user might fail the reading by setting
- * @error.
- *
- * Returns: should return TRUE, if the reading was handled. Otherwise,
- * a default action will be performed that depends on the @handler_type.
- * For %NM_KEYFILE_HANDLER_TYPE_WARN handler_type, the default action is doing nothing.
- */
-typedef gboolean (*NMKeyfileReadHandler)(GKeyFile *            keyfile,
-                                         NMConnection *        connection,
-                                         NMKeyfileHandlerType  handler_type,
-                                         NMKeyfileHandlerData *handler_data,
-                                         void *                user_data);
-
-typedef enum {
-    NM_KEYFILE_WARN_SEVERITY_DEBUG             = 1000,
-    NM_KEYFILE_WARN_SEVERITY_INFO              = 2000,
-    NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE = 2901,
-    NM_KEYFILE_WARN_SEVERITY_WARN              = 3000,
-} NMKeyfileWarnSeverity;
-
-NMConnection *nm_keyfile_read(GKeyFile *            keyfile,
-                              const char *          base_dir,
-                              NMKeyfileHandlerFlags handler_flags,
-                              NMKeyfileReadHandler  handler,
-                              void *                user_data,
-                              GError **             error);
-
 gboolean nm_keyfile_read_ensure_id(NMConnection *connection, const char *fallback_id);
 
 gboolean nm_keyfile_read_ensure_uuid(NMConnection *connection, const char *fallback_uuid_seed);
@@ -81,47 +40,10 @@ gboolean nm_keyfile_read_ensure_uuid(NMConnection *connection, const char *fallb
 /*****************************************************************************/
 
 /**
- * NMKeyfileWriteHandler:
- *
- * This is a hook to tweak the serialization.
- *
- * Handler for certain properties or events that are not entirely contained
- * within the keyfile or that might be serialized differently. The @handler_type and
- * @handler_data arguments tell which kind of argument we have at hand.
- *
- * Currently only the handler_type %NM_KEYFILE_HANDLER_TYPE_WRITE_CERT is supported, which provides
- * @handler_data as %NMKeyfileHandlerDataWriteCert. However, this handler should be generic enough
- * to support other types as well.
- *
- * This don't have to be only "properties". For example, nm_keyfile_read() uses
- * a similar handler to push warnings to the caller.
- *
- * If the handler raises an error, it should set the @error value. This causes
- * the an overall failure.
- *
- * Returns: whether the issue was handled. If the type was unhandled,
- * a default action will be performed. This might be raise an error,
- * do some fallback parsing, or do nothing.
- */
-typedef gboolean (*NMKeyfileWriteHandler)(NMConnection *        connection,
-                                          GKeyFile *            keyfile,
-                                          NMKeyfileHandlerType  handler_type,
-                                          NMKeyfileHandlerData *handler_data,
-                                          void *                user_data);
-
-GKeyFile *nm_keyfile_write(NMConnection *        connection,
-                           NMKeyfileHandlerFlags handler_flags,
-                           NMKeyfileWriteHandler handler,
-                           void *                user_data,
-                           GError **             error);
-
-/*****************************************************************************/
-
-/**
  * NMKeyfileHandlerDataWarn:
  *
  * this struct is passed as @handler_data for the @NMKeyfileReadHandler of
- * handler_type %NM_KEYFILE_HANDLER_TYPE_WARN.
+ * type %NM_KEYFILE_HANDLER_TYPE_WARN.
  */
 typedef struct {
     NMKeyfileWarnSeverity severity;
@@ -134,7 +56,7 @@ typedef struct {
  * NMKeyfileHandlerDataWriteCert:
  *
  * this struct is passed as @handler_data for the @NMKeyfileWriteHandler of
- * handler_type %NM_KEYFILE_HANDLER_TYPE_WRITE_CERT.
+ * type %NM_KEYFILE_HANDLER_TYPE_WRITE_CERT.
  */
 typedef struct {
     const NMSetting8021xSchemeVtable *vtable;
@@ -159,18 +81,6 @@ struct _NMKeyfileHandlerData {
 
 /*****************************************************************************/
 
-void nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GError *src);
-
-void nm_keyfile_handler_data_get_context(const NMKeyfileHandlerData *handler_data,
-                                         const char **               out_kf_group_name,
-                                         const char **               out_kf_key_name,
-                                         NMSetting **                out_cur_setting,
-                                         const char **               out_cur_property_name);
-
-void nm_keyfile_handler_data_warn_get(const NMKeyfileHandlerData *handler_data,
-                                      const char **               out_message,
-                                      NMKeyfileWarnSeverity *     out_severity);
-
 const char *_nm_keyfile_handler_data_warn_get_message(const NMKeyfileHandlerData *handler_data);
 
 /*****************************************************************************/
diff --git a/libnm-core/nm-keyfile/nm-keyfile.c b/libnm-core/nm-keyfile/nm-keyfile.c
index 1c979c1d8e..1042d2d604 100644
--- a/libnm-core/nm-keyfile/nm-keyfile.c
+++ b/libnm-core/nm-keyfile/nm-keyfile.c
@@ -3602,14 +3602,16 @@ nm_keyfile_read_ensure_uuid(NMConnection *connection, const char *fallback_uuid_
  *   the relative path is made absolute using @base_dir. This must
  *   be an absolute path.
  * @handler_flags: the #NMKeyfileHandlerFlags.
- * @handler: read handler
+ * @handler: (allow-none) (scope call): read handler
  * @user_data: user data for read handler
- * @error: error
+ * @error: (allow-none) (out): error
  *
  * Tries to create a NMConnection from a keyfile. The resulting keyfile is
  * not normalized and might not even verify.
  *
  * Returns: (transfer full): on success, returns the created connection.
+ *
+ * Since: 1.30
  */
 NMConnection *
 nm_keyfile_read(GKeyFile *            keyfile,
@@ -3948,6 +3950,19 @@ _write_setting_wireguard(NMSetting *setting, KeyfileWriterInfo *info)
     }
 }
 
+/**
+ * nm_keyfile_write:
+ * @connection: the #NMConnection to persist to keyfile.
+ * @handler_flags: the #NMKeyfileHandlerFlags.
+ * @handler: (allow-none) (scope call): optional handler for events and
+ *   to override the default behavior.
+ * @user_data: argument for @handler.
+ * @error: the #GError in case writing fails.
+ *
+ * Returns: (transfer full): a new #GKeyFile or %NULL on error.
+ *
+ * Since: 1.30
+ */
 GKeyFile *
 nm_keyfile_write(NMConnection *        connection,
                  NMKeyfileHandlerFlags handler_flags,
@@ -4213,6 +4228,8 @@ nm_keyfile_utils_create_filename(const char *name, gboolean with_extension)
  * Note that @src is no longer valid after this call. If you want
  * to keep using the same GError*, you need to set it to %NULL
  * after calling this function on it.
+ *
+ * Since: 1.30
  */
 void
 nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GError *src)
@@ -4237,6 +4254,8 @@ nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GErr
  *
  * Get context information of the current event. This function can be called
  * on all events, but the context information may be unset.
+ *
+ * Since: 1.30
  */
 void
 nm_keyfile_handler_data_get_context(const NMKeyfileHandlerData *handler_data,
@@ -4278,6 +4297,8 @@ _nm_keyfile_handler_data_warn_get_message(const NMKeyfileHandlerData *handler_da
  *  event.
  * @out_message: (out) (allow-none) (transfer none): the warning message.
  * @out_severity: (out) (allow-none): the #NMKeyfileWarnSeverity warning severity.
+ *
+ * Since: 1.30
  */
 void
 nm_keyfile_handler_data_warn_get(const NMKeyfileHandlerData *handler_data,
diff --git a/libnm/libnm.ver b/libnm/libnm.ver
index c85fcb5c5c..552e550646 100644
--- a/libnm/libnm.ver
+++ b/libnm/libnm.ver
@@ -1755,3 +1755,15 @@ global:
 	nm_setting_ip_config_remove_dhcp_reject_server;
 	nm_setting_wireless_get_ap_isolation;
 } libnm_1_26_4;
+
+libnm_1_30_0 {
+global:
+	nm_keyfile_handler_data_fail_with_error;
+	nm_keyfile_handler_data_get_context;
+	nm_keyfile_handler_data_warn_get;
+	nm_keyfile_handler_flags_get_type;
+	nm_keyfile_handler_type_get_type;
+	nm_keyfile_read;
+	nm_keyfile_warn_severity_get_type;
+	nm_keyfile_write;
+} libnm_1_28_0;
diff --git a/libnm/meson.build b/libnm/meson.build
index 9cfdb5433b..5808837459 100644
--- a/libnm/meson.build
+++ b/libnm/meson.build
@@ -154,6 +154,7 @@ liblibnm = static_library(
 links = [
   liblibnm,
   libnm_core,
+  libnm_keyfile,
   libnmdbus,
   libnm_systemd_logging_stub,
   libnm_utils_base,
@@ -201,7 +202,7 @@ if enable_introspection
 
   libnm_gir = gnome.generate_gir(
     libnm,
-    sources: libnm_core_sources + libnm_core_headers + libnm_core_enum_sources + libnm_sources + libnm_headers + libnm_enum_sources + [nm_version_macro_header],
+    sources: libnm_core_sources + nm_keyfile_source + libnm_core_headers + libnm_core_enum_sources + libnm_sources + libnm_headers + libnm_enum_sources + [nm_version_macro_header],
     includes: 'Gio-2.0',
     nsversion: nm_gir_version,
     namespace: 'NM',