/* GIMP - The GNU Image Manipulation Program
 * Copyright (C) 1995 Spencer Kimball and Peter Mattis
 *
 * gimpprocedure.c
 * Copyright (C) 2019 Michael Natterer <mitch@gimp.org>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#include "config.h"

#include <stdarg.h>
#include <sys/types.h>

#include <gobject/gvaluecollector.h>

#include "gimp.h"

#include "libgimpbase/gimpprotocol.h"
#include "libgimpbase/gimpwire.h"

#include "gimpgpparams.h"
#include "gimppdb-private.h"
#include "gimpplugin-private.h"
#include "gimppdb_pdb.h"
#include "gimppdbprocedure.h"
#include "gimpplugin-private.h"
#include "gimpplugin_pdb.h"
#include "gimpprocedureconfig-private.h"

#include "libgimp-intl.h"


/**
 * GimpProcedure:
 *
 * Procedures are registered functions which can be run across GIMP ecosystem.
 * They can be created by plug-ins and can then run by the core application
 * when called from menus (or through other interaction depending on specific
 * procedure subclasses).
 *
 * A plug-in can also run procedures created by the core, but also the ones
 * created by other plug-ins (see [class@PDB]).
 **/

enum
{
  PROP_0,
  PROP_PLUG_IN,
  PROP_NAME,
  PROP_PROCEDURE_TYPE,
  N_PROPS
};


typedef struct _GimpProcedurePrivate
{
  GimpPlugIn       *plug_in;

  gchar            *name;
  GimpPDBProcType   proc_type;

  gchar            *image_types;

  gchar            *menu_label;
  GList            *menu_paths;

  GimpIconType      icon_type;
  gpointer          icon_data;

  gchar            *blurb;
  gchar            *help;
  gchar            *help_id;

  gchar            *authors;
  gchar            *copyright;
  gchar            *date;

  gint              sensitivity_mask;

  gint32            n_args;
  GParamSpec      **args;

  gint32            n_aux_args;
  GParamSpec      **aux_args;

  gint32            n_values;
  GParamSpec      **values;

  GimpRunFunc       run_func;
  gpointer          run_data;
  GDestroyNotify    run_data_destroy;

  gboolean          installed;
} GimpProcedurePrivate;


static void                  gimp_procedure_constructed        (GObject              *object);
static void                  gimp_procedure_finalize           (GObject              *object);
static void                  gimp_procedure_set_property       (GObject              *object,
                                                                guint                 property_id,
                                                                const GValue         *value,
                                                                GParamSpec           *pspec);
static void                  gimp_procedure_get_property       (GObject              *object,
                                                                guint                 property_id,
                                                                GValue               *value,
                                                                GParamSpec           *pspec);

static void                  gimp_procedure_real_install       (GimpProcedure        *procedure);
static void                  gimp_procedure_real_uninstall     (GimpProcedure        *procedure);
static GimpValueArray      * gimp_procedure_real_run           (GimpProcedure        *procedure,
                                                                const GimpValueArray *args);
static GimpProcedureConfig * gimp_procedure_real_create_config (GimpProcedure        *procedure,
                                                                GParamSpec          **args,
                                                                gint                  n_args);

static GimpProcedureConfig *
                      gimp_procedure_create_config_with_prefix (GimpProcedure        *procedure,
                                                                const gchar          *prefix,
                                                                GParamSpec          **args,
                                                                gint                  n_args);

static GimpValueArray      * gimp_procedure_new_arguments      (GimpProcedure        *procedure);
static gboolean              gimp_procedure_validate_args      (GimpProcedure        *procedure,
                                                                GParamSpec          **param_specs,
                                                                gint                  n_param_specs,
                                                                GimpValueArray       *args,
                                                                gboolean              return_vals,
                                                                GError              **error);

static void                  gimp_procedure_set_icon           (GimpProcedure        *procedure,
                                                                GimpIconType          icon_type,
                                                                gconstpointer         icon_data);


G_DEFINE_TYPE_WITH_PRIVATE (GimpProcedure, gimp_procedure, G_TYPE_OBJECT)

#define parent_class gimp_procedure_parent_class

static GParamSpec *props[N_PROPS] = { NULL, };


static void
gimp_procedure_class_init (GimpProcedureClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

  object_class->constructed  = gimp_procedure_constructed;
  object_class->finalize     = gimp_procedure_finalize;
  object_class->set_property = gimp_procedure_set_property;
  object_class->get_property = gimp_procedure_get_property;

  klass->install             = gimp_procedure_real_install;
  klass->uninstall           = gimp_procedure_real_uninstall;
  klass->run                 = gimp_procedure_real_run;
  klass->create_config       = gimp_procedure_real_create_config;

  props[PROP_PLUG_IN] =
    g_param_spec_object ("plug-in",
                         "Plug-In",
                         "The GimpPlugIn of this plug-in process",
                         GIMP_TYPE_PLUG_IN,
                         GIMP_PARAM_READWRITE |
                         G_PARAM_CONSTRUCT_ONLY);

  props[PROP_NAME] =
    g_param_spec_string ("name",
                         "Name",
                         "The procedure's name",
                         NULL,
                         GIMP_PARAM_READWRITE |
                         G_PARAM_CONSTRUCT_ONLY);

  props[PROP_PROCEDURE_TYPE] =
    g_param_spec_enum ("procedure-type",
                       "Procedure type",
                       "The procedure's type",
                       GIMP_TYPE_PDB_PROC_TYPE,
                       GIMP_PDB_PROC_TYPE_PLUGIN,
                       GIMP_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY);

  g_object_class_install_properties (object_class, N_PROPS, props);
}

static void
gimp_procedure_init (GimpProcedure *procedure)
{
}

static void
gimp_procedure_constructed (GObject *object)
{
  GimpProcedure        *procedure = GIMP_PROCEDURE (object);
  GimpProcedurePrivate *priv      = gimp_procedure_get_instance_private (procedure);

  G_OBJECT_CLASS (parent_class)->constructed (object);

  g_assert (GIMP_IS_PLUG_IN (priv->plug_in));
  g_assert (priv->name != NULL);

  gimp_procedure_set_sensitivity_mask (procedure, GIMP_PROCEDURE_SENSITIVE_ALWAYS);
}

static void
gimp_procedure_finalize (GObject *object)
{
  GimpProcedure        *procedure = GIMP_PROCEDURE (object);
  GimpProcedurePrivate *priv      = gimp_procedure_get_instance_private (procedure);
  gint                  i;

  if (priv->run_data_destroy)
    priv->run_data_destroy (priv->run_data);

  g_clear_object  (&priv->plug_in);

  g_clear_pointer (&priv->name,        g_free);
  g_clear_pointer (&priv->image_types, g_free);
  g_clear_pointer (&priv->menu_label,  g_free);
  g_clear_pointer (&priv->blurb,       g_free);
  g_clear_pointer (&priv->help,        g_free);
  g_clear_pointer (&priv->help_id,     g_free);
  g_clear_pointer (&priv->authors,     g_free);
  g_clear_pointer (&priv->copyright,   g_free);
  g_clear_pointer (&priv->date,        g_free);

  g_list_free_full (priv->menu_paths, g_free);
  priv->menu_paths = NULL;

  gimp_procedure_set_icon (procedure, GIMP_ICON_TYPE_ICON_NAME, NULL);

  if (priv->args)
    {
      for (i = 0; i < priv->n_args; i++)
        g_param_spec_unref (priv->args[i]);

      g_clear_pointer (&priv->args, g_free);
    }

  if (priv->aux_args)
    {
      for (i = 0; i < priv->n_aux_args; i++)
        g_param_spec_unref (priv->aux_args[i]);

      g_clear_pointer (&priv->aux_args, g_free);
    }

  if (priv->values)
    {
      for (i = 0; i < priv->n_values; i++)
        g_param_spec_unref (priv->values[i]);

      g_clear_pointer (&priv->values, g_free);
    }

  G_OBJECT_CLASS (parent_class)->finalize (object);
}

static void
gimp_procedure_set_property (GObject      *object,
                             guint         property_id,
                             const GValue *value,
                             GParamSpec   *pspec)
{
  GimpProcedure        *procedure = GIMP_PROCEDURE (object);
  GimpProcedurePrivate *priv      = gimp_procedure_get_instance_private (procedure);

  switch (property_id)
    {
    case PROP_PLUG_IN:
      g_set_object (&priv->plug_in, g_value_get_object (value));
      break;

    case PROP_NAME:
      priv->name = g_value_dup_string (value);
      break;

    case PROP_PROCEDURE_TYPE:
      priv->proc_type = g_value_get_enum (value);
      break;

    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
      break;
    }
}

static void
gimp_procedure_get_property (GObject    *object,
                             guint       property_id,
                             GValue     *value,
                             GParamSpec *pspec)
{
  GimpProcedure        *procedure = GIMP_PROCEDURE (object);
  GimpProcedurePrivate *priv      = gimp_procedure_get_instance_private (procedure);

  switch (property_id)
    {
    case PROP_PLUG_IN:
      g_value_set_object (value, priv->plug_in);
      break;

    case PROP_NAME:
      g_value_set_string (value, priv->name);
      break;

    case PROP_PROCEDURE_TYPE:
      g_value_set_enum (value, priv->proc_type);
      break;

    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
      break;
    }
}

static void
gimp_procedure_install_icon (GimpProcedure *procedure)
{
  GimpIconType  icon_type;
  guint8       *icon_data        = NULL;
  gsize         icon_data_length = 0;
  GBytes       *icon_bytes       = NULL;

  icon_type = gimp_procedure_get_icon_type (procedure);

  switch (icon_type)
    {
    case GIMP_ICON_TYPE_ICON_NAME:
      {
        icon_data = (guint8 *) gimp_procedure_get_icon_name (procedure);
        if (icon_data)
          icon_bytes = g_bytes_new_static (icon_data,
                                           strlen ((gchar *) icon_data) + 1);
      }
      break;

    case GIMP_ICON_TYPE_PIXBUF:
      {
        GdkPixbuf *pixbuf = gimp_procedure_get_icon_pixbuf (procedure);

        if (pixbuf)
          {
            if (gdk_pixbuf_save_to_buffer (pixbuf,
                                           (gchar **) &icon_data, &icon_data_length,
                                           "png", NULL, NULL))
              icon_bytes = g_bytes_new_take (icon_data, icon_data_length);
          }
      }
      break;

    case GIMP_ICON_TYPE_IMAGE_FILE:
      {
        GFile *file = gimp_procedure_get_icon_file (procedure);

        if (file)
          {
            icon_data        = (guchar *) g_file_get_uri (file);
            icon_data_length = strlen ((gchar *) icon_data) + 1;
            icon_bytes       = g_bytes_new_take (icon_data, icon_data_length);
          }
      }
      break;
    }

  if (icon_bytes)
    _gimp_pdb_set_proc_icon (gimp_procedure_get_name (procedure),
                             icon_type, icon_bytes);
  g_bytes_unref (icon_bytes);
}

static void
gimp_procedure_real_install (GimpProcedure *procedure)
{
  GimpProcedurePrivate  *priv;
  GParamSpec           **args;
  GParamSpec           **return_vals;
  gint                   n_args        = 0;
  gint                   n_return_vals = 0;
  GList                 *list;
  GimpPlugIn            *plug_in;
  GPProcInstall          proc_install;
  gint                   i;

  priv = gimp_procedure_get_instance_private (procedure);

  g_return_if_fail (priv->installed == FALSE);

  args        = gimp_procedure_get_arguments (procedure, &n_args);
  return_vals = gimp_procedure_get_return_values (procedure, &n_return_vals);

  proc_install.name          = (gchar *) gimp_procedure_get_name (procedure);
  proc_install.type          = gimp_procedure_get_proc_type (procedure);
  proc_install.n_params      = n_args;
  proc_install.n_return_vals = n_return_vals;
  proc_install.params        = g_new0 (GPParamDef, n_args);
  proc_install.return_vals   = g_new0 (GPParamDef, n_return_vals);

  for (i = 0; i < n_args; i++)
    {
      _gimp_param_spec_to_gp_param_def (args[i],
                                        &proc_install.params[i], FALSE);
    }

  for (i = 0; i < n_return_vals; i++)
    {
      _gimp_param_spec_to_gp_param_def (return_vals[i],
                                        &proc_install.return_vals[i], FALSE);
    }

  plug_in = gimp_procedure_get_plug_in (procedure);

  if (! gp_proc_install_write (_gimp_plug_in_get_write_channel (plug_in),
                               &proc_install, plug_in))
    gimp_quit ();

  g_free (proc_install.params);
  g_free (proc_install.return_vals);

  gimp_procedure_install_icon (procedure);

  if (priv->image_types)
    {
      _gimp_pdb_set_proc_image_types (gimp_procedure_get_name (procedure),
                                      priv->image_types);
    }

  if (priv->menu_label)
    {
      _gimp_pdb_set_proc_menu_label (gimp_procedure_get_name (procedure),
                                     priv->menu_label);
    }

  _gimp_pdb_set_proc_sensitivity_mask (gimp_procedure_get_name (procedure),
                                       priv->sensitivity_mask);

  for (list = gimp_procedure_get_menu_paths (procedure);
       list;
       list = g_list_next (list))
    {
      _gimp_pdb_add_proc_menu_path (gimp_procedure_get_name (procedure),
                                    list->data);
    }

  if (priv->blurb ||
      priv->help  ||
      priv->help_id)
    {
      _gimp_pdb_set_proc_documentation (gimp_procedure_get_name (procedure),
                                        priv->blurb,
                                        priv->help,
                                        priv->help_id);
    }

  if (priv->authors   ||
      priv->copyright ||
      priv->date)
    {
      _gimp_pdb_set_proc_attribution (gimp_procedure_get_name (procedure),
                                      priv->authors,
                                      priv->copyright,
                                      priv->date);
    }

  priv->installed = TRUE;
}

static void
gimp_procedure_real_uninstall (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv = gimp_procedure_get_instance_private (procedure);
  GimpPlugIn           *plug_in;
  GPProcUninstall       proc_uninstall;

  g_return_if_fail (priv->installed == TRUE);

  proc_uninstall.name = (gchar *) gimp_procedure_get_name (procedure);

  plug_in = gimp_procedure_get_plug_in (procedure);

  if (! gp_proc_uninstall_write (_gimp_plug_in_get_write_channel (plug_in),
                                 &proc_uninstall, plug_in))
    gimp_quit ();

  priv->installed = FALSE;
}

static GimpValueArray *
gimp_procedure_real_run (GimpProcedure        *procedure,
                         const GimpValueArray *args)
{
  GimpProcedurePrivate *priv     = gimp_procedure_get_instance_private (procedure);
  GimpPlugIn           *plug_in;
  GimpProcedureConfig  *config;
  GimpImage            *image    = NULL;
  GimpRunMode           run_mode = GIMP_RUN_NONINTERACTIVE;
  GimpValueArray       *retvals;
  GimpPDBStatusType     status   = GIMP_PDB_EXECUTION_ERROR;

  if (gimp_value_array_length (args) > 0 &&
      G_VALUE_HOLDS_ENUM (gimp_value_array_index (args, 0)))
    {
      run_mode = GIMP_VALUES_GET_ENUM (args, 0);

      if (gimp_value_array_length (args) > 1 &&
          GIMP_VALUE_HOLDS_IMAGE (gimp_value_array_index (args, 1)))
        image = GIMP_VALUES_GET_IMAGE (args, 1);
    }

  config = _gimp_procedure_create_run_config (procedure);
  _gimp_procedure_config_begin_run (config, image, run_mode, args, NULL);

  retvals = priv->run_func (procedure, config, priv->run_data);

  if (retvals != NULL                       &&
      gimp_value_array_length (retvals) > 0 &&
      G_VALUE_HOLDS_ENUM (gimp_value_array_index (retvals, 0)))
    status = GIMP_VALUES_GET_ENUM (retvals, 0);

  _gimp_procedure_config_end_run (config, status);

  /* This is debug printing to help plug-in developers figure out best
   * practices.
   */
  plug_in = gimp_procedure_get_plug_in (procedure);
  if (G_OBJECT (config)->ref_count > 1 &&
      _gimp_plug_in_manage_memory_manually (plug_in))
    g_printerr ("%s: ERROR: the GimpProcedureConfig object was refed "
                "by plug-in, it MUST NOT do that!\n", G_STRFUNC);

  g_object_unref (config);

  return retvals;
}

static GimpProcedureConfig *
gimp_procedure_real_create_config (GimpProcedure  *procedure,
                                   GParamSpec    **args,
                                   gint            n_args)
{
  return gimp_procedure_create_config_with_prefix (procedure,
                                                   "GimpProcedureConfigRun",
                                                   args, n_args);
}

static GimpProcedureConfig *
gimp_procedure_create_config_with_prefix (GimpProcedure  *procedure,
                                          const gchar    *prefix,
                                          GParamSpec    **args,
                                          gint            n_args)
{
  GimpProcedurePrivate *priv = gimp_procedure_get_instance_private (procedure);
  gchar                *type_name;
  GType                 type;

  type_name = g_strdup_printf ("%s-%s", prefix,
                               gimp_procedure_get_name (procedure));

  type = g_type_from_name (type_name);

  if (! type)
    {
      GParamSpec **config_args;
      gint         n_config_args;

      n_config_args = n_args + priv->n_aux_args;

      config_args = g_new0 (GParamSpec *, n_config_args);

      memcpy (config_args,
              args,
              n_args * sizeof (GParamSpec *));
      memcpy (config_args + n_args,
              priv->aux_args,
              priv->n_aux_args * sizeof (GParamSpec *));

      type = gimp_config_type_register (GIMP_TYPE_PROCEDURE_CONFIG,
                                        type_name,
                                        config_args, n_config_args);

      g_free (config_args);
    }

  g_free (type_name);

  return g_object_new (type,
                       "procedure", procedure,
                       NULL);
}


/*  public functions  */

/**
 * gimp_procedure_new:
 * @plug_in:   a #GimpPlugIn.
 * @name:      the new procedure's name.
 * @proc_type: the new procedure's #GimpPDBProcType.
 * @run_func:  the run function for the new procedure.
 * @run_data:  user data passed to @run_func.
 * @run_data_destroy: (nullable): free function for @run_data, or %NULL.
 *
 * Creates a new procedure named @name which will call @run_func when
 * invoked.
 *
 * The @name parameter is mandatory and should be unique, or it will
 * overwrite an already existing procedure (overwrite procedures only
 * if you know what you're doing).
 *
 * @proc_type should be [enum@Gimp.PDBProcType.PLUGIN] for "normal" plug-ins.
 *
 * Using [enum@Gimp.PDBProcType.PERSISTENT] means that the plug-in will
 * add temporary procedures. Therefore, the GIMP core will wait until
 * the %GIMP_PDB_PROC_TYPE_PERSISTENT procedure has called
 * [method@Procedure.persistent_ready], which means that the procedure
 * has done its initialization, installed its temporary procedures and
 * is ready to run.
 *
 * *Not calling [method@Procedure.persistent_ready] from a
 * %GIMP_PDB_PROC_TYPE_PERSISTENT procedure will cause the GIMP core to
 * lock up.*
 *
 * Additionally, a %GIMP_PDB_PROC_TYPE_PERSISTENT procedure with no
 * arguments added is an "automatic" extension that will be
 * automatically started on each GIMP startup.
 *
 * [enum@Gimp.PDBProcType.TEMPORARY] must be used for temporary procedures
 * that are created during a plug-ins lifetime. They must be added to
 * the #GimpPlugIn using [method@PlugIn.add_temp_procedure].
 *
 * @run_func is called via [method@Procedure.run].
 *
 * For %GIMP_PDB_PROC_TYPE_PLUGIN and %GIMP_PDB_PROC_TYPE_PERSISTENT
 * procedures the call of @run_func is basically the lifetime of the
 * plug-in.
 *
 * Returns: a new #GimpProcedure.
 *
 * Since: 3.0
 **/
GimpProcedure *
gimp_procedure_new (GimpPlugIn        *plug_in,
                    const gchar       *name,
                    GimpPDBProcType    proc_type,
                    GimpRunFunc        run_func,
                    gpointer           run_data,
                    GDestroyNotify     run_data_destroy)
{
  GimpProcedure        *procedure;
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PLUG_IN (plug_in), NULL);
  g_return_val_if_fail (gimp_is_canonical_identifier (name), NULL);
  g_return_val_if_fail (proc_type != GIMP_PDB_PROC_TYPE_INTERNAL, NULL);
  g_return_val_if_fail (run_func != NULL, NULL);

  procedure = g_object_new (GIMP_TYPE_PROCEDURE,
                            "plug-in",        plug_in,
                            "name",           name,
                            "procedure-type", proc_type,
                            NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  priv->run_func         = run_func;
  priv->run_data         = run_data;
  priv->run_data_destroy = run_data_destroy;

  return procedure;
}
/**
 * gimp_procedure_get_plug_in:
 * @procedure: A #GimpProcedure.
 *
 * Returns: (transfer none): The #GimpPlugIn given in [ctor@Procedure.new].
 *
 * Since: 3.0
 **/
GimpPlugIn *
gimp_procedure_get_plug_in (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->plug_in;
}

/**
 * gimp_procedure_get_name:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's name given in [ctor@Procedure.new].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_name (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->name;
}

/**
 * gimp_procedure_get_proc_type:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's type given in [ctor@Procedure.new].
 *
 * Since: 3.0
 **/
GimpPDBProcType
gimp_procedure_get_proc_type (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure),
                        GIMP_PDB_PROC_TYPE_PLUGIN);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->proc_type;
}

/**
 * gimp_procedure_set_image_types:
 * @procedure:   A #GimpProcedure.
 * @image_types: The image types this procedure can operate on.
 *
 * This is a comma separated list of image types, or actually drawable
 * types, that this procedure can deal with. Wildcards are possible
 * here, so you could say "RGB\*" instead of "RGB, RGBA" or "\*" for all
 * image types.
 *
 * Supported types are "RGB", "GRAY", "INDEXED" and their variants
 * with alpha.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_image_types (GimpProcedure *procedure,
                                const gchar   *image_types)
{
  GimpProcedurePrivate *priv;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  g_free (priv->image_types);
  priv->image_types = g_strdup (image_types);

  if (priv->installed)
    _gimp_pdb_set_proc_image_types (gimp_procedure_get_name (procedure),
                                    priv->image_types);
}

/**
 * gimp_procedure_get_image_types:
 * @procedure:  A #GimpProcedure.
 *
 * This function retrieves the list of image types the procedure can
 * operate on. See gimp_procedure_set_image_types().
 *
 * Returns: The image types.
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_image_types (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->image_types;
}

/**
 * gimp_procedure_set_sensitivity_mask:
 * @procedure:        A #GimpProcedure.
 * @sensitivity_mask: A binary mask of [flags@Gimp.ProcedureSensitivityMask].
 *
 * Sets the cases when @procedure is supposed to be sensitive or not.
 *
 * Note that it will be used by the core to determine whether to show a
 * procedure as sensitive (hence forbid running it otherwise), yet it
 * will not forbid thid-party plug-ins for instance to run manually your
 * registered procedure. Therefore you should still handle non-supported
 * cases appropriately by returning with %GIMP_PDB_EXECUTION_ERROR and a
 * suitable error message.
 *
 * Similarly third-party plug-ins should verify they are allowed to call
 * a procedure with [method@Procedure.get_sensitivity_mask] when running
 * with dynamic contents.
 *
 * Note that by default, a procedure works on an image with one or more
 * drawables selected. Hence not setting the mask, setting it with 0 or
 * setting it with `GIMP_PROCEDURE_SENSITIVE_DRAWABLE |
 * GIMP_PROCEDURE_SENSITIVE_DRAWABLES` are equivalent.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_sensitivity_mask (GimpProcedure *procedure,
                                     gint           sensitivity_mask)
{
  GimpProcedurePrivate *priv;
  gboolean              success = TRUE;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  if (GIMP_PROCEDURE_GET_CLASS (procedure)->set_sensitivity)
    success = GIMP_PROCEDURE_GET_CLASS (procedure)->set_sensitivity (procedure,
                                                                     sensitivity_mask);

  if (success)
    {
      priv->sensitivity_mask = sensitivity_mask;

      if (priv->installed)
        _gimp_pdb_set_proc_sensitivity_mask (gimp_procedure_get_name (procedure),
                                             priv->sensitivity_mask);
    }
}

/**
 * gimp_procedure_get_sensitivity_mask:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's sensitivity mask given in
 *          [method@Procedure.set_sensitivity_mask].
 *
 * Since: 3.0
 **/
gint
gimp_procedure_get_sensitivity_mask (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), 0);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->sensitivity_mask;
}

/**
 * gimp_procedure_set_menu_label:
 * @procedure:  A #GimpProcedure.
 * @menu_label: The @procedure's menu label.
 *
 * Sets the label to use for the @procedure's menu entry, The
 * location(s) where to register in the menu hierarchy is chosen using
 * gimp_procedure_add_menu_path().
 *
 * Plug-ins are responsible for their own translations. You are expected to send
 * localized strings to GIMP if your plug-in is internationalized.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_menu_label (GimpProcedure *procedure,
                               const gchar   *menu_label)
{
  GimpProcedurePrivate *priv;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
  g_return_if_fail (menu_label != NULL && strlen (menu_label));

  priv = gimp_procedure_get_instance_private (procedure);

  g_clear_pointer (&priv->menu_label, g_free);
  priv->menu_label = g_strdup (menu_label);

  if (priv->installed)
    _gimp_pdb_set_proc_menu_label (gimp_procedure_get_name (procedure),
                                   priv->menu_label);
}

/**
 * gimp_procedure_get_menu_label:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's menu label given in
 *          gimp_procedure_set_menu_label().
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_menu_label (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->menu_label;
}

/**
 * gimp_procedure_add_menu_path:
 * @procedure: A #GimpProcedure.
 * @menu_path: The @procedure's additional menu path.
 *
 * Adds a menu path to the procedure. Only procedures which have a menu
 * label can add a menu path.
 *
 * Menu paths are untranslated paths to known menus and submenus with the
 * syntax `<Prefix>/Path/To/Submenu`, for example `<Image>/Layer/Transform`.
 * GIMP will localize these.
 * Nevertheless you should localize unknown parts of the path. For instance, say
 * you want to create procedure to create customized layers and add a `Create`
 * submenu which you want to localize from your plug-in with gettext. You could
 * call:
 *
 * ```C
 * path = g_build_path ("/", "<Image>/Layer", _("Create"), NULL);
 * gimp_procedure_add_menu_path (procedure, path);
 * g_free (path);
 * ```
 *
 * See also: gimp_plug_in_add_menu_branch().
 *
 * GIMP menus also have a concept of named section. For instance, say you are
 * creating a plug-in which you want to show next to the "Export", "Export As"
 * plug-ins in the File menu. You would add it to the menu path "File/[Export]".
 * If you actually wanted to create a submenu called "[Export]" (with square
 * brackets), double the brackets: "File/[[Export]]"
 *
 * See also: https://gitlab.gnome.org/GNOME/gimp/-/blob/master/menus/image-menu.ui.in.in
 *
 * This function will place your procedure to the bottom of the selected path or
 * section. Order is not assured relatively to other plug-ins.
 *
 * Since: 3.0
 **/
void
gimp_procedure_add_menu_path (GimpProcedure *procedure,
                              const gchar   *menu_path)
{
  GimpProcedurePrivate *priv;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
  g_return_if_fail (menu_path != NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  g_return_if_fail (priv->menu_label != NULL);

  priv->menu_paths = g_list_append (priv->menu_paths, g_strdup (menu_path));

  if (priv->installed)
    _gimp_pdb_add_proc_menu_path (gimp_procedure_get_name (procedure),
                                  menu_path);
}

/**
 * gimp_procedure_get_menu_paths:
 * @procedure: A #GimpProcedure.
 *
 * Returns: (transfer none) (element-type gchar*): the @procedure's
 *          menu paths as added with gimp_procedure_add_menu_path().
 *
 * Since: 3.0
 **/
GList *
gimp_procedure_get_menu_paths (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->menu_paths;
}

/**
 * gimp_procedure_set_icon_name:
 * @procedure: a #GimpProcedure.
 * @icon_name: (nullable): an icon name.
 *
 * Sets the icon for @procedure to the icon referenced by @icon_name.
 *
 * Since: 3.0
 */
void
gimp_procedure_set_icon_name (GimpProcedure *procedure,
                              const gchar   *icon_name)
{
  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  gimp_procedure_set_icon (procedure,
                           GIMP_ICON_TYPE_ICON_NAME,
                           icon_name);
}

/**
 * gimp_procedure_set_icon_pixbuf:
 * @procedure: a #GimpProcedure.
 * @pixbuf:    (nullable): a #GdkPixbuf.
 *
 * Sets the icon for @procedure to @pixbuf.
 *
 * Since: 3.0
 */
void
gimp_procedure_set_icon_pixbuf (GimpProcedure *procedure,
                                GdkPixbuf     *pixbuf)
{
  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
  g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));

  gimp_procedure_set_icon (procedure,
                           GIMP_ICON_TYPE_PIXBUF,
                           pixbuf);
}

/**
 * gimp_procedure_set_icon_file:
 * @procedure: a #GimpProcedure.
 * @file:      (nullable): a #GFile pointing to an image file.
 *
 * Sets the icon for @procedure to the contents of an image file.
 *
 * Since: 3.0
 */
void
gimp_procedure_set_icon_file (GimpProcedure *procedure,
                              GFile         *file)
{
  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
  g_return_if_fail (file == NULL || G_IS_FILE (file));

  gimp_procedure_set_icon (procedure,
                           GIMP_ICON_TYPE_IMAGE_FILE,
                           file);
}

/**
 * gimp_procedure_get_icon_type:
 * @procedure: a #GimpProcedure.
 *
 * Gets the type of data set as @procedure's icon. Depending on the
 * result, you can call the relevant specific function, such as
 * [method@Procedure.get_icon_name].
 *
 * Returns: the #GimpIconType of @procedure's icon.
 *
 * Since: 3.0
 */
GimpIconType
gimp_procedure_get_icon_type (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), -1);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->icon_type;
}

/**
 * gimp_procedure_get_icon_name:
 * @procedure: a #GimpProcedure.
 *
 * Gets the name of the icon if one was set for @procedure.
 *
 * Returns: (nullable): the icon name or %NULL if no icon name was set.
 *
 * Since: 3.0
 */
const gchar *
gimp_procedure_get_icon_name (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  if (priv->icon_type == GIMP_ICON_TYPE_ICON_NAME)
    return (const gchar *) priv->icon_data;

  return NULL;
}

/**
 * gimp_procedure_get_icon_file:
 * @procedure: a #GimpProcedure.
 *
 * Gets the file of the icon if one was set for @procedure.
 *
 * Returns: (nullable) (transfer none): the icon #GFile or %NULL if no
 *          file was set.
 *
 * Since: 3.0
 */
GFile *
gimp_procedure_get_icon_file (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  if (priv->icon_type == GIMP_ICON_TYPE_IMAGE_FILE)
    return (GFile *) priv->icon_data;

  return NULL;
}

/**
 * gimp_procedure_get_icon_pixbuf:
 * @procedure: a #GimpProcedure.
 *
 * Gets the #GdkPixbuf of the icon if an icon was set this way for
 * @procedure.
 *
 * Returns: (nullable) (transfer none): the icon pixbuf or %NULL if no
 *          icon name was set.
 *
 * Since: 3.0
 */
GdkPixbuf *
gimp_procedure_get_icon_pixbuf (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  if (priv->icon_type == GIMP_ICON_TYPE_PIXBUF)
    return (GdkPixbuf *) priv->icon_data;

  return NULL;
}

/**
 * gimp_procedure_set_documentation:
 * @procedure:           A #GimpProcedure.
 * @blurb:               The @procedure's blurb.
 * @help:    (nullable): The @procedure's help text.
 * @help_id: (nullable): The @procedure's help ID.
 *
 * Sets various documentation strings on @procedure:
 *
 * * @blurb is used for instance as the @procedure's tooltip when represented in
 *   the UI such as a menu entry.
 * * @help is a free-form text that's meant as additional documentation for
 *   developers of scripts and plug-ins. If the @blurb and the argument names
 *   and descriptions are enough for a quite self-explanatory procedure, you may
 *   set @help to %NULL, rather than setting an uninformative @help (avoid
 *   setting the same text as @blurb or redundant information).
 *
 * Plug-ins are responsible for their own translations. You are expected to send
 * localized strings of @blurb and @help to GIMP if your plug-in is
 * internationalized.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_documentation (GimpProcedure *procedure,
                                  const gchar   *blurb,
                                  const gchar   *help,
                                  const gchar   *help_id)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  g_clear_pointer (&priv->blurb,   g_free);
  g_clear_pointer (&priv->help,    g_free);
  g_clear_pointer (&priv->help_id, g_free);

  priv->blurb   = g_strdup (blurb);
  priv->help    = g_strdup (help);
  priv->help_id = g_strdup (help_id);

  if (priv->installed)
    _gimp_pdb_set_proc_documentation (gimp_procedure_get_name (procedure),
                                      priv->blurb,
                                      priv->help,
                                      priv->help_id);
}

/**
 * gimp_procedure_get_blurb:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's blurb given in
 * [method@Procedure.set_documentation].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_blurb (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->blurb;
}

/**
 * gimp_procedure_get_help:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's help text given in
 * [method@Procedure.set_documentation].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_help (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->help;
}

/**
 * gimp_procedure_get_help_id:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's help ID given in
 * [method@Procedure.set_documentation].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_help_id (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->help_id;
}

/**
 * gimp_procedure_set_attribution:
 * @procedure: A #GimpProcedure.
 * @authors:   The @procedure's author(s).
 * @copyright: The @procedure's copyright.
 * @date:      The @procedure's date (written or published).
 *
 * Sets various attribution strings on @procedure.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_attribution (GimpProcedure *procedure,
                                const gchar   *authors,
                                const gchar   *copyright,
                                const gchar   *date)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  g_free (priv->authors);
  g_free (priv->copyright);
  g_free (priv->date);

  priv->authors   = g_strdup (authors);
  priv->copyright = g_strdup (copyright);
  priv->date      = g_strdup (date);

  if (priv->installed)
    _gimp_pdb_set_proc_attribution (gimp_procedure_get_name (procedure),
                                    priv->authors,
                                    priv->copyright,
                                    priv->date);
}

/**
 * gimp_procedure_get_authors:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's authors given in [method@Procedure.set_attribution].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_authors (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->authors;
}

/**
 * gimp_procedure_get_copyright:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's copyright given in
 * [method@Procedure.set_attribution].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_copyright (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->copyright;
}

/**
 * gimp_procedure_get_date:
 * @procedure: A #GimpProcedure.
 *
 * Returns: The procedure's date given in [method@Procedure.set_attribution].
 *
 * Since: 3.0
 **/
const gchar *
gimp_procedure_get_date (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return priv->date;
}

/**
 * _gimp_procedure_add_argument:
 * @procedure: the #GimpProcedure.
 * @pspec:     (transfer floating): the argument specification.
 *
 * Add a new argument to @procedure according to @pspec specifications.
 * The arguments will be ordered according to the calls order.
 *
 * If @pspec is floating, ownership will be taken over by @procedure,
 * allowing to pass directly `g*_param_spec_*()` calls as arguments.
 *
 * Returns: (transfer none): the same @pspec or %NULL in case of error.
 *
 * Since: 3.0
 **/
GParamSpec *
_gimp_procedure_add_argument (GimpProcedure *procedure,
                              GParamSpec    *pspec)
{
  GimpProcedurePrivate *priv;

  priv = gimp_procedure_get_instance_private (procedure);
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
  g_return_val_if_fail (gimp_is_canonical_identifier (pspec->name), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  if (gimp_procedure_find_argument (procedure, pspec->name))
    {
      g_warning ("Argument with name '%s' already exists on procedure '%s'",
                 pspec->name,
                 gimp_procedure_get_name (procedure));
      g_param_spec_sink (pspec);
      return NULL;
    }

  if (gimp_procedure_find_aux_argument (procedure, pspec->name))
    {
      g_warning ("Auxiliary argument with name '%s' already exists "
                 "on procedure '%s'",
                 pspec->name,
                 gimp_procedure_get_name (procedure));
      g_param_spec_sink (pspec);
      return NULL;
    }

  priv->args = g_renew (GParamSpec *, priv->args, priv->n_args + 1);

  priv->args[priv->n_args] = pspec;

  g_param_spec_ref_sink (pspec);

  priv->n_args++;

  return pspec;
}

/**
 * _gimp_procedure_add_aux_argument:
 * @procedure: the #GimpProcedure.
 * @pspec:     (transfer full): the argument specification.
 *
 * Add a new auxiliary argument to @procedure according to @pspec
 * specifications.
 *
 * Auxiliary arguments are not passed to the @procedure in run() and
 * are not known to the PDB. They are however members of the
 * #GimpProcedureConfig created by gimp_procedure_create_config() and
 * can be used to persistently store whatever last used values the
 * @procedure wants to remember across invocations
 *
 * Returns: (transfer none): the same @pspec.
 *
 * Since: 3.0
 **/
GParamSpec *
_gimp_procedure_add_aux_argument (GimpProcedure *procedure,
                                  GParamSpec    *pspec)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), pspec);
  g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), pspec);
  g_return_val_if_fail (gimp_is_canonical_identifier (pspec->name), pspec);

  priv = gimp_procedure_get_instance_private (procedure);

  if (gimp_procedure_find_argument (procedure, pspec->name))
    {
      g_warning ("Argument with name '%s' already exists on procedure '%s'",
                 pspec->name,
                 gimp_procedure_get_name (procedure));
      return pspec;
    }

  if (gimp_procedure_find_aux_argument (procedure, pspec->name))
    {
      g_warning ("Auxiliary argument with name '%s' already exists "
                 "on procedure '%s'",
                 pspec->name,
                 gimp_procedure_get_name (procedure));
      return pspec;
    }

  priv->aux_args = g_renew (GParamSpec *, priv->aux_args, priv->n_aux_args + 1);

  priv->aux_args[priv->n_aux_args] = pspec;

  g_param_spec_ref_sink (pspec);

  priv->n_aux_args++;

  return pspec;
}

/**
 * _gimp_procedure_add_return_value:
 * @procedure: the #GimpProcedure.
 * @pspec:     (transfer full): the return value specification.
 *
 * Add a new return value to @procedure according to @pspec
 * specifications.
 *
 * The returned values will be ordered according to the calls order.
 *
 * Returns: (transfer none): the same @pspec.
 *
 * Since: 3.0
 **/
GParamSpec *
_gimp_procedure_add_return_value (GimpProcedure *procedure,
                                  GParamSpec    *pspec)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), pspec);
  g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), pspec);
  g_return_val_if_fail (gimp_is_canonical_identifier (pspec->name), pspec);

  priv = gimp_procedure_get_instance_private (procedure);

  if (gimp_procedure_find_return_value (procedure, pspec->name))
    {
      g_warning ("Return value with name '%s' already exists on procedure '%s'",
                 pspec->name,
                 gimp_procedure_get_name (procedure));
      return pspec;
    }

  priv->values = g_renew (GParamSpec *, priv->values, priv->n_values + 1);

  priv->values[priv->n_values] = pspec;

  g_param_spec_ref_sink (pspec);

  priv->n_values++;

  return pspec;
}

/**
 * gimp_procedure_find_argument:
 * @procedure: A #GimpProcedure
 * @name:      An argument name
 *
 * Searches the @procedure's arguments for a #GParamSpec called @name.
 *
 * Returns: (transfer none): The @procedure's argument with @name if it
 *          exists, or %NULL otherwise.
 *
 * Since: 3.0
 **/
GParamSpec *
gimp_procedure_find_argument (GimpProcedure *procedure,
                              const gchar   *name)
{
  GimpProcedurePrivate *priv;
  gint                  i;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (name != NULL, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  for (i = 0; i < priv->n_args; i++)
    if (! strcmp (name, priv->args[i]->name))
      return priv->args[i];

  return NULL;
}

/**
 * gimp_procedure_find_aux_argument:
 * @procedure: A #GimpProcedure
 * @name:      An auxiliary argument name
 *
 * Searches the @procedure's auxiliary arguments for a #GParamSpec
 * called @name.
 *
 * Returns: (transfer none): The @procedure's auxiliary argument with
 *          @name if it exists, or %NULL otherwise.
 *
 * Since: 3.0
 **/
GParamSpec *
gimp_procedure_find_aux_argument (GimpProcedure *procedure,
                                  const gchar   *name)
{
  GimpProcedurePrivate *priv;
  gint                  i;

  priv = gimp_procedure_get_instance_private (procedure);

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (name != NULL, NULL);

  for (i = 0; i < priv->n_aux_args; i++)
    if (! strcmp (name, priv->aux_args[i]->name))
      return priv->aux_args[i];

  return NULL;
}

/**
 * gimp_procedure_find_return_value:
 * @procedure: A #GimpProcedure
 * @name:      A return value name
 *
 * Searches the @procedure's return values for a #GParamSpec called
 * @name.
 *
 * Returns: (transfer none): The @procedure's return values with @name
 *          if it exists, or %NULL otherwise.
 *
 * Since: 3.0
 **/
GParamSpec *
gimp_procedure_find_return_value (GimpProcedure *procedure,
                                  const gchar   *name)
{
  GimpProcedurePrivate *priv;
  gint                  i;

  priv = gimp_procedure_get_instance_private (procedure);

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (name != NULL, NULL);

  for (i = 0; i < priv->n_values; i++)
    if (! strcmp (name, priv->values[i]->name))
      return priv->values[i];

  return NULL;
}

/**
 * gimp_procedure_get_arguments:
 * @procedure:   A #GimpProcedure.
 * @n_arguments: (out): Returns the number of arguments.
 *
 * Returns: (transfer none) (array length=n_arguments): An array
 *          of @GParamSpec in the order they were added in.
 *
 * Since: 3.0
 **/
GParamSpec **
gimp_procedure_get_arguments (GimpProcedure *procedure,
                              gint          *n_arguments)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (n_arguments != NULL, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  *n_arguments = priv->n_args;

  return priv->args;
}

/**
 * gimp_procedure_get_aux_arguments:
 * @procedure:   A #GimpProcedure.
 * @n_arguments: (out): Returns the number of auxiliary arguments.
 *
 * Returns: (transfer none) (array length=n_arguments): An array
 *          of @GParamSpec in the order they were added in.
 *
 * Since: 3.0
 **/
GParamSpec **
gimp_procedure_get_aux_arguments (GimpProcedure *procedure,
                                  gint          *n_arguments)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (n_arguments != NULL, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  *n_arguments = priv->n_aux_args;

  return priv->aux_args;
}

/**
 * gimp_procedure_get_return_values:
 * @procedure:       A #GimpProcedure.
 * @n_return_values: (out): Returns the number of return values.
 *
 * Returns: (transfer none) (array length=n_return_values): An array
 *          of @GParamSpec in the order they were added in.
 *
 * Since: 3.0
 **/
GParamSpec **
gimp_procedure_get_return_values (GimpProcedure *procedure,
                                  gint          *n_return_values)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (n_return_values != NULL, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  *n_return_values = priv->n_values;

  return priv->values;
}

/**
 * gimp_procedure_set_argument_sync:
 * @procedure: a #GimpProcedure.
 * @arg_name:  the name of one of @procedure's arguments or auxiliary arguments.
 * @sync:      how to sync the argument or auxiliary argument.
 *
 * When the procedure's run() function exits, a #GimpProcedure's arguments
 * or auxiliary arguments can be automatically synced with a #GimpParasite of
 * the #GimpImage the procedure is running on.
 *
 * In order to enable this, set @sync to %GIMP_ARGUMENT_SYNC_PARASITE.
 *
 * Currently, it is possible to sync a string argument of type
 * #GParamSpecString with an image parasite of the same name, for
 * example the "gimp-comment" parasite in file save procedures.
 *
 * Since: 3.0
 **/
void
gimp_procedure_set_argument_sync (GimpProcedure    *procedure,
                                  const gchar      *arg_name,
                                  GimpArgumentSync  sync)
{
  GParamSpec *pspec;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
  g_return_if_fail (arg_name != NULL);

  pspec = gimp_procedure_find_argument (procedure, arg_name);

  if (! pspec)
    pspec = gimp_procedure_find_aux_argument (procedure, arg_name);

  g_return_if_fail (pspec != NULL);

  switch (sync)
    {
    case GIMP_ARGUMENT_SYNC_NONE:
      gegl_param_spec_set_property_key (pspec, "gimp-argument-sync", NULL);
      break;

    case GIMP_ARGUMENT_SYNC_PARASITE:
      gegl_param_spec_set_property_key (pspec, "gimp-argument-sync", "parasite");
      break;
    }
}

/**
 * gimp_procedure_get_argument_sync:
 * @procedure: a #GimpProcedure
 * @arg_name:  the name of one of @procedure's arguments or auxiliary arguments
 *
 * Returns: The #GimpArgumentSync value set with
 *          gimp_procedure_set_argument_sync():
 *
 * Since: 3.0
 **/
GimpArgumentSync
gimp_procedure_get_argument_sync (GimpProcedure *procedure,
                                  const gchar   *arg_name)
{
  GParamSpec       *pspec;
  GimpArgumentSync  sync = GIMP_ARGUMENT_SYNC_NONE;
  const gchar      *value;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), GIMP_ARGUMENT_SYNC_NONE);
  g_return_val_if_fail (arg_name != NULL, GIMP_ARGUMENT_SYNC_NONE);

  pspec = gimp_procedure_find_argument (procedure, arg_name);

  if (! pspec)
    pspec = gimp_procedure_find_aux_argument (procedure, arg_name);

  g_return_val_if_fail (pspec != NULL, GIMP_ARGUMENT_SYNC_NONE);

  value = gegl_param_spec_get_property_key (pspec, "gimp-argument-sync");

  if (value)
    {
      if (! strcmp (value, "parasite"))
        sync = GIMP_ARGUMENT_SYNC_PARASITE;
    }

  return sync;
}

/**
 * gimp_procedure_new_return_values:
 * @procedure: the procedure.
 * @status:    the success status of the procedure run.
 * @error:     (in) (nullable) (transfer full):
 *             an optional #GError. This parameter should be set if
 *             @status is either #GIMP_PDB_EXECUTION_ERROR or
 *             #GIMP_PDB_CALLING_ERROR.
 *
 * Format the expected return values from procedures.
 *
 * Returns: (transfer full): the expected #GimpValueArray as could be returned
 * by a [callback@RunFunc].
 *
 * Since: 3.0
 **/
GimpValueArray *
gimp_procedure_new_return_values (GimpProcedure     *procedure,
                                  GimpPDBStatusType  status,
                                  GError            *error)
{
  GimpProcedurePrivate *priv;
  GimpValueArray       *args;
  GValue                value = G_VALUE_INIT;
  gint                  i;

  g_return_val_if_fail (status != GIMP_PDB_PASS_THROUGH, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  switch (status)
    {
    case GIMP_PDB_SUCCESS:
    case GIMP_PDB_CANCEL:
      g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

      args = gimp_value_array_new (priv->n_values + 1);

      g_value_init (&value, GIMP_TYPE_PDB_STATUS_TYPE);
      g_value_set_enum (&value, status);
      gimp_value_array_append (args, &value);
      g_value_unset (&value);

      for (i = 0; i < priv->n_values; i++)
        {
          GParamSpec *pspec = priv->values[i];

          g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
          g_param_value_set_default (pspec, &value);
          gimp_value_array_append (args, &value);
          g_value_unset (&value);
        }
      break;

    case GIMP_PDB_EXECUTION_ERROR:
    case GIMP_PDB_CALLING_ERROR:
      args = gimp_value_array_new ((error && error->message) ? 2 : 1);

      g_value_init (&value, GIMP_TYPE_PDB_STATUS_TYPE);
      g_value_set_enum (&value, status);
      gimp_value_array_append (args, &value);
      g_value_unset (&value);

      if (error && error->message)
        {
          g_value_init (&value, G_TYPE_STRING);
          g_value_set_string (&value, error->message);
          gimp_value_array_append (args, &value);
          g_value_unset (&value);
        }
      break;

    default:
      g_return_val_if_reached (NULL);
    }

  g_clear_error (&error);

  return args;
}

/**
 * gimp_procedure_run: (skip)
 * @procedure:      the [class@Gimp.Procedure] to run.
 * @first_arg_name: the name of an argument of @procedure or %NULL to
 *                  run @procedure with default arguments.
 * @...:            the value of @first_arg_name and any more argument
 *                  names and values as needed.
 *
 * Runs the procedure named @procedure_name with arguments given as
 * list of `(name, value)` pairs, terminated by %NULL.
 *
 * The order of arguments does not matter and if any argument is missing, its
 * default value will be used. The value type must correspond to the argument
 * type as registered for @procedure_name.
 *
 * Returns: (transfer full): the return values for the procedure call.
 *
 * Since: 3.0
 */
GimpValueArray *
gimp_procedure_run (GimpProcedure *procedure,
                    const gchar   *first_arg_name,
                    ...)
{
  GimpValueArray *return_values;
  va_list         args;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  va_start (args, first_arg_name);

  return_values = gimp_procedure_run_valist (procedure, first_arg_name, args);

  va_end (args);

  return return_values;
}

/**
 * gimp_procedure_run_valist: (skip)
 * @procedure:      the [class@Gimp.Procedure] to run.
 * @first_arg_name: the name of an argument of @procedure or %NULL to
 *                  run @procedure with default arguments.
 * @args            the value of @first_arg_name and any more argument
 *                  names and values as needed.
 *
 * Runs @procedure with arguments names and values, given in the order as passed
 * to [method@Procedure.run].
 *
 * Returns: (transfer full): the return values for the procedure call.
 *
 * Since: 3.0
 */
GimpValueArray *
gimp_procedure_run_valist (GimpProcedure *procedure,
                           const gchar   *first_arg_name,
                           va_list        args)
{
  GimpValueArray      *return_values;
  GimpProcedureConfig *config;
  const gchar         *arg_name;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  config   = gimp_procedure_create_config (procedure);
  arg_name = first_arg_name;

  while (arg_name != NULL)
    {
      GParamSpec *pspec;
      gchar      *error = NULL;
      GValue      value = G_VALUE_INIT;

      pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (config), arg_name);

      if (pspec == NULL)
        {
          g_warning ("%s: %s has no property named '%s'",
                     G_STRFUNC,
                     g_type_name (G_TYPE_FROM_INSTANCE (config)),
                     arg_name);
          g_clear_object (&config);
          return NULL;
        }

      g_value_init (&value, pspec->value_type);
      G_VALUE_COLLECT (&value, args, G_VALUE_NOCOPY_CONTENTS, &error);

      if (error)
        {
          g_warning ("%s: %s", G_STRFUNC, error);
          g_free (error);
          g_clear_object (&config);
          return NULL;
        }

      g_object_set_property (G_OBJECT (config), arg_name, &value);
      g_value_unset (&value);

      arg_name = va_arg (args, const gchar *);
    }

  return_values = gimp_procedure_run_config (procedure, config);
  g_clear_object (&config);

  return return_values;
}

/**
 * gimp_procedure_run_config: (rename-to gimp_procedure_run)
 * @procedure:          the [class@Gimp.Procedure] to run.
 * @config: (nullable): the @procedure's arguments.
 *
 * Runs @procedure, calling the run_func given in [ctor@Procedure.new].
 *
 * Create @config at default values with
 * [method@Gimp.Procedure.create_config] then set any argument you wish
 * to change from defaults with [method@GObject.Object.set].
 *
 * If @config is %NULL, the default arguments of @procedure will be used.
 *
 * Returns: (transfer full): The @procedure's return values.
 *
 * Since: 3.0
 **/
GimpValueArray *
gimp_procedure_run_config (GimpProcedure       *procedure,
                           GimpProcedureConfig *config)
{
  GimpValueArray *return_vals;
  GimpValueArray *args;
  gboolean        free_config = FALSE;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (config == NULL || GIMP_IS_PROCEDURE_CONFIG (config), NULL);
  g_return_val_if_fail (config == NULL || gimp_procedure_config_get_procedure (config) == procedure, NULL);

  if (config == NULL)
    {
      config = gimp_procedure_create_config (procedure);
      free_config = TRUE;
    }

  args = gimp_procedure_new_arguments (procedure);
  _gimp_procedure_config_get_values (config, args);

  return_vals = _gimp_procedure_run_array (procedure, args);

  gimp_value_array_unref (args);

  if (free_config)
    g_object_unref (config);

  return return_vals;
}

/**
 * _gimp_procedure_create_run_config:
 * @procedure: A #GimpProcedure
 *
 * Create a #GimpConfig with properties that match @procedure's arguments, to be
 * used in the run() method for @procedure.
 *
 * This is an internal function to be used only by libgimp code.
 *
 * Returns: (transfer full): The new #GimpConfig.
 *
 * Since: 3.0
 **/
GimpProcedureConfig *
_gimp_procedure_create_run_config (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return GIMP_PROCEDURE_GET_CLASS (procedure)->create_config (procedure,
                                                              priv->args,
                                                              priv->n_args);
}

GimpValueArray *
_gimp_procedure_run_array (GimpProcedure  *procedure,
                           GimpValueArray *args)
{
  GimpProcedurePrivate *priv;
  GimpValueArray       *return_vals;
  GError               *error = NULL;
  gint                  i;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
  g_return_val_if_fail (args != NULL, NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  if (! gimp_procedure_validate_args (procedure,
                                      priv->args,
                                      priv->n_args,
                                      args, FALSE, &error))
    {
      return_vals = gimp_procedure_new_return_values (procedure,
                                                      GIMP_PDB_CALLING_ERROR,
                                                      error);
      return return_vals;
    }

  /*  add missing args with default values  */
  if (gimp_value_array_length (args) < priv->n_args)
    {
      GimpProcedureConfig *config;
      GObjectClass        *config_class = NULL;
      GimpValueArray      *complete;

      /*  if saved defaults exist, they override GParamSpec  */
      config = _gimp_procedure_create_run_config (procedure);
      if (gimp_procedure_config_load_default (config, NULL))
        config_class = G_OBJECT_GET_CLASS (config);
      else
        g_clear_object (&config);

      complete = gimp_value_array_new (priv->n_args);

      for (i = 0; i < priv->n_args; i++)
        {
          GParamSpec *pspec = priv->args[i];
          GValue      value = G_VALUE_INIT;

          g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));

          if (i < gimp_value_array_length (args))
            {
              GValue *orig = gimp_value_array_index (args, i);

              g_value_copy (orig, &value);
            }
          else if (config &&
                   g_object_class_find_property (config_class, pspec->name))
            {
              g_object_get_property (G_OBJECT (config), pspec->name,
                                     &value);
            }
          else
            {
              g_param_value_set_default (pspec, &value);
            }

          gimp_value_array_append (complete, &value);
          g_value_unset (&value);
        }

      g_clear_object (&config);

      /*  call the procedure  */
      return_vals = GIMP_PROCEDURE_GET_CLASS (procedure)->run (procedure,
                                                               complete);
      gimp_value_array_unref (complete);
    }
  else
    {
      /*  call the procedure  */
      return_vals = GIMP_PROCEDURE_GET_CLASS (procedure)->run (procedure,
                                                               args);
    }

  if (! return_vals)
    {
      g_warning ("%s: no return values, shouldn't happen", G_STRFUNC);

      error = g_error_new (0, 0,
                           _("Procedure '%s' returned no return values"),
                           gimp_procedure_get_name (procedure));

      return_vals = gimp_procedure_new_return_values (procedure,
                                                      GIMP_PDB_EXECUTION_ERROR,
                                                      error);
    }

  return return_vals;
}

/**
 * gimp_procedure_persistent_ready:
 * @procedure: A #GimpProcedure
 *
 * Notify the main GIMP application that the persistent procedure has
 * been properly initialized and is ready to run.
 *
 * This function _must_ be called from every procedure's [callback@RunFunc]
 * that was created as [enum@Gimp.PDBProcType.PERSISTENT].
 *
 * Subsequently, extensions can process temporary procedure run
 * requests using either [method@PlugIn.persistent_enable] or
 * [method@PlugIn.persistent_process].
 *
 * See also: [ctor@Procedure.new].
 *
 * Since: 3.0
 **/
void
gimp_procedure_persistent_ready (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;
  GimpPlugIn           *plug_in;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  g_return_if_fail (priv->proc_type == GIMP_PDB_PROC_TYPE_PERSISTENT);

  plug_in = gimp_procedure_get_plug_in (procedure);

  if (! gp_extension_ack_write (_gimp_plug_in_get_write_channel (plug_in),
                                plug_in))
    gimp_quit ();
}

/**
 * gimp_procedure_create_config:
 * @procedure: A #GimpProcedure
 *
 * Create a #GimpConfig with properties that match @procedure's arguments, to be
 * used in [method@Procedure.run_config] method.
 *
 * Returns: (transfer full): The new #GimpConfig.
 *
 * Since: 3.0
 **/
GimpProcedureConfig *
gimp_procedure_create_config (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  return gimp_procedure_create_config_with_prefix (procedure,
                                                   "GimpProcedureConfig",
                                                   priv->args,
                                                   priv->n_args);
}

/**
 * gimp_procedure_is_internal:
 * @procedure: A #GimpProcedure
 *
 * Provide the information if @procedure is an internal procedure. Only
 * a procedure looked up in the [class@Gimp.PDB] can be internal.
 * Procedures created by a plug-in in particular are never internal.
 *
 * Returns: Whether @procedure is an internal procedure or not.
 *
 * Since: 3.0
 **/
gboolean
gimp_procedure_is_internal (GimpProcedure *procedure)
{
  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), FALSE);

  if (GIMP_IS_PDB_PROCEDURE (procedure))
    {
      GimpProcedurePrivate *priv = gimp_procedure_get_instance_private (procedure);

      return (priv->proc_type == GIMP_PDB_PROC_TYPE_INTERNAL);
    }
  else
    {
      return FALSE;
    }
}

/**
 * _gimp_procedure_get_ref_count:
 * @procedure: A #GimpProcedure
 *
 * Internal function to count the number of reference held by this
 * procedure inside its list of arguments's defaults.
 *
 * Returns: a reference count, which you will probably have to multiply
 *          by 2, if a config object has been created too.
 *
 * Since: 3.0
 **/
gint
_gimp_procedure_get_ref_count (GimpProcedure *procedure,
                               GObject       *object)
{
  GimpProcedurePrivate *priv;
  gint                  ref_count = 0;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), 0);

  priv = gimp_procedure_get_instance_private (procedure);
  for (gint i = 0; i < priv->n_args; i++)
    {
      GParamSpec *pspec = priv->args[i];

      if (GIMP_IS_PARAM_SPEC_OBJECT (pspec))
        {
          if (gimp_param_spec_object_has_default (pspec) &&
              gimp_param_spec_object_get_default (pspec) == object)
            ref_count++;
        }
    }

  return ref_count;
}


/*  private functions  */

/**
 * gimp_procedure_new_arguments:
 * @procedure: the #GimpProcedure.
 *
 * Format the expected argument values of procedures, in the order as
 * added with [method@Procedure.add_argument].
 *
 * Returns: (transfer full): the expected #GimpValueArray which could be given as
 *          arguments to run @procedure, with all values set to
 *          defaults. Free with gimp_value_array_unref().
 *
 * Since: 3.0
 **/
static GimpValueArray *
gimp_procedure_new_arguments (GimpProcedure *procedure)
{
  GimpProcedurePrivate *priv;
  GimpValueArray       *args;
  GValue                value = G_VALUE_INIT;
  gint                  i;

  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);

  priv = gimp_procedure_get_instance_private (procedure);

  args = gimp_value_array_new (priv->n_args);

  for (i = 0; i < priv->n_args; i++)
    {
      GParamSpec *pspec = priv->args[i];

      g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
      g_param_value_set_default (pspec, &value);
      gimp_value_array_append (args, &value);
      g_value_unset (&value);
    }

  return args;
}

static gboolean
gimp_procedure_validate_args (GimpProcedure   *procedure,
                              GParamSpec     **param_specs,
                              gint             n_param_specs,
                              GimpValueArray  *args,
                              gboolean         return_vals,
                              GError         **error)
{
  gint i;

  for (i = 0; i < MIN (gimp_value_array_length (args), n_param_specs); i++)
    {
      GValue     *arg       = gimp_value_array_index (args, i);
      GParamSpec *pspec     = param_specs[i];
      GType       arg_type  = G_VALUE_TYPE (arg);
      GType       spec_type = G_PARAM_SPEC_VALUE_TYPE (pspec);

      if (! g_type_is_a (arg_type, spec_type))
        {
          if (return_vals)
            {
              g_set_error (error,
                           GIMP_PDB_ERROR, GIMP_PDB_ERROR_INVALID_RETURN_VALUE,
                           _("Procedure '%s' returned a wrong value type "
                             "for return value '%s' (#%d). "
                             "Expected %s, got %s."),
                           gimp_procedure_get_name (procedure),
                           g_param_spec_get_name (pspec),
                           i + 1, g_type_name (spec_type),
                           g_type_name (arg_type));
            }
          else
            {
              g_set_error (error,
                           GIMP_PDB_ERROR, GIMP_PDB_ERROR_INVALID_ARGUMENT,
                           _("Procedure '%s' has been called with a "
                             "wrong value type for argument '%s' (#%d). "
                             "Expected %s, got %s."),
                           gimp_procedure_get_name (procedure),
                           g_param_spec_get_name (pspec),
                           i + 1, g_type_name (spec_type),
                           g_type_name (arg_type));
            }

          return FALSE;
        }
      else if (! (pspec->flags & GIMP_PARAM_NO_VALIDATE))
        {
          GValue string_value = G_VALUE_INIT;

          g_value_init (&string_value, G_TYPE_STRING);

          if (g_value_type_transformable (arg_type, G_TYPE_STRING))
            g_value_transform (arg, &string_value);
          else
            g_value_set_static_string (&string_value,
                                       "<not transformable to string>");

          if (g_param_value_validate (pspec, arg))
            {
              const gchar *value = g_value_get_string (&string_value);

              if (value == NULL)
                value = "(null)";

              if (return_vals)
                {
                  g_set_error (error,
                               GIMP_PDB_ERROR,
                               GIMP_PDB_ERROR_INVALID_RETURN_VALUE,
                               _("Procedure '%s' returned "
                                 "'%s' as return value '%s' "
                                 "(#%d, type %s). "
                                 "This value is out of range."),
                               gimp_procedure_get_name (procedure),
                               value,
                               g_param_spec_get_name (pspec),
                               i + 1, g_type_name (spec_type));
                }
              else
                {
                  g_set_error (error,
                               GIMP_PDB_ERROR,
                               GIMP_PDB_ERROR_INVALID_ARGUMENT,
                               _("Procedure '%s' has been called with "
                                 "value '%s' for argument '%s' "
                                 "(#%d, type %s). "
                                 "This value is out of range."),
                               gimp_procedure_get_name (procedure),
                               value,
                               g_param_spec_get_name (pspec),
                               i + 1, g_type_name (spec_type));
                }

              g_value_unset (&string_value);

              return FALSE;
            }

          /*  UTT-8 validate all strings  */
          if (G_PARAM_SPEC_TYPE (pspec) == G_TYPE_PARAM_STRING ||
              (G_PARAM_SPEC_TYPE (pspec) == G_TYPE_BOXED &&
               G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_STRV))
            {
              gboolean valid = TRUE;

              if (G_PARAM_SPEC_TYPE (pspec) == G_TYPE_PARAM_STRING)
                {
                  const gchar *string = g_value_get_string (arg);

                  if (string)
                    valid = g_utf8_validate (string, -1, NULL);
                }
              else
                {
                  const gchar **strings = g_value_get_boxed (arg);

                  for (const gchar **sp = strings; sp && *sp && valid; sp++)
                    valid = g_utf8_validate (*sp, -1, NULL);
                }

              if (! valid)
                {
                  if (return_vals)
                    {
                      g_set_error (error,
                                   GIMP_PDB_ERROR,
                                   GIMP_PDB_ERROR_INVALID_RETURN_VALUE,
                                   _("Procedure '%s' returned an "
                                     "invalid UTF-8 string for argument '%s'."),
                                   gimp_procedure_get_name (procedure),
                                   g_param_spec_get_name (pspec));
                    }
                  else
                    {
                      g_set_error (error,
                                   GIMP_PDB_ERROR,
                                   GIMP_PDB_ERROR_INVALID_ARGUMENT,
                                   _("Procedure '%s' has been called with an "
                                     "invalid UTF-8 string for argument '%s'."),
                                   gimp_procedure_get_name (procedure),
                                   g_param_spec_get_name (pspec));
                    }

                  g_value_unset (&string_value);

                  return FALSE;
                }
            }

          g_value_unset (&string_value);
        }
    }

  return TRUE;
}

static void
gimp_procedure_set_icon (GimpProcedure *procedure,
                         GimpIconType   icon_type,
                         gconstpointer  icon_data)
{
  GimpProcedurePrivate *priv;

  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));

  priv = gimp_procedure_get_instance_private (procedure);

  if (icon_data == priv->icon_data)
    return;

  switch (priv->icon_type)
    {
    case GIMP_ICON_TYPE_ICON_NAME:
      g_clear_pointer (&priv->icon_data, g_free);
      break;

    case GIMP_ICON_TYPE_PIXBUF:
    case GIMP_ICON_TYPE_IMAGE_FILE:
      g_clear_object (&priv->icon_data);
      break;
    }

  priv->icon_type = icon_type;

  switch (icon_type)
    {
    case GIMP_ICON_TYPE_ICON_NAME:
      priv->icon_data = g_strdup (icon_data);
      break;

    case GIMP_ICON_TYPE_PIXBUF:
    case GIMP_ICON_TYPE_IMAGE_FILE:
      g_set_object (&priv->icon_data, (GObject *) icon_data);
      break;

    default:
      g_return_if_reached ();
    }

  if (priv->installed)
    gimp_procedure_install_icon (procedure);
}
