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 static void register_lazy_static_resources ();
  42
  43 G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
  44
  45 /**
  46  * SECTION:gresource
  47  * @short_description: Resource framework
  48  * @include: gio/gio.h
  49  *
  50  * Applications and libraries often contain binary or textual data that is really part of the
  51  * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
  52  * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
  53  * manually included as literal strings in the code.
  54  *
  55  * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program
  56  * provide a convenient and efficient alternative to this which has some nice properties. You
  57  * maintain the files as normal files, so its easy to edit them, but during the build the files
  58  * are combined into a binary bundle that is linked into the executable. This means that loading
  59  * the resource files are efficient (as they are already in memory, shared with other instances) and
  60  * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
  61  * also makes it easier to create relocatable applications.
  62  *
  63  * Resource files can also be marked as compresses. Such files will be included in the resource bundle
  64  * in a compressed form, but will be automatically uncompressed when the resource is used. This
  65  * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
  66  *
  67  * Resource files can also be marked to be preprocessed, by setting the value of the
  68  * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
  69  * The only options currently supported are:
  70  *
  71  * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip
  72  * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
  73  * environment variable must be set to the full path to the xmllint executable, or xmllint
  74  * must be in the PATH; otherwise the preprocessing step is skipped.
  75  *
  76  * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert
  77  * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
  78  * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
  79  * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be
  80  * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
  81  * abort.
  82  *
  83  * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program
  84  * which takes an xml file that describes the bundle, and a set of files that the xml references. These
  85  * are combined into a binary resource bundle.
  86  *
  87  * <example id="resource-example"><title>Example resource description</title>
  88  * <programlisting><![CDATA[
  89  * <?xml version="1.0" encoding="UTF-8"?>
  90  * <gresources>
  91  *   <gresource prefix="/org/gtk/Example">
  92  *     <file>data/splashscreen.png</file>
  93  *     <file compressed="true">dialog.ui</file>
  94  *     <file preprocess="xml-stripblanks">menumarkup.xml</file>
  95  *   </gresource>
  96  * </gresources>
  97  * ]]></programlisting></example>
  98  *
  99  * This will create a resource bundle with the following files:
 100  * <programlisting><![CDATA[
 101  * /org/gtk/Example/data/splashscreen.png
 102  * /org/gtk/Example/dialog.ui
 103  * /org/gtk/Example/menumarkup.xml
 104  * ]]></programlisting>
 105  *
 106  * Note that all resources in the process share the same namespace, so use java-style
 107  * path prefixes (like in the above example) to avoid conflicts.
 108  *
 109  * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a
 110  * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
 111  * --generate-header arguments to create a source file and header to link directly into your application.
 112  *
 113  * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
 114  * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
 115  * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
 116  * the resource data.
 117  *
 118  * There are two forms of the generated source, the default version uses the compiler support for constructor
 119  * and destructor functions (where availible) to automatically create and register the #GResource on startup
 120  * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
 121  * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
 122  * even on the minor ones where this is not availible. (Constructor support is availible for at least Win32, MacOS and Linux.)
 123  *
 124  * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
 125  * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
 126  * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
 127  * is for your own resources, and resource data is often used once, during parsing, and then released.
 128  *
 129  * Since: 2.32
 130  */
 131
 132 /**
 133  * g_resource_error_quark:
 134  *
 135  * Gets the #GResource Error Quark.
 136  *
 137  * Return value: a #GQuark.
 138  *
 139  * Since: 2.32
 140  */
 141 GQuark
 142 g_resource_error_quark (void)
 143 {
 144   return g_quark_from_static_string ("g-resource-error-quark");
 145 }
 146
 147 /**
 148  * g_resource_ref:
 149  * @resource: A #GResource.
 150  *
 151  * Atomically increments the reference count of @array by one. This
 152  * function is MT-safe and may be called from any thread.
 153  *
 154  * Returns: The passed in #GResource.
 155  *
 156  * Since: 2.32
 157  **/
 158 GResource *
 159 g_resource_ref (GResource *resource)
 160 {
 161   g_atomic_int_inc (&resource->ref_count);
 162   return resource;
 163 }
 164
 165 /**
 166  * g_resource_unref:
 167  * @resource: A #GResource.
 168  *
 169  * Atomically decrements the reference count of @resource by one. If the
 170  * reference count drops to 0, all memory allocated by the array is
 171  * released. This function is MT-safe and may be called from any
 172  * thread.
 173  *
 174  * Since: 2.32
 175  **/
 176 void
 177 g_resource_unref (GResource *resource)
 178 {
 179   if (g_atomic_int_dec_and_test (&resource->ref_count))
 180     {
 181       gvdb_table_unref (resource->table);
 182       g_free (resource);
 183     }
 184 }
 185
 186 /**
 187  * g_resource_new_from_data:
 188  * @data: A #GBytes.
 189  * @error: return location for a #GError, or %NULL.
 190  *
 191  * Creates a GResource from a reference to the binary resource bundle.
 192  * This will keep a reference to @data while the resource lives, so
 193  * the data should not be modified or freed.
 194  *
 195  * If you want to use this resource in the global resource namespace you need
 196  * to register it with g_resources_register().
 197  *
 198  * Return value: (transfer full): a new #GResource, or %NULL on error.
 199  *
 200  * Since: 2.32
 201  **/
 202 GResource *
 203 g_resource_new_from_data (GBytes *data,
 204                           GError **error)
 205 {
 206   GResource *resource;
 207   GvdbTable *table;
 208
 209   table = gvdb_table_new_from_data (g_bytes_get_data (data, NULL),
 210                                     g_bytes_get_size (data),
 211                                     TRUE,
 212                                     g_bytes_ref (data),
 213                                     (GvdbRefFunc)g_bytes_ref,
 214                                     (GDestroyNotify)g_bytes_unref,
 215                                     error);
 216
 217   if (table == NULL)
 218     return NULL;
 219
 220   resource = g_new0 (GResource, 1);
 221   resource->ref_count = 1;
 222   resource->table = table;
 223
 224   return resource;
 225 }
 226
 227 /**
 228  * g_resource_load:
 229  * @filename: (type filename): the path of a filename to load, in the GLib filename encoding.
 230  * @error: return location for a #GError, or %NULL.
 231  *
 232  * Loads a binary resource bundle and creates a #GResource representation of it, allowing
 233  * you to query it for data.
 234  *
 235  * If you want to use this resource in the global resource namespace you need
 236  * to register it with g_resources_register().
 237  *
 238  * Return value: (transfer full): a new #GResource, or %NULL on error.
 239  *
 240  * Since: 2.32
 241  **/
 242 GResource *
 243 g_resource_load (const gchar *filename,
 244                  GError **error)
 245 {
 246   GResource *resource;
 247   GvdbTable *table;
 248
 249   table = gvdb_table_new (filename, FALSE, error);
 250   if (table == NULL)
 251     return NULL;
 252
 253   resource = g_new0 (GResource, 1);
 254   resource->table = table;
 255
 256   return resource;
 257 }
 258
 259 static gboolean do_lookup (GResource *resource,
 260                            const char *path,
 261                            GResourceLookupFlags lookup_flags,
 262                            gsize *size,
 263                            guint32 *flags,
 264                            const void **data,
 265                            gsize *data_size,
 266                            GError **error)
 267 {
 268   char *free_path = NULL;
 269   gsize path_len;
 270   gboolean res = FALSE;
 271   GVariant *value;
 272
 273   path_len = strlen (path);
 274   if (path[path_len-1] == '/')
 275     {
 276       path = free_path = g_strdup (path);
 277       free_path[path_len-1] = 0;
 278     }
 279
 280   value = gvdb_table_get_value (resource->table, path);
 281
 282   if (value == NULL)
 283     {
 284       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 285                    _("The resource at '%s' does not exist"),
 286                    path);
 287     }
 288   else
 289     {
 290       guint32 _size, _flags;
 291       GVariant *array;
 292
 293       g_variant_get (value, "(uu@ay)",
 294                      &_size,
 295                      &_flags,
 296                      &array);
 297
 298       if (size)
 299         *size = _size;
 300       if (flags)
 301         *flags = _flags;
 302       if (data)
 303         *data = g_variant_get_data (array);
 304       if (data_size)
 305         {
 306           /* Don't report trailing newline that non-compressed files has */
 307           if (_flags & G_RESOURCE_FLAGS_COMPRESSED)
 308             *data_size = g_variant_get_size (array);
 309           else
 310             *data_size = g_variant_get_size (array) - 1;
 311         }
 312       g_variant_unref (array);
 313       g_variant_unref (value);
 314
 315       res = TRUE;
 316     }
 317
 318   g_free (free_path);
 319   return res;
 320 }
 321
 322 /**
 323  * g_resource_open_stream:
 324  * @resource: A #GResource.
 325  * @path: A pathname inside the resource.
 326  * @lookup_flags: A #GResourceLookupFlags.
 327  * @error: return location for a #GError, or %NULL.
 328  *
 329  * Looks for a file at the specified @path in the resource and
 330  * returns a #GInputStream that lets you read the data.
 331  *
 332  * @lookup_flags controls the behaviour of the lookup.
 333  *
 334  * Returns: (transfer full): #GInputStream or %NULL on error.
 335  *     Free the returned object with g_object_unref().
 336  *
 337  * Since: 2.32
 338  **/
 339 GInputStream *
 340 g_resource_open_stream (GResource *resource,
 341                         const char *path,
 342                         GResourceLookupFlags lookup_flags,
 343                         GError **error)
 344 {
 345   const void *data;
 346   gsize data_size;
 347   guint32 flags;
 348   GInputStream *stream, *stream2;
 349
 350   if (!do_lookup (resource, path, lookup_flags, NULL, &flags, &data, &data_size, error))
 351     return NULL;
 352
 353   stream = g_memory_input_stream_new_from_data (data, data_size, NULL);
 354   g_object_set_data_full (G_OBJECT (stream), "g-resource",
 355                           g_resource_ref (resource),
 356                           (GDestroyNotify)g_resource_unref);
 357
 358   if (flags & G_RESOURCE_FLAGS_COMPRESSED)
 359     {
 360       GZlibDecompressor *decompressor =
 361         g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
 362
 363       stream2 = g_converter_input_stream_new (stream, G_CONVERTER (decompressor));
 364       g_object_unref (decompressor);
 365       g_object_unref (stream);
 366       stream = stream2;
 367     }
 368
 369   return stream;
 370 }
 371
 372 /**
 373  * g_resource_lookup_data:
 374  * @resource: A #GResource.
 375  * @path: A pathname inside the resource.
 376  * @lookup_flags: A #GResourceLookupFlags.
 377  * @error: return location for a #GError, or %NULL.
 378  *
 379  * Looks for a file at the specified @path in the resource and
 380  * returns a #GBytes that lets you directly access the data in
 381  * memory.
 382  *
 383  * The data is always followed by a zero byte, so you
 384  * can safely use the data as a C string. However, that byte
 385  * is not included in the size of the GBytes.
 386  *
 387  * For uncompressed resource files this is a pointer directly into
 388  * the resource bundle, which is typically in some readonly data section
 389  * in the program binary. For compressed files we allocate memory on
 390  * the heap and automatically uncompress the data.
 391  *
 392  * @lookup_flags controls the behaviour of the lookup.
 393  *
 394  * Returns: (transfer full): #GBytes or %NULL on error.
 395  *     Free the returned object with g_bytes_unref().
 396  *
 397  * Since: 2.32
 398  **/
 399 GBytes *
 400 g_resource_lookup_data (GResource *resource,
 401                         const char *path,
 402                         GResourceLookupFlags lookup_flags,
 403                         GError **error)
 404 {
 405   const void *data;
 406   guint32 flags;
 407   gsize data_size;
 408   gsize size;
 409
 410   if (!do_lookup (resource, path, lookup_flags, &size, &flags, &data, &data_size, error))
 411     return NULL;
 412
 413   if (flags & G_RESOURCE_FLAGS_COMPRESSED)
 414     {
 415       char *uncompressed, *d;
 416       const char *s;
 417       GConverterResult res;
 418       gsize d_size, s_size;
 419       gsize bytes_read, bytes_written;
 420
 421
 422       GZlibDecompressor *decompressor =
 423         g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
 424
 425       uncompressed = g_malloc (size + 1);
 426
 427       s = data;
 428       s_size = data_size;
 429       d = uncompressed;
 430       d_size = size;
 431
 432       do
 433         {
 434           res = g_converter_convert (G_CONVERTER (decompressor),
 435                                      s, s_size,
 436                                      d, d_size,
 437                                      G_CONVERTER_INPUT_AT_END,
 438                                      &bytes_read,
 439                                      &bytes_written,
 440                                      NULL);
 441           if (res == G_CONVERTER_ERROR)
 442             {
 443               g_free (uncompressed);
 444               g_object_unref (decompressor);
 445
 446               g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_INTERNAL,
 447                            _("The resource at '%s' failed to decompress"),
 448                            path);
 449               return NULL;
 450
 451             }
 452           s += bytes_read;
 453           s_size -= bytes_read;
 454           d += bytes_written;
 455           d_size -= bytes_written;
 456         }
 457       while (res != G_CONVERTER_FINISHED);
 458
 459       uncompressed[size] = 0; /* Zero terminate */
 460
 461       g_object_unref (decompressor);
 462
 463       return g_bytes_new_take (uncompressed, size);
 464     }
 465   else
 466     return g_bytes_new_with_free_func (data, data_size, (GDestroyNotify)g_resource_unref, g_resource_ref (resource));
 467 }
 468
 469 /**
 470  * g_resource_get_info:
 471  * @resource: A #GResource.
 472  * @path: A pathname inside the resource.
 473  * @lookup_flags: A #GResourceLookupFlags.
 474  * @size:  (out) (allow-none): a location to place the length of the contents of the file,
 475  *    or %NULL if the length is not needed
 476  * @flags:  (out) (allow-none): a location to place the flags about the file,
 477  *    or %NULL if the length is not needed
 478  * @error: return location for a #GError, or %NULL.
 479  *
 480  * Looks for a file at the specified @path in the resource and
 481  * if found returns information about it.
 482  *
 483  * @lookup_flags controls the behaviour of the lookup.
 484  *
 485  * Returns: %TRUE if the file was found. %FALSE if there were errors.
 486  *
 487  * Since: 2.32
 488  **/
 489 gboolean
 490 g_resource_get_info (GResource *resource,
 491                      const char *path,
 492                      GResourceLookupFlags lookup_flags,
 493                      gsize *size,
 494                      guint32 *flags,
 495                      GError **error)
 496 {
 497   return do_lookup (resource, path, lookup_flags, size, flags, NULL, NULL, error);
 498 }
 499
 500 /**
 501  * g_resource_enumerate_children:
 502  * @resource: A #GResource.
 503  * @path: A pathname inside the resource.
 504  * @lookup_flags: A #GResourceLookupFlags.
 505  * @error: return location for a #GError, or %NULL.
 506  *
 507  * Returns all the names of children at the specified @path in the resource.
 508  * The return result is a %NULL terminated list of strings which should
 509  * be released with g_strfreev().
 510  *
 511  * @lookup_flags controls the behaviour of the lookup.
 512  *
 513  * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
 514  *
 515  * Since: 2.32
 516  **/
 517 char **
 518 g_resource_enumerate_children (GResource *resource,
 519                                const char *path,
 520                                GResourceLookupFlags lookup_flags,
 521                                GError **error)
 522 {
 523   gchar **children;
 524   gsize path_len;
 525   char *path_with_slash;
 526
 527   if (*path == 0)
 528     {
 529       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 530                    _("The resource at '%s' does not exist"),
 531                    path);
 532       return NULL;
 533     }
 534
 535   path_len = strlen (path);
 536   if (path[path_len-1] != '/')
 537     path_with_slash = g_strconcat (path, "/", NULL);
 538   else
 539     path_with_slash = g_strdup (path);
 540
 541   children = gvdb_table_list (resource->table, path_with_slash);
 542   g_free (path_with_slash);
 543
 544   if (children == NULL)
 545     {
 546       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 547                    _("The resource at '%s' does not exist"),
 548                    path);
 549       return NULL;
 550     }
 551
 552   return children;
 553 }
 554
 555 static GRWLock resources_lock;
 556 static GList *registered_resources;
 557
 558 /* This is updated atomically, so we can append to it and check for NULL outside the
 559    lock, but all other accesses are done under the write lock */
 560 static GStaticResource *lazy_register_resources;
 561
 562 static void
 563 g_resources_register_unlocked (GResource *resource)
 564 {
 565   registered_resources = g_list_prepend (registered_resources,
 566                                         g_resource_ref (resource));
 567 }
 568
 569 static void
 570 g_resources_unregister_unlocked (GResource *resource)
 571 {
 572   if (g_list_find (registered_resources, resource) == NULL)
 573     {
 574       g_warning ("Tried to remove not registred resource");
 575     }
 576   else
 577     {
 578       registered_resources = g_list_remove (registered_resources,
 579                                            resource);
 580       g_resource_unref (resource);
 581     }
 582 }
 583
 584 /**
 585  * g_resources_register:
 586  * @resource: A #GResource.
 587  *
 588  * Registers the resource with the process-global set of resources.
 589  * Once a resource is registered the files in it can be accessed
 590  * with the global resource lookup functions like g_resources_lookup_data().
 591  *
 592  * Since: 2.32
 593  **/
 594 void
 595 g_resources_register (GResource *resource)
 596 {
 597   g_rw_lock_writer_lock (&resources_lock);
 598   g_resources_register_unlocked (resource);
 599   g_rw_lock_writer_unlock (&resources_lock);
 600 }
 601
 602 /**
 603  * g_resources_unregister:
 604  * @resource: A #GResource.
 605  *
 606  * Unregisters the resource from the process-global set of resources.
 607  *
 608  * Since: 2.32
 609  **/
 610 void
 611 g_resources_unregister (GResource *resource)
 612 {
 613   g_rw_lock_writer_lock (&resources_lock);
 614   g_resources_unregister_unlocked (resource);
 615   g_rw_lock_writer_unlock (&resources_lock);
 616 }
 617
 618 /**
 619  * g_resources_open_stream:
 620  * @path: A pathname inside the resource.
 621  * @lookup_flags: A #GResourceLookupFlags.
 622  * @error: return location for a #GError, or %NULL.
 623  *
 624  * Looks for a file at the specified @path in the set of
 625  * globally registred resources and returns a #GInputStream
 626  * that lets you read the data.
 627  *
 628  * @lookup_flags controls the behaviour of the lookup.
 629  *
 630  * Returns: (transfer full): #GInputStream or %NULL on error.
 631  *     Free the returned object with g_object_unref().
 632  *
 633  * Since: 2.32
 634  **/
 635 GInputStream *
 636 g_resources_open_stream (const char *path,
 637                          GResourceLookupFlags lookup_flags,
 638                          GError **error)
 639 {
 640   GInputStream *res = NULL;
 641   GList *l;
 642   GInputStream *stream;
 643
 644   register_lazy_static_resources ();
 645
 646   g_rw_lock_reader_lock (&resources_lock);
 647
 648   for (l = registered_resources; l != NULL; l = l->next)
 649     {
 650       GResource *r = l->data;
 651       GError *my_error = NULL;
 652
 653       stream = g_resource_open_stream (r, path, lookup_flags, &my_error);
 654       if (stream == NULL &&
 655           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 656         {
 657           g_clear_error (&my_error);
 658         }
 659       else
 660         {
 661           if (stream == NULL)
 662             g_propagate_error (error, my_error);
 663           res = stream;
 664           break;
 665         }
 666     }
 667
 668   if (l == NULL)
 669     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 670                  _("The resource at '%s' does not exist"),
 671                  path);
 672
 673   g_rw_lock_reader_unlock (&resources_lock);
 674
 675   return res;
 676 }
 677
 678 /**
 679  * g_resources_lookup_data:
 680  * @path: A pathname inside the resource.
 681  * @lookup_flags: A #GResourceLookupFlags.
 682  * @error: return location for a #GError, or %NULL.
 683  *
 684  * Looks for a file at the specified @path in the set of
 685  * globally registred resources and returns a #GBytes that
 686  * lets you directly access the data in memory.
 687  *
 688  * The data is always followed by a zero byte, so you
 689  * can safely use the data as a C string. However, that byte
 690  * is not included in the size of the GBytes.
 691  *
 692  * For uncompressed resource files this is a pointer directly into
 693  * the resource bundle, which is typically in some readonly data section
 694  * in the program binary. For compressed files we allocate memory on
 695  * the heap and automatically uncompress the data.
 696  *
 697  * @lookup_flags controls the behaviour of the lookup.
 698  *
 699  * Returns: (transfer full): #GBytes or %NULL on error.
 700  *     Free the returned object with g_bytes_unref().
 701  *
 702  * Since: 2.32
 703  **/
 704 GBytes *
 705 g_resources_lookup_data (const char *path,
 706                          GResourceLookupFlags lookup_flags,
 707                          GError **error)
 708 {
 709   GBytes *res = NULL;
 710   GList *l;
 711   GBytes *data;
 712
 713   register_lazy_static_resources ();
 714
 715   g_rw_lock_reader_lock (&resources_lock);
 716
 717   for (l = registered_resources; l != NULL; l = l->next)
 718     {
 719       GResource *r = l->data;
 720       GError *my_error = NULL;
 721
 722       data = g_resource_lookup_data (r, path, lookup_flags, &my_error);
 723       if (data == NULL &&
 724           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 725         {
 726           g_clear_error (&my_error);
 727         }
 728       else
 729         {
 730           if (data == NULL)
 731             g_propagate_error (error, my_error);
 732           res = data;
 733           break;
 734         }
 735     }
 736
 737   if (l == NULL)
 738     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 739                  _("The resource at '%s' does not exist"),
 740                  path);
 741
 742   g_rw_lock_reader_unlock (&resources_lock);
 743
 744   return res;
 745 }
 746
 747 /**
 748  * g_resources_enumerate_children:
 749  * @path: A pathname inside the resource.
 750  * @lookup_flags: A #GResourceLookupFlags.
 751  * @error: return location for a #GError, or %NULL.
 752  *
 753  * Returns all the names of children at the specified @path in the set of
 754  * globally registred resources.
 755  * The return result is a %NULL terminated list of strings which should
 756  * be released with g_strfreev().
 757  *
 758  * @lookup_flags controls the behaviour of the lookup.
 759  *
 760  * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
 761  *
 762  * Since: 2.32
 763  **/
 764 char **
 765 g_resources_enumerate_children (const char *path,
 766                                 GResourceLookupFlags lookup_flags,
 767                                 GError **error)
 768 {
 769   GHashTable *hash = NULL;
 770   GList *l;
 771   char **children;
 772   int i;
 773
 774   register_lazy_static_resources ();
 775
 776   g_rw_lock_reader_lock (&resources_lock);
 777
 778   for (l = registered_resources; l != NULL; l = l->next)
 779     {
 780       GResource *r = l->data;
 781
 782       children = g_resource_enumerate_children (r, path, 0, NULL);
 783
 784       if (children != NULL)
 785         {
 786           if (hash == NULL)
 787             hash = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
 788
 789           for (i = 0; children[i] != NULL; i++)
 790             g_hash_table_insert (hash, children[i], children[i]);
 791           g_free (children);
 792         }
 793     }
 794
 795   g_rw_lock_reader_unlock (&resources_lock);
 796
 797   if (hash == NULL)
 798     {
 799       g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 800                    _("The resource at '%s' does not exist"),
 801                    path);
 802       return NULL;
 803     }
 804   else
 805     {
 806       GHashTableIter iter;
 807       const char *key;
 808       guint n_children;
 809       n_children = g_hash_table_size (hash);
 810       children = g_new (char *, n_children + 1);
 811       i = 0;
 812
 813       g_hash_table_iter_init (&iter, hash);
 814       while (g_hash_table_iter_next (&iter, (gpointer *)&key, NULL))
 815         children[i++] = g_strdup (key);
 816       children[i++] = NULL;
 817
 818       g_hash_table_destroy (hash);
 819
 820       return children;
 821     }
 822 }
 823
 824 /**
 825  * g_resources_get_info:
 826  * @path: A pathname inside the resource.
 827  * @lookup_flags: A #GResourceLookupFlags.
 828  * @size:  (out) (allow-none): a location to place the length of the contents of the file,
 829  *    or %NULL if the length is not needed
 830  * @flags:  (out) (allow-none): a location to place the flags about the file,
 831  *    or %NULL if the length is not needed
 832  * @error: return location for a #GError, or %NULL.
 833  *
 834  * Looks for a file at the specified @path in the set of
 835  * globally registred resources and if found returns information about it.
 836  *
 837  * @lookup_flags controls the behaviour of the lookup.
 838  *
 839  * Returns: %TRUE if the file was found. %FALSE if there were errors.
 840  *
 841  * Since: 2.32
 842  **/
 843 gboolean
 844 g_resources_get_info (const char   *path,
 845                       GResourceLookupFlags lookup_flags,
 846                       gsize        *size,
 847                       guint32      *flags,
 848                       GError      **error)
 849 {
 850   gboolean res = FALSE;
 851   GList *l;
 852   gboolean r_res;
 853
 854   register_lazy_static_resources ();
 855
 856   g_rw_lock_reader_lock (&resources_lock);
 857
 858   for (l = registered_resources; l != NULL; l = l->next)
 859     {
 860       GResource *r = l->data;
 861       GError *my_error = NULL;
 862
 863       r_res = g_resource_get_info (r, path, lookup_flags, size, flags, &my_error);
 864       if (!r_res &&
 865           g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
 866         {
 867           g_clear_error (&my_error);
 868         }
 869       else
 870         {
 871           if (!r_res)
 872             g_propagate_error (error, my_error);
 873           res = r_res;
 874           break;
 875         }
 876     }
 877
 878   if (l == NULL)
 879     g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
 880                  _("The resource at '%s' does not exist"),
 881                  path);
 882
 883   g_rw_lock_reader_unlock (&resources_lock);
 884
 885   return res;
 886 }
 887
 888 /* This code is to handle registration of resources very early, from a constructor.
 889  * At that point we'd like to do minimal work, to avoid ordering issues. For instance,
 890  * we're not allowed to use g_malloc, as the user need to be able to call g_mem_set_vtable
 891  * before the first call to g_malloc.
 892  *
 893  * So, what we do at construction time is that we just register a static structure on
 894  * a list of resources that need to be initialized, and then later, when doing any lookups
 895  * in the global list of registered resources, or when getting a reference to the
 896  * lazily initialized resource we lazily create and register all the GResources on
 897  * the lazy list.
 898  *
 899  * To avoid having to use locks in the constructor, and having to grab the writer lock
 900  * when checking the lazy registering list we update lazy_register_resources in
 901  * a lock-less fashion (atomic prepend-only, atomic replace with NULL). However, all
 902  * operations except:
 903  *  * check if there are any resources to lazily initialize
 904  *  * Add a static resource to the lazy init list
 905  * Do use the full writer lock for protection.
 906  */
 907
 908 static void
 909 register_lazy_static_resources_unlocked ()
 910 {
 911   GStaticResource *list;
 912
 913   do
 914     list = lazy_register_resources;
 915   while (!g_atomic_pointer_compare_and_exchange (&lazy_register_resources, list, NULL));
 916
 917   while (list != NULL)
 918     {
 919       GBytes *bytes = g_bytes_new_static (list->data, list->data_len);
 920       GResource *resource = g_resource_new_from_data (bytes, NULL);
 921       if (resource)
 922         {
 923           g_resources_register_unlocked (resource);
 924           g_atomic_pointer_set (&list->resource, resource);
 925         }
 926       g_bytes_unref (bytes);
 927
 928       list = list->next;
 929     }
 930 }
 931
 932 static void
 933 register_lazy_static_resources ()
 934 {
 935   if (g_atomic_pointer_get (&lazy_register_resources) == NULL)
 936     return;
 937
 938   g_rw_lock_writer_lock (&resources_lock);
 939   register_lazy_static_resources_unlocked ();
 940   g_rw_lock_writer_unlock (&resources_lock);
 941 }
 942
 943 /**
 944  * g_static_resource_init:
 945  * @static_resource: pointer to a static #GStaticResource.
 946  *
 947  * Initializes a GResource from static data using a
 948  * GStaticResource.
 949  *
 950  * This is normally used by code generated by
 951  * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
 952  * not typically used by other code.
 953  *
 954  * Since: 2.32
 955  **/
 956 void
 957 g_static_resource_init (GStaticResource *static_resource)
 958 {
 959   gpointer next;
 960
 961   do
 962     {
 963       next = lazy_register_resources;
 964       static_resource->next = next;
 965     }
 966   while (!g_atomic_pointer_compare_and_exchange (&lazy_register_resources, next, static_resource));
 967 }
 968
 969 /**
 970  * g_static_resource_fini:
 971  * @static_resource: pointer to a static #GStaticResource.
 972  *
 973  * Finalized a GResource initialized by g_static_resource_init ().
 974  *
 975  * This is normally used by code generated by
 976  * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
 977  * not typically used by other code.
 978  *
 979  * Since: 2.32
 980  **/
 981 void
 982 g_static_resource_fini (GStaticResource *static_resource)
 983 {
 984   GResource *resource;
 985
 986   g_rw_lock_writer_lock (&resources_lock);
 987
 988   register_lazy_static_resources_unlocked ();
 989
 990   resource = g_atomic_pointer_get (&static_resource->resource);
 991   if (resource)
 992     {
 993       g_atomic_pointer_set (&static_resource->resource, NULL);
 994       g_resources_unregister_unlocked (resource);
 995       g_resource_unref (resource);
 996     }
 997
 998   g_rw_lock_writer_unlock (&resources_lock);
 999 }
1000
1001 /**
1002  * g_static_resource_get_resource:
1003  * @static_resource: pointer to a static #GStaticResource.
1004  *
1005  * Gets the GResource that was registred by a call to g_static_resource_init ().
1006  *
1007  * This is normally used by code generated by
1008  * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
1009  * not typically used by other code.
1010  *
1011  * Return value:  (transfer none): a #GResource.
1012  *
1013  * Since: 2.32
1014  **/
1015 GResource *
1016 g_static_resource_get_resource  (GStaticResource *static_resource)
1017 {
1018   register_lazy_static_resources ();
1019
1020   return g_atomic_pointer_get (&static_resource->resource);
1021 }