[gimp] libgimp: new gimp_image_metadata_save_filter API

[Daniel Novomeský <dnovomesky src gnome org>]

commit ff87bc8d4d41a8335cde13bd0151c75925e82c0c
Author: Daniel Novomeský <dnovomesky gmail com>
Date:   Tue Mar 15 13:01:45 2022 +0100

    libgimp: new gimp_image_metadata_save_filter API
    
    This new function is an alternative to existing
    gimp_image_metadata_save_finish, when you want to save metadata
    yourself and you need only filtering processing.
    It returns filtered metadata allowing the caller
    to save the finalized metadata via other means
    (via native format’s library for example)
    This API can be used to support metadata saving of image formats
    not directly supported by gexiv2/exiv2.

 libgimp/gimp.def                 |   1 +
 libgimp/gimpimagemetadata-save.c | 116 ++++++++++++++++++++++++++++++---------
 libgimp/gimpimagemetadata.h      |   6 ++
 3 files changed, 97 insertions(+), 26 deletions(-)
---
diff --git a/libgimp/gimp.def b/libgimp/gimp.def
index 753248cd78..34fed87183 100644
--- a/libgimp/gimp.def
+++ b/libgimp/gimp.def
@@ -452,6 +452,7 @@ EXPORTS
        gimp_image_metadata_load_finish
        gimp_image_metadata_load_prepare
        gimp_image_metadata_load_thumbnail
+       gimp_image_metadata_save_filter
        gimp_image_metadata_save_finish
        gimp_image_metadata_save_prepare
        gimp_image_new
diff --git a/libgimp/gimpimagemetadata-save.c b/libgimp/gimpimagemetadata-save.c
index c75565ab1a..afd44aacdd 100644
--- a/libgimp/gimpimagemetadata-save.c
+++ b/libgimp/gimpimagemetadata-save.c
@@ -519,33 +519,38 @@ gimp_image_metadata_set_xmp_structs (GList          *xmp_list,
 }
 
 /**
- * gimp_image_metadata_save_finish:
+ * gimp_image_metadata_save_filter:
  * @image:     The actually saved image
  * @mime_type: The saved file's mime-type
- * @metadata:  The metadata to write to @file
+ * @metadata:  The metadata to export
  * @flags:     Flags to specify what of the metadata to save
- * @file:      The file @image was saved to
+ * @file:      The file @image was saved to or NULL if file was not saved yet
  * @error:     Return location for error message
  *
- * Saves the @metadata retrieved from the image with
- * gimp_image_metadata_save_prepare() to @file, taking into account
- * the passed @flags.
+ * Filters the @metadata retrieved from the image with
+ * gimp_image_metadata_save_prepare(),
+ * taking into account the passed @flags.
  *
  * Note that the @image passed to this function might be different
  * from the image passed to gimp_image_metadata_save_prepare(), due
  * to whatever file export conversion happened in the meantime
  *
- * Returns: Whether the save was successful.
+ * This is an alternative to gimp_image_metadata_save_finish when you
+ * want to save metadata yourself and you need only filtering processing.
  *
- * Since: 2.10
+ * Returns: Filtered metadata or NULL in case of failure.
+ *
+ * Use g_object_unref() when returned metadata are no longer needed
+ *
+ * Since: 3.0
  */
-gboolean
-gimp_image_metadata_save_finish (GimpImage              *image,
-                                 const gchar            *mime_type,
-                                 GimpMetadata           *metadata,
-                                 GimpMetadataSaveFlags   flags,
-                                 GFile                  *file,
-                                 GError                **error)
+GimpMetadata *
+gimp_image_metadata_save_filter (GimpImage            *image,
+                                 const gchar          *mime_type,
+                                 GimpMetadata         *metadata,
+                                 GimpMetadataSaveFlags flags,
+                                 GFile                *file,
+                                 GError              **error)
 {
   GimpMetadata   *new_metadata;
   GExiv2Metadata *new_g2metadata;
@@ -558,28 +563,33 @@ gimp_image_metadata_save_finish (GimpImage              *image,
   gboolean        support_exif;
   gboolean        support_xmp;
   gboolean        support_iptc;
-  gboolean        success = FALSE;
   gint            i;
 
-  g_return_val_if_fail (GIMP_IS_IMAGE (image), FALSE);
-  g_return_val_if_fail (mime_type != NULL, FALSE);
-  g_return_val_if_fail (GEXIV2_IS_METADATA (metadata), FALSE);
-  g_return_val_if_fail (G_IS_FILE (file), FALSE);
-  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+  g_return_val_if_fail (GIMP_IS_IMAGE (image), NULL);
+  g_return_val_if_fail (mime_type != NULL, NULL);
+  g_return_val_if_fail (GEXIV2_IS_METADATA (metadata), NULL);
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 
   if (! (flags & (GIMP_METADATA_SAVE_EXIF |
                   GIMP_METADATA_SAVE_XMP  |
                   GIMP_METADATA_SAVE_IPTC |
                   GIMP_METADATA_SAVE_THUMBNAIL)))
-    return TRUE;
+    return NULL;
 
-  /* read metadata from saved file */
-  new_metadata = gimp_metadata_load_from_file (file, error);
-  new_g2metadata = GEXIV2_METADATA (new_metadata);
+  if (file)
+    {
+      /* read metadata from saved file */
+      new_metadata = gimp_metadata_load_from_file (file, error);
+    }
+  else
+    {
+      new_metadata = gimp_metadata_new ();
+    }
 
   if (! new_metadata)
-    return FALSE;
+    return NULL;
 
+  new_g2metadata = GEXIV2_METADATA (new_metadata);
   support_exif = gexiv2_metadata_get_supports_exif (new_g2metadata);
   support_xmp  = gexiv2_metadata_get_supports_xmp  (new_g2metadata);
   support_iptc = gexiv2_metadata_get_supports_iptc (new_g2metadata);
@@ -842,6 +852,60 @@ gimp_image_metadata_save_finish (GimpImage              *image,
       /* nothing to do, blah blah */
     }
 
+  return new_metadata;
+}
+
+/**
+ * gimp_image_metadata_save_finish:
+ * @image:     The actually saved image
+ * @mime_type: The saved file's mime-type
+ * @metadata:  The metadata to write to @file
+ * @flags:     Flags to specify what of the metadata to save
+ * @file:      The file @image was saved to
+ * @error:     Return location for error message
+ *
+ * Saves the @metadata retrieved from the image with
+ * gimp_image_metadata_save_prepare() to @file, taking into account
+ * the passed @flags.
+ *
+ * Note that the @image passed to this function might be different
+ * from the image passed to gimp_image_metadata_save_prepare(), due
+ * to whatever file export conversion happened in the meantime
+ *
+ * Returns: Whether the save was successful.
+ *
+ * Since: 2.10
+ */
+gboolean
+gimp_image_metadata_save_finish (GimpImage            *image,
+                                 const gchar          *mime_type,
+                                 GimpMetadata         *metadata,
+                                 GimpMetadataSaveFlags flags,
+                                 GFile                *file,
+                                 GError              **error)
+{
+  GimpMetadata *new_metadata;
+  gboolean      success = FALSE;
+
+  g_return_val_if_fail (GIMP_IS_IMAGE (image), FALSE);
+  g_return_val_if_fail (mime_type != NULL, FALSE);
+  g_return_val_if_fail (GEXIV2_IS_METADATA (metadata), FALSE);
+  g_return_val_if_fail (G_IS_FILE (file), FALSE);
+  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+
+  if (! (flags & (GIMP_METADATA_SAVE_EXIF |
+                  GIMP_METADATA_SAVE_XMP  |
+                  GIMP_METADATA_SAVE_IPTC |
+                  GIMP_METADATA_SAVE_THUMBNAIL)))
+    return TRUE;
+
+  new_metadata = gimp_image_metadata_save_filter (image, mime_type, metadata,
+                                                  flags, file, error);
+  if (! new_metadata)
+    {
+      return FALSE;
+    }
+
   success = gimp_metadata_save_to_file (new_metadata, file, error);
 
   g_object_unref (new_metadata);
diff --git a/libgimp/gimpimagemetadata.h b/libgimp/gimpimagemetadata.h
index 1f7c5970da..d21d4540c1 100644
--- a/libgimp/gimpimagemetadata.h
+++ b/libgimp/gimpimagemetadata.h
@@ -43,6 +43,12 @@ void           gimp_image_metadata_load_finish    (GimpImage             *image,
 GimpMetadata * gimp_image_metadata_save_prepare   (GimpImage             *image,
                                                    const gchar           *mime_type,
                                                    GimpMetadataSaveFlags *suggested_flags);
+GimpMetadata * gimp_image_metadata_save_filter    (GimpImage             *image,
+                                                   const gchar           *mime_type,
+                                                   GimpMetadata          *metadata,
+                                                   GimpMetadataSaveFlags  flags,
+                                                   GFile                 *file,
+                                                   GError               **error);
 gboolean       gimp_image_metadata_save_finish    (GimpImage             *image,
                                                    const gchar           *mime_type,
                                                    GimpMetadata          *metadata,