libgimp/gimpproceduraldb_pdb.c

   1 /* LIBGIMP - The GIMP Library
   2  * Copyright (C) 1995-2003 Peter Mattis and Spencer Kimball
   3  *
   4  * gimpproceduraldb_pdb.c
   5  *
   6  * This library is free software: you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 3 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library.  If not, see
  18  * <https://www.gnu.org/licenses/>.
  19  */
  20
  21 /* NOTE: This file is auto-generated by pdbgen.pl */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #include "gimp.h"
  28
  29
  30 /**
  31  * SECTION: gimpproceduraldb
  32  * @title: gimpproceduraldb
  33  * @short_description: Functions for querying and changing procedural database (PDB) entries.
  34  *
  35  * Functions for querying and changing procedural database (PDB)
  36  * entries.
  37  **/
  38
  39
  40 /**
  41  * gimp_procedural_db_temp_name:
  42  *
  43  * Generates a unique temporary PDB name.
  44  *
  45  * This procedure generates a temporary PDB entry name that is
  46  * guaranteed to be unique.
  47  *
  48  * Returns: A unique temporary name for a temporary PDB entry.
  49  **/
  50 gchar *
  51 gimp_procedural_db_temp_name (void)
  52 {
  53   GimpParam *return_vals;
  54   gint nreturn_vals;
  55   gchar *temp_name = NULL;
  56
  57   return_vals = gimp_run_procedure ("gimp-procedural-db-temp-name",
  58                                     &nreturn_vals,
  59                                     GIMP_PDB_END);
  60
  61   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  62     temp_name = g_strdup (return_vals[1].data.d_string);
  63
  64   gimp_destroy_params (return_vals, nreturn_vals);
  65
  66   return temp_name;
  67 }
  68
  69 /**
  70  * gimp_procedural_db_dump:
  71  * @filename: The dump filename.
  72  *
  73  * Dumps the current contents of the procedural database
  74  *
  75  * This procedure dumps the contents of the procedural database to the
  76  * specified file. The file will contain all of the information
  77  * provided for each registered procedure.
  78  *
  79  * Returns: TRUE on success.
  80  **/
  81 gboolean
  82 gimp_procedural_db_dump (const gchar *filename)
  83 {
  84   GimpParam *return_vals;
  85   gint nreturn_vals;
  86   gboolean success = TRUE;
  87
  88   return_vals = gimp_run_procedure ("gimp-procedural-db-dump",
  89                                     &nreturn_vals,
  90                                     GIMP_PDB_STRING, filename,
  91                                     GIMP_PDB_END);
  92
  93   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  94
  95   gimp_destroy_params (return_vals, nreturn_vals);
  96
  97   return success;
  98 }
  99
 100 /**
 101  * gimp_procedural_db_query:
 102  * @name: The regex for procedure name.
 103  * @blurb: The regex for procedure blurb.
 104  * @help: The regex for procedure help.
 105  * @author: The regex for procedure author.
 106  * @copyright: The regex for procedure copyright.
 107  * @date: The regex for procedure date.
 108  * @proc_type: The regex for procedure type: { 'Internal GIMP procedure', 'GIMP Plug-in', 'GIMP Extension', 'Temporary Procedure' }.
 109  * @num_matches: The number of matching procedures.
 110  * @procedure_names: The list of procedure names.
 111  *
 112  * Queries the procedural database for its contents using regular
 113  * expression matching.
 114  *
 115  * This procedure queries the contents of the procedural database. It
 116  * is supplied with seven arguments matching procedures on { name,
 117  * blurb, help, author, copyright, date, procedure type}. This is
 118  * accomplished using regular expression matching. For instance, to
 119  * find all procedures with \"jpeg\" listed in the blurb, all seven
 120  * arguments can be supplied as \".*\", except for the second, which
 121  * can be supplied as \".*jpeg.*\". There are two return arguments for
 122  * this procedure. The first is the number of procedures matching the
 123  * query. The second is a concatenated list of procedure names
 124  * corresponding to those matching the query. If no matching entries
 125  * are found, then the returned string is NULL and the number of
 126  * entries is 0.
 127  *
 128  * Returns: TRUE on success.
 129  **/
 130 gboolean
 131 gimp_procedural_db_query (const gchar   *name,
 132                           const gchar   *blurb,
 133                           const gchar   *help,
 134                           const gchar   *author,
 135                           const gchar   *copyright,
 136                           const gchar   *date,
 137                           const gchar   *proc_type,
 138                           gint          *num_matches,
 139                           gchar       ***procedure_names)
 140 {
 141   GimpParam *return_vals;
 142   gint nreturn_vals;
 143   gboolean success = TRUE;
 144   gint i;
 145
 146   return_vals = gimp_run_procedure ("gimp-procedural-db-query",
 147                                     &nreturn_vals,
 148                                     GIMP_PDB_STRING, name,
 149                                     GIMP_PDB_STRING, blurb,
 150                                     GIMP_PDB_STRING, help,
 151                                     GIMP_PDB_STRING, author,
 152                                     GIMP_PDB_STRING, copyright,
 153                                     GIMP_PDB_STRING, date,
 154                                     GIMP_PDB_STRING, proc_type,
 155                                     GIMP_PDB_END);
 156
 157   *num_matches = 0;
 158   *procedure_names = NULL;
 159
 160   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 161
 162   if (success)
 163     {
 164       *num_matches = return_vals[1].data.d_int32;
 165       if (*num_matches > 0)
 166         {
 167           *procedure_names = g_new0 (gchar *, *num_matches + 1);
 168           for (i = 0; i < *num_matches; i++)
 169             (*procedure_names)[i] = g_strdup (return_vals[2].data.d_stringarray[i]);
 170         }
 171     }
 172
 173   gimp_destroy_params (return_vals, nreturn_vals);
 174
 175   return success;
 176 }
 177
 178 /**
 179  * gimp_procedural_db_proc_exists:
 180  * @procedure_name: The procedure name.
 181  *
 182  * Checks if the specified procedure exists in the procedural database
 183  *
 184  * This procedure checks if the specified procedure is registered in
 185  * the procedural database.
 186  *
 187  * Returns: Whether a procedure of that name is registered.
 188  *
 189  * Since: 2.6
 190  **/
 191 gboolean
 192 gimp_procedural_db_proc_exists (const gchar *procedure_name)
 193 {
 194   GimpParam *return_vals;
 195   gint nreturn_vals;
 196   gboolean exists = FALSE;
 197
 198   return_vals = gimp_run_procedure ("gimp-procedural-db-proc-exists",
 199                                     &nreturn_vals,
 200                                     GIMP_PDB_STRING, procedure_name,
 201                                     GIMP_PDB_END);
 202
 203   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
 204     exists = return_vals[1].data.d_int32;
 205
 206   gimp_destroy_params (return_vals, nreturn_vals);
 207
 208   return exists;
 209 }
 210
 211 /**
 212  * _gimp_procedural_db_proc_info:
 213  * @procedure_name: The procedure name.
 214  * @blurb: A short blurb.
 215  * @help: Detailed procedure help.
 216  * @author: Author(s) of the procedure.
 217  * @copyright: The copyright.
 218  * @date: Copyright date.
 219  * @proc_type: The procedure type.
 220  * @num_args: The number of input arguments.
 221  * @num_values: The number of return values.
 222  *
 223  * Queries the procedural database for information on the specified
 224  * procedure.
 225  *
 226  * This procedure returns information on the specified procedure. A
 227  * short blurb, detailed help, author(s), copyright information,
 228  * procedure type, number of input, and number of return values are
 229  * returned. For specific information on each input argument and return
 230  * value, use the gimp_procedural_db_proc_arg() and
 231  * gimp_procedural_db_proc_val() procedures.
 232  *
 233  * Returns: TRUE on success.
 234  **/
 235 gboolean
 236 _gimp_procedural_db_proc_info (const gchar      *procedure_name,
 237                                gchar           **blurb,
 238                                gchar           **help,
 239                                gchar           **author,
 240                                gchar           **copyright,
 241                                gchar           **date,
 242                                GimpPDBProcType  *proc_type,
 243                                gint             *num_args,
 244                                gint             *num_values)
 245 {
 246   GimpParam *return_vals;
 247   gint nreturn_vals;
 248   gboolean success = TRUE;
 249
 250   return_vals = gimp_run_procedure ("gimp-procedural-db-proc-info",
 251                                     &nreturn_vals,
 252                                     GIMP_PDB_STRING, procedure_name,
 253                                     GIMP_PDB_END);
 254
 255   *blurb = NULL;
 256   *help = NULL;
 257   *author = NULL;
 258   *copyright = NULL;
 259   *date = NULL;
 260   *proc_type = 0;
 261   *num_args = 0;
 262   *num_values = 0;
 263
 264   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 265
 266   if (success)
 267     {
 268       *blurb = g_strdup (return_vals[1].data.d_string);
 269       *help = g_strdup (return_vals[2].data.d_string);
 270       *author = g_strdup (return_vals[3].data.d_string);
 271       *copyright = g_strdup (return_vals[4].data.d_string);
 272       *date = g_strdup (return_vals[5].data.d_string);
 273       *proc_type = return_vals[6].data.d_int32;
 274       *num_args = return_vals[7].data.d_int32;
 275       *num_values = return_vals[8].data.d_int32;
 276     }
 277
 278   gimp_destroy_params (return_vals, nreturn_vals);
 279
 280   return success;
 281 }
 282
 283 /**
 284  * gimp_procedural_db_proc_arg:
 285  * @procedure_name: The procedure name.
 286  * @arg_num: The argument number.
 287  * @arg_type: The type of argument.
 288  * @arg_name: The name of the argument.
 289  * @arg_desc: A description of the argument.
 290  *
 291  * Queries the procedural database for information on the specified
 292  * procedure's argument.
 293  *
 294  * This procedure returns information on the specified procedure's
 295  * argument. The argument type, name, and a description are retrieved.
 296  *
 297  * Returns: TRUE on success.
 298  **/
 299 gboolean
 300 gimp_procedural_db_proc_arg (const gchar     *procedure_name,
 301                              gint             arg_num,
 302                              GimpPDBArgType  *arg_type,
 303                              gchar          **arg_name,
 304                              gchar          **arg_desc)
 305 {
 306   GimpParam *return_vals;
 307   gint nreturn_vals;
 308   gboolean success = TRUE;
 309
 310   return_vals = gimp_run_procedure ("gimp-procedural-db-proc-arg",
 311                                     &nreturn_vals,
 312                                     GIMP_PDB_STRING, procedure_name,
 313                                     GIMP_PDB_INT32, arg_num,
 314                                     GIMP_PDB_END);
 315
 316   *arg_type = 0;
 317   *arg_name = NULL;
 318   *arg_desc = NULL;
 319
 320   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 321
 322   if (success)
 323     {
 324       *arg_type = return_vals[1].data.d_int32;
 325       *arg_name = g_strdup (return_vals[2].data.d_string);
 326       *arg_desc = g_strdup (return_vals[3].data.d_string);
 327     }
 328
 329   gimp_destroy_params (return_vals, nreturn_vals);
 330
 331   return success;
 332 }
 333
 334 /**
 335  * gimp_procedural_db_proc_val:
 336  * @procedure_name: The procedure name.
 337  * @val_num: The return value number.
 338  * @val_type: The type of return value.
 339  * @val_name: The name of the return value.
 340  * @val_desc: A description of the return value.
 341  *
 342  * Queries the procedural database for information on the specified
 343  * procedure's return value.
 344  *
 345  * This procedure returns information on the specified procedure's
 346  * return value. The return value type, name, and a description are
 347  * retrieved.
 348  *
 349  * Returns: TRUE on success.
 350  **/
 351 gboolean
 352 gimp_procedural_db_proc_val (const gchar     *procedure_name,
 353                              gint             val_num,
 354                              GimpPDBArgType  *val_type,
 355                              gchar          **val_name,
 356                              gchar          **val_desc)
 357 {
 358   GimpParam *return_vals;
 359   gint nreturn_vals;
 360   gboolean success = TRUE;
 361
 362   return_vals = gimp_run_procedure ("gimp-procedural-db-proc-val",
 363                                     &nreturn_vals,
 364                                     GIMP_PDB_STRING, procedure_name,
 365                                     GIMP_PDB_INT32, val_num,
 366                                     GIMP_PDB_END);
 367
 368   *val_type = 0;
 369   *val_name = NULL;
 370   *val_desc = NULL;
 371
 372   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 373
 374   if (success)
 375     {
 376       *val_type = return_vals[1].data.d_int32;
 377       *val_name = g_strdup (return_vals[2].data.d_string);
 378       *val_desc = g_strdup (return_vals[3].data.d_string);
 379     }
 380
 381   gimp_destroy_params (return_vals, nreturn_vals);
 382
 383   return success;
 384 }
 385
 386 /**
 387  * _gimp_procedural_db_get_data:
 388  * @identifier: The identifier associated with data.
 389  * @bytes: The number of bytes in the data.
 390  * @data: A byte array containing data.
 391  *
 392  * Returns data associated with the specified identifier.
 393  *
 394  * This procedure returns any data which may have been associated with
 395  * the specified identifier. The data is a variable length array of
 396  * bytes. If no data has been associated with the identifier, an error
 397  * is returned.
 398  *
 399  * Returns: TRUE on success.
 400  **/
 401 gboolean
 402 _gimp_procedural_db_get_data (const gchar  *identifier,
 403                               gint         *bytes,
 404                               guint8      **data)
 405 {
 406   GimpParam *return_vals;
 407   gint nreturn_vals;
 408   gboolean success = TRUE;
 409
 410   return_vals = gimp_run_procedure ("gimp-procedural-db-get-data",
 411                                     &nreturn_vals,
 412                                     GIMP_PDB_STRING, identifier,
 413                                     GIMP_PDB_END);
 414
 415   *bytes = 0;
 416   *data = NULL;
 417
 418   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 419
 420   if (success)
 421     {
 422       *bytes = return_vals[1].data.d_int32;
 423       *data = g_new (guint8, *bytes);
 424       memcpy (*data,
 425               return_vals[2].data.d_int8array,
 426               *bytes * sizeof (guint8));
 427     }
 428
 429   gimp_destroy_params (return_vals, nreturn_vals);
 430
 431   return success;
 432 }
 433
 434 /**
 435  * gimp_procedural_db_get_data_size:
 436  * @identifier: The identifier associated with data.
 437  *
 438  * Returns size of data associated with the specified identifier.
 439  *
 440  * This procedure returns the size of any data which may have been
 441  * associated with the specified identifier. If no data has been
 442  * associated with the identifier, an error is returned.
 443  *
 444  * Returns: The number of bytes in the data.
 445  **/
 446 gint
 447 gimp_procedural_db_get_data_size (const gchar *identifier)
 448 {
 449   GimpParam *return_vals;
 450   gint nreturn_vals;
 451   gint bytes = 0;
 452
 453   return_vals = gimp_run_procedure ("gimp-procedural-db-get-data-size",
 454                                     &nreturn_vals,
 455                                     GIMP_PDB_STRING, identifier,
 456                                     GIMP_PDB_END);
 457
 458   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
 459     bytes = return_vals[1].data.d_int32;
 460
 461   gimp_destroy_params (return_vals, nreturn_vals);
 462
 463   return bytes;
 464 }
 465
 466 /**
 467  * _gimp_procedural_db_set_data:
 468  * @identifier: The identifier associated with data.
 469  * @bytes: The number of bytes in the data.
 470  * @data: A byte array containing data.
 471  *
 472  * Associates the specified identifier with the supplied data.
 473  *
 474  * This procedure associates the supplied data with the provided
 475  * identifier. The data may be subsequently retrieved by a call to
 476  * 'procedural-db-get-data'.
 477  *
 478  * Returns: TRUE on success.
 479  **/
 480 gboolean
 481 _gimp_procedural_db_set_data (const gchar  *identifier,
 482                               gint          bytes,
 483                               const guint8 *data)
 484 {
 485   GimpParam *return_vals;
 486   gint nreturn_vals;
 487   gboolean success = TRUE;
 488
 489   return_vals = gimp_run_procedure ("gimp-procedural-db-set-data",
 490                                     &nreturn_vals,
 491                                     GIMP_PDB_STRING, identifier,
 492                                     GIMP_PDB_INT32, bytes,
 493                                     GIMP_PDB_INT8ARRAY, data,
 494                                     GIMP_PDB_END);
 495
 496   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
 497
 498   gimp_destroy_params (return_vals, nreturn_vals);
 499
 500   return success;
 501 }