gio/gresource.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2011 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Authors: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #include "gresource.h"
  28 #include <gvdb/gvdb-reader.h>
  29 #include <gi18n.h>
  30 #include <gio/gmemoryinputstream.h>
  31 #include <gio/gzlibdecompressor.h>
  32 #include <gio/gconverterinputstream.h>
  33
  34 struct _GResource
  35 {
  36   int ref_count;
  37
  38   GvdbTable *table;
  39 };
  40
  41 G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
  42
  43 /**
  44  * SECTION:gresource
  45  * @short_description: Resource framework
  46  * @include: gio/gio.h
  47  *
  48  * Applications and libraries often contain binary or textual data that is really part of the
  49  * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
  50  * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
  51  * manually included as literal strings in the code.
  52  *
  53  * The #GResource API and the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
  54  * provide a convenient and efficient alternative to this which has some nice properties. You
  55  * maintain the files as normal files, so its easy to edit them, but during the build the files
  56  * are combined into a binary bundle that is linked into the executable. This means that loading
  57  * the resource files are efficient (as they are already in memory, shared with other instances) and
  58  * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
  59  * also makes it easier to create relocatable applications.
  60  *
  61  * Resource files can also be marked as compresses. Such files will be included in the resource bundle
  62  * in a compressed form, but will be automatically uncompressed when the resource is used. This
  63  * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
  64  *
  65  * Resource bundles are created by the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
  66  * which takes an xml file that describes the bundle, and a set of files that the xml references. These
  67  * are combined into a binary resource bundle.
  68  *
  69  * <example id="resource-example"><title>Example resource description</title>
  70  * <programlisting><![CDATA[
  71  * <?xml version="1.0" encoding="UTF-8"?>
  72  * <gresources>
  73  *   <gresource prefix="/org/gtk/Example">
  74  *     <file>data/splashscreen.png</file>
  75  *     <file compressed="true">dialog.ui</file>
  76  *     <file>menumarkup.xml</file>
  77  *   </gresource>
  78  * </gresources>
  79  * ]]></programlisting></example>
  80  *
  81  * This will create a resource bundle with the following files:
  82  * <programlisting><![CDATA[
  83  * /org/gtk/Example/data/splashscreen.png
  84  * /org/gtk/Example/dialog.ui
  85  * /org/gtk/Example/menumarkup.xml
  86  * ]]></programlisting>
  87  *
  88  * Note that all resources in the process share the same namespace, so use java-style
  89  * path prefixes (like in the above example) to avoid conflicts.
  90  *
  91  * You can then use <link linkend="glib-compile-schemas">glib-compile-resources</link> to compile the xml to a
  92  * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
  93  * --generate-header arguments to create a source file and header to link directly into your application.
  94  *
  95  * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
  96  * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
  97  * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
  98  * the resource data.
  99  *
 100  * There are two forms of the generated source, the default version uses the compiler support for constructor
 101  * and destructor functions (where availible) to automatically create and register the #GResource on startup
 102  * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
 103  * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
 104  * even on the minor ones where this is not availible. (Constructor support is availible for at least Win32, MacOS and Linux.)
 105  *
 106  * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
 107  * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
 108  * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
 109  * is for your own resources, and resource data is often used once, during parsing, and then released.
 110  *
 111  * Since: 2.32
 112  */
 113
 114 /**
 115  * g_resource_error_quark:
 116  *
 117  * Gets the #GResource Error Quark.
 118  *
 119  * Return value: a #GQuark.
 120  *
 121  * Since: 2.32
 122  */
 123 GQuark
 124 g_resource_error_quark (void)
 125 {
 126   return g_quark_from_static_string ("g-resource-error-quark");
 127 }
 128
 129 /**
 130  * g_resource_ref:
 131  * @resource: A #GResource.
 132  *
 133  * Atomically increments the reference count of @array by one. This
 134  * function is MT-safe and may be called from any thread.
 135  *
 136  * Returns: The passed in #GResource.
 137  *
 138  * Since: 2.32
 139  **/
 140 GResource *
 141 g_resource_ref (GResource *resource)
 142 {
 143   g_atomic_int_inc (&resource->ref_count);
 144   return resource;
 145 }
 146
 147 /**
 148  * g_resource_unref:
 149  * @resource: A #GResource.
 150  *
 151  * Atomically decrements the reference count of @resource by one. If the
 152  * reference count drops to 0, all memory allocated by the array is
 153  * released. This function is MT-safe and may be called from any
 154  * thread.
 155  *
 156  * Since: 2.32
 157  **/
 158 void
 159 g_resource_unref (GResource *resource)
 160 {
 161   if (g_atomic_int_dec_and_test (&resource->ref_count))
 162     {
 163       gvdb_table_unref (resource->table);
 164       g_free (resource);
 165     }
 166 }
 167
 168 /**
 169  * g_resource_new_from_data:
 170  * @data: A #GBytes.
 171  * @error: return location for a #GError, or %NULL.
 172  *
 173  * Creates a GResource from a reference to the binary resource bundle.
 174  * This will keep a reference to @data while the resource lives, so
 175  * the data should not be modified or freed.
 176  *
 177  * If you want to use this resource in the global resource namespace you need
 178  * to register it with g_resources_register().
 179  *
 180  * Return value: (transfer full): a new #GResource, or %NULL on error.
 181  *
 182  * Since: 2.32
 183  **/
 184 GResource *
 185 g_resource_new_from_data (GBytes *data,
 186                           GError **error)
 187 {
 188   GResource *resource;
 189   GvdbTable *table;
 190
 191   table = gvdb_table_new_from_data (g_bytes_get_data (data, NULL),
 192                                     g_bytes_get_size (data),
 193                                     TRUE,
 194                                     g_bytes_ref (data),
 195                                     (GvdbRefFunc)g_bytes_ref,
 196                                     (GDestroyNotify)g_bytes_unref,
 197                                     error);
 198
 199   if (table == NULL)
 200     return NULL;
 201
 202   resource = g_new0 (GResource, 1);
 203   resource->ref_count = 1;
 204   resource->table = table;
 205
 206   return resource;
 207 }
 208
 209 /**
 210  * g_resource_load:
 211  * @filename: (type filename): the path of a filename to load, in the GLib filename encoding.
 212  * @error: return location for a #GError, or %NULL.
 213  *
 214  * Loads a binary resource bundle and creates a #GResource representation of it, allowing
 215  * you to query it for data.
 216  *
 217  * If you want to use this resource in the global resource namespace you need
 218  * to register it with g_resources_register().
 219  *
 220  * Return value: (transfer full): a new #GResource, or %NULL on error.
 221  *
 222  * Since: 2.32
 223  **/
 224 GResource *
 225 g_resource_load (const gchar *filename,
 226                  GError **error)
 227 {
 228   GResource *resource;
 229   GvdbTable *table;
 230
 231   table = gvdb_table_new (filename, FALSE, error);
 232   if (table == NULL)
 233     return NULL;
 234
 235   resource = g_new0 (GResource, 1);
 236   resource->table = table;
 237
 238   return resource;
 239 }
 240
 241 static gboolean do_lookup (GResource *resource,
 242                            const char *path,
 243                            GResourceLookupFlags lookup_flags,
 244                            gsize *size,
 245                            guint32 *flags,
 246                            const void **data,
 247                            gsize *data_size,
 248                            GError **error)
 249 {
 250   char *free_path = NULL;
 251   gsize path_len;
 252   gboolean res = FALSE;
 253   GVariant *value;
 254
 255   path_len = strlen (path);
 256   if (path[path_len-1] == '/')
 257     {
 258       path = free_path = g_strdup (path);
 259       free_path[path_len-1] = 0;
 260     }
 261
 262   value = gvdb_table_get_value (resource->table, path);
 263
 264   if (value == NULL)
 265     {
 266       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 267                    _("The resource at '%s' does not exist"),
 268                    path);
 269     }
 270   else
 271     {
 272       guint32 _size, _flags;
 273       GVariant *array;
 274
 275       g_variant_get (value, "(uu@ay)",
 276                      &_size,
 277                      &_flags,
 278                      &array);
 279
 280       if (!res)
 281         {
 282           if (size)
 283             *size = _size;
 284           if (flags)
 285             *flags = _flags;
 286           if (data)
 287             *data = g_variant_get_data (array);
 288           if (data_size)
 289             {
 290               /* Don't report trailing newline that non-compressed files has */
 291               if (_flags & G_RESOURCE_FLAGS_COMPRESSED)
 292                 *data_size = g_variant_get_size (array);
 293               else
 294                 *data_size = g_variant_get_size (array) - 1;
 295             }
 296           res = TRUE;
 297         }
 298     }
 299
 300   g_free (free_path);
 301   return res;
 302 }
 303
 304 /**
 305  * g_resource_open_stream:
 306  * @resource: A #GResource.
 307  * @path: A pathname inside the resource.
 308  * @lookup_flags: A #GResourceLookupFlags.
 309  * @error: return location for a #GError, or %NULL.
 310  *
 311  * Looks for a file at the specified @path in the resource and
 312  * returns a #GInputStream that lets you read the data.
 313  *
 314  * @lookup_flags controls the behaviour of the lookup.
 315  *
 316  * Returns: (transfer full): #GInputStream or %NULL on error.
 317  *     Free the returned object with g_object_unref().
 318  *
 319  * Since: 2.32
 320  **/
 321 GInputStream *
 322 g_resource_open_stream (GResource *resource,
 323                         const char *path,
 324                         GResourceLookupFlags lookup_flags,
 325                         GError **error)
 326 {
 327   const void *data;
 328   gsize data_size;
 329   guint32 flags;
 330   GInputStream *stream, *stream2;
 331
 332   if (!do_lookup (resource, path, lookup_flags, NULL, &flags, &data, &data_size, error))
 333     return NULL;
 334
 335   stream = g_memory_input_stream_new_from_data (data, data_size, NULL);
 336   g_object_set_data_full (G_OBJECT (stream), "g-resource",
 337                           g_resource_ref (resource),
 338                           (GDestroyNotify)g_resource_unref);
 339
 340   if (flags & G_RESOURCE_FLAGS_COMPRESSED)
 341     {
 342       GZlibDecompressor *decompressor =
 343         g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
 344
 345       stream2 = g_converter_input_stream_new (stream, G_CONVERTER (decompressor));
 346       g_object_unref (decompressor);
 347       g_object_unref (stream);
 348       stream = stream2;
 349     }
 350
 351   return stream;
 352 }
 353
 354 /**
 355  * g_resource_lookup_data:
 356  * @resource: A #GResource.
 357  * @path: A pathname inside the resource.
 358  * @lookup_flags: A #GResourceLookupFlags.
 359  * @error: return location for a #GError, or %NULL.
 360  *
 361  * Looks for a file at the specified @path in the resource and
 362  * returns a #GBytes that lets you directly access the data in
 363  * memory.
 364  *
 365  * The data is always followed by a zero byte, so you
 366  * can safely use the data as a C string. However, that byte
 367  * is not included in the size of the GBytes.
 368  *
 369  * For uncompressed resource files this is a pointer directly into
 370  * the resource bundle, which is typically in some readonly data section
 371  * in the program binary. For compressed files we allocate memory on
 372  * the heap and automatically uncompress the data.
 373  *
 374  * @lookup_flags controls the behaviour of the lookup.
 375  *
 376  * Returns: (transfer full): #GBytes or %NULL on error.
 377  *     Free the returned object with g_bytes_unref().
 378  *
 379  * Since: 2.32
 380  **/
 381 GBytes *
 382 g_resource_lookup_data (GResource *resource,
 383                         const char *path,
 384                         GResourceLookupFlags lookup_flags,
 385                         GError **error)
 386 {
 387   const void *data;
 388   guint32 flags;
 389   gsize data_size;
 390   gsize size;
 391
 392   if (!do_lookup (resource, path, lookup_flags, &size, &flags, &data, &data_size, error))
 393     return NULL;
 394
 395   if (flags & G_RESOURCE_FLAGS_COMPRESSED)
 396     {
 397       char *uncompressed, *d;
 398       const char *s;
 399       GConverterResult res;
 400       gsize d_size, s_size;
 401       gsize bytes_read, bytes_written;
 402
 403
 404       GZlibDecompressor *decompressor =
 405         g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
 406
 407       uncompressed = g_malloc (size + 1);
 408
 409       s = data;
 410       s_size = data_size;
 411       d = uncompressed;
 412       d_size = size;
 413
 414       do
 415         {
 416           res = g_converter_convert (G_CONVERTER (decompressor),
 417                                      s, s_size,
 418                                      d, d_size,
 419                                      G_CONVERTER_INPUT_AT_END,
 420                                      &bytes_read,
 421                                      &bytes_written,
 422                                      NULL);
 423           if (res == G_CONVERTER_ERROR)
 424             {
 425               g_free (uncompressed);
 426               g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_INTERNAL,
 427                            _("The resource at '%s' failed to decompress"),
 428                            path);
 429               return NULL;
 430
 431             }
 432           s += bytes_read;
 433           s_size -= bytes_read;
 434           d += bytes_written;
 435           d_size -= bytes_written;
 436         }
 437       while (res != G_CONVERTER_FINISHED);
 438
 439       uncompressed[size] = 0; /* Zero terminate */
 440
 441       return g_bytes_new_take (uncompressed, size);
 442     }
 443   else
 444     return g_bytes_new_with_free_func (data, data_size, (GDestroyNotify)g_resource_unref, g_resource_ref (resource));
 445 }
 446
 447 /**
 448  * g_resource_get_info:
 449  * @resource: A #GResource.
 450  * @path: A pathname inside the resource.
 451  * @lookup_flags: A #GResourceLookupFlags.
 452  * @size:  (out) (allow-none): a location to place the length of the contents of the file,
 453  *    or %NULL if the length is not needed
 454  * @flags:  (out) (allow-none): a location to place the flags about the file,
 455  *    or %NULL if the length is not needed
 456  * @error: return location for a #GError, or %NULL.
 457  *
 458  * Looks for a file at the specified @path in the resource and
 459  * if found returns information about it.
 460  *
 461  * @lookup_flags controls the behaviour of the lookup.
 462  *
 463  * Returns: %TRUE if the file was found. %FALSE if there were errors.
 464  *
 465  * Since: 2.32
 466  **/
 467 gboolean
 468 g_resource_get_info (GResource *resource,
 469                      const char *path,
 470                      GResourceLookupFlags lookup_flags,
 471                      gsize *size,
 472                      guint32 *flags,
 473                      GError **error)
 474 {
 475   return do_lookup (resource, path, lookup_flags, size, flags, NULL, NULL, error);
 476 }
 477
 478 /**
 479  * g_resource_enumerate_children:
 480  * @resource: A #GResource.
 481  * @path: A pathname inside the resource.
 482  * @lookup_flags: A #GResourceLookupFlags.
 483  * @error: return location for a #GError, or %NULL.
 484  *
 485  * Returns all the names of children at the specified @path in the resource.
 486  * The return result is a %NULL terminated list of strings which should
 487  * be released with g_strfreev().
 488  *
 489  * @lookup_flags controls the behaviour of the lookup.
 490  *
 491  * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
 492  *
 493  * Since: 2.32
 494  **/
 495 char **
 496 g_resource_enumerate_children (GResource *resource,
 497                                const char *path,
 498                                GResourceLookupFlags lookup_flags,
 499                                GError **error)
 500 {
 501   gchar **children;
 502   gsize path_len;
 503   char *path_with_slash;
 504
 505   if (*path == 0)
 506     {
 507       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 508                    _("The resource at '%s' does not exist"),
 509                    path);
 510       return NULL;
 511     }
 512
 513   path_len = strlen (path);
 514   if (path[path_len-1] != '/')
 515     path_with_slash = g_strconcat (path, "/", NULL);
 516   else
 517     path_with_slash = g_strdup (path);
 518
 519   children = gvdb_table_list (resource->table, path_with_slash);
 520   g_free (path_with_slash);
 521
 522   if (children == NULL)
 523     {
 524       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 525                    _("The resource at '%s' does not exist"),
 526                    path);
 527       return NULL;
 528     }
 529
 530   return children;
 531 }
 532
 533 static GRWLock resources_lock;
 534 static GList *registered_resources;
 535
 536 /**
 537  * g_resources_register:
 538  * @resource: A #GResource.
 539  *
 540  * Registers the resource with the process-global set of resources.
 541  * Once a resource is registered the files in it can be accessed
 542  * with the global resource lookup functions like g_resources_lookup_data().
 543  *
 544  * Since: 2.32
 545  **/
 546 void
 547 g_resources_register (GResource *resource)
 548 {
 549   g_rw_lock_writer_lock (&resources_lock);
 550
 551   registered_resources = g_list_prepend (registered_resources,
 552                                         g_resource_ref (resource));
 553
 554   g_rw_lock_writer_unlock (&resources_lock);
 555 }
 556
 557 /**
 558  * g_resources_unregister:
 559  * @resource: A #GResource.
 560  *
 561  * Unregisters the resource from the process-global set of resources.
 562  *
 563  * Since: 2.32
 564  **/
 565 void
 566 g_resources_unregister (GResource *resource)
 567 {
 568   g_rw_lock_writer_lock (&resources_lock);
 569
 570   if (g_list_find (registered_resources, resource) == NULL)
 571     {
 572       g_warning ("Tried to remove not registred resource");
 573     }
 574   else
 575     {
 576       registered_resources = g_list_remove (registered_resources,
 577                                            resource);
 578       g_resource_unref (resource);
 579     }
 580
 581   g_rw_lock_writer_unlock (&resources_lock);
 582 }
 583
 584 /**
 585  * g_resources_open_stream:
 586  * @path: A pathname inside the resource.
 587  * @lookup_flags: A #GResourceLookupFlags.
 588  * @error: return location for a #GError, or %NULL.
 589  *
 590  * Looks for a file at the specified @path in the set of
 591  * globally registred resources and returns a #GInputStream
 592  * that lets you read the data.
 593  *
 594  * @lookup_flags controls the behaviour of the lookup.
 595  *
 596  * Returns: (transfer full): #GInputStream or %NULL on error.
 597  *     Free the returned object with g_object_unref().
 598  *
 599  * Since: 2.32
 600  **/
 601 GInputStream *
 602 g_resources_open_stream (const char *path,
 603                          GResourceLookupFlags lookup_flags,
 604                          GError **error)
 605 {
 606   GInputStream *res = NULL;
 607   GList *l;
 608   GInputStream *stream;
 609
 610   g_rw_lock_reader_lock (&resources_lock);
 611
 612   for (l = registered_resources; l != NULL; l = l->next)
 613     {
 614       GResource *r = l->data;
 615       GError *my_error = NULL;
 616
 617       stream = g_resource_open_stream (r, path, lookup_flags, &my_error);
 618       if (stream == NULL &&
 619           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 620         {
 621           g_clear_error (&my_error);
 622         }
 623       else
 624         {
 625           if (stream == NULL)
 626             g_propagate_error (error, my_error);
 627           res = stream;
 628           break;
 629         }
 630     }
 631
 632   if (l == NULL)
 633     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 634                  _("The resource at '%s' does not exist"),
 635                  path);
 636
 637   g_rw_lock_reader_unlock (&resources_lock);
 638
 639   return res;
 640 }
 641
 642 /**
 643  * g_resources_lookup_data:
 644  * @path: A pathname inside the resource.
 645  * @lookup_flags: A #GResourceLookupFlags.
 646  * @error: return location for a #GError, or %NULL.
 647  *
 648  * Looks for a file at the specified @path in the set of
 649  * globally registred resources and returns a #GBytes that
 650  * lets you directly access the data in memory.
 651  *
 652  * The data is always followed by a zero byte, so you
 653  * can safely use the data as a C string. However, that byte
 654  * is not included in the size of the GBytes.
 655  *
 656  * For uncompressed resource files this is a pointer directly into
 657  * the resource bundle, which is typically in some readonly data section
 658  * in the program binary. For compressed files we allocate memory on
 659  * the heap and automatically uncompress the data.
 660  *
 661  * @lookup_flags controls the behaviour of the lookup.
 662  *
 663  * Returns: (transfer full): #GBytes or %NULL on error.
 664  *     Free the returned object with g_bytes_unref().
 665  *
 666  * Since: 2.32
 667  **/
 668 GBytes *
 669 g_resources_lookup_data (const char *path,
 670                          GResourceLookupFlags lookup_flags,
 671                          GError **error)
 672 {
 673   GBytes *res = NULL;
 674   GList *l;
 675   GBytes *data;
 676
 677   g_rw_lock_reader_lock (&resources_lock);
 678
 679   for (l = registered_resources; l != NULL; l = l->next)
 680     {
 681       GResource *r = l->data;
 682       GError *my_error = NULL;
 683
 684       data = g_resource_lookup_data (r, path, lookup_flags, &my_error);
 685       if (data == NULL &&
 686           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 687         {
 688           g_clear_error (&my_error);
 689         }
 690       else
 691         {
 692           if (data == NULL)
 693             g_propagate_error (error, my_error);
 694           res = data;
 695           break;
 696         }
 697     }
 698
 699   if (l == NULL)
 700     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 701                  _("The resource at '%s' does not exist"),
 702                  path);
 703
 704   g_rw_lock_reader_unlock (&resources_lock);
 705
 706   return res;
 707 }
 708
 709 /**
 710  * g_resources_enumerate_children:
 711  * @path: A pathname inside the resource.
 712  * @lookup_flags: A #GResourceLookupFlags.
 713  * @error: return location for a #GError, or %NULL.
 714  *
 715  * Returns all the names of children at the specified @path in the set of
 716  * globally registred resources.
 717  * The return result is a %NULL terminated list of strings which should
 718  * be released with g_strfreev().
 719  *
 720  * @lookup_flags controls the behaviour of the lookup.
 721  *
 722  * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
 723  *
 724  * Since: 2.32
 725  **/
 726 char **
 727 g_resources_enumerate_children (const char *path,
 728                                 GResourceLookupFlags lookup_flags,
 729                                 GError **error)
 730 {
 731   GHashTable *hash = NULL;
 732   GList *l;
 733   char **children;
 734   int i;
 735
 736   g_rw_lock_reader_lock (&resources_lock);
 737
 738   for (l = registered_resources; l != NULL; l = l->next)
 739     {
 740       GResource *r = l->data;
 741
 742       children = g_resource_enumerate_children (r, path, 0, NULL);
 743
 744       if (children != NULL)
 745         {
 746           if (hash == NULL)
 747             hash = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
 748
 749           for (i = 0; children[i] != NULL; i++)
 750             g_hash_table_insert (hash, children[i], children[i]);
 751           g_free (children);
 752         }
 753     }
 754
 755   g_rw_lock_reader_unlock (&resources_lock);
 756
 757   if (hash == NULL)
 758     {
 759       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 760                    _("The resource at '%s' does not exist"),
 761                    path);
 762       return NULL;
 763     }
 764   else
 765     {
 766       GHashTableIter iter;
 767       const char *key;
 768       guint n_children;
 769       n_children = g_hash_table_size (hash);
 770       children = g_new (char *, n_children + 1);
 771       i = 0;
 772
 773       g_hash_table_iter_init (&iter, hash);
 774       while (g_hash_table_iter_next (&iter, (gpointer *)&key, NULL))
 775         children[i++] = g_strdup (key);
 776       children[i++] = NULL;
 777
 778       g_hash_table_destroy (hash);
 779
 780       return children;
 781     }
 782 }
 783
 784 /**
 785  * g_resources_get_info:
 786  * @path: A pathname inside the resource.
 787  * @lookup_flags: A #GResourceLookupFlags.
 788  * @size:  (out) (allow-none): a location to place the length of the contents of the file,
 789  *    or %NULL if the length is not needed
 790  * @flags:  (out) (allow-none): a location to place the flags about the file,
 791  *    or %NULL if the length is not needed
 792  * @error: return location for a #GError, or %NULL.
 793  *
 794  * Looks for a file at the specified @path in the set of
 795  * globally registred resources and if found returns information about it.
 796  *
 797  * @lookup_flags controls the behaviour of the lookup.
 798  *
 799  * Returns: %TRUE if the file was found. %FALSE if there were errors.
 800  *
 801  * Since: 2.32
 802  **/
 803 gboolean
 804 g_resources_get_info (const char   *path,
 805                       GResourceLookupFlags lookup_flags,
 806                       gsize        *size,
 807                       guint32      *flags,
 808                       GError      **error)
 809 {
 810   gboolean res = FALSE;
 811   GList *l;
 812   gboolean r_res;
 813
 814   g_rw_lock_reader_lock (&resources_lock);
 815
 816   for (l = registered_resources; l != NULL; l = l->next)
 817     {
 818       GResource *r = l->data;
 819       GError *my_error = NULL;
 820
 821       r_res = g_resource_get_info (r, path, lookup_flags, size, flags, &my_error);
 822       if (!r_res &&
 823           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 824         {
 825           g_clear_error (&my_error);
 826         }
 827       else
 828         {
 829           if (!r_res)
 830             g_propagate_error (error, my_error);
 831           res = r_res;
 832           break;
 833         }
 834     }
 835
 836   if (l == NULL)
 837     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 838                  _("The resource at '%s' does not exist"),
 839                  path);
 840
 841   g_rw_lock_reader_unlock (&resources_lock);
 842
 843   return res;
 844 }