1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2011 Red Hat, Inc
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.
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.
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.
20 * Authors: Alexander Larsson <alexl@redhat.com>
27 #include "gresource.h"
28 #include <gvdb/gvdb-reader.h>
30 #include <gio/gmemoryinputstream.h>
31 #include <gio/gzlibdecompressor.h>
32 #include <gio/gconverterinputstream.h>
41 G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
45 * @short_description: Resource framework
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.
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.
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.
65 * Resource files can also be marked to be preprocessed, by setting the value of the
66 * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
67 * The only option currently supported is
68 * <literal>xml-stripblanks</literal> which will use <literal>xmllint</literal> to strip
69 * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
70 * environment variable must be set to the full path to the xmllint executable;
71 * otherwise the preprocessing step is skipped.
73 * Resource bundles are created by the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
74 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
75 * are combined into a binary resource bundle.
77 * <example id="resource-example"><title>Example resource description</title>
78 * <programlisting><![CDATA[
79 * <?xml version="1.0" encoding="UTF-8"?>
81 * <gresource prefix="/org/gtk/Example">
82 * <file>data/splashscreen.png</file>
83 * <file compressed="true">dialog.ui</file>
84 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
87 * ]]></programlisting></example>
89 * This will create a resource bundle with the following files:
90 * <programlisting><![CDATA[
91 * /org/gtk/Example/data/splashscreen.png
92 * /org/gtk/Example/dialog.ui
93 * /org/gtk/Example/menumarkup.xml
94 * ]]></programlisting>
96 * Note that all resources in the process share the same namespace, so use java-style
97 * path prefixes (like in the above example) to avoid conflicts.
99 * You can then use <link linkend="glib-compile-schemas">glib-compile-resources</link> to compile the xml to a
100 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
101 * --generate-header arguments to create a source file and header to link directly into your application.
103 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
104 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
105 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
108 * There are two forms of the generated source, the default version uses the compiler support for constructor
109 * and destructor functions (where availible) to automatically create and register the #GResource on startup
110 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
111 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
112 * even on the minor ones where this is not availible. (Constructor support is availible for at least Win32, MacOS and Linux.)
114 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
115 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
116 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
117 * is for your own resources, and resource data is often used once, during parsing, and then released.
123 * g_resource_error_quark:
125 * Gets the #GResource Error Quark.
127 * Return value: a #GQuark.
132 g_resource_error_quark (void)
134 return g_quark_from_static_string ("g-resource-error-quark");
139 * @resource: A #GResource.
141 * Atomically increments the reference count of @array by one. This
142 * function is MT-safe and may be called from any thread.
144 * Returns: The passed in #GResource.
149 g_resource_ref (GResource *resource)
151 g_atomic_int_inc (&resource->ref_count);
157 * @resource: A #GResource.
159 * Atomically decrements the reference count of @resource by one. If the
160 * reference count drops to 0, all memory allocated by the array is
161 * released. This function is MT-safe and may be called from any
167 g_resource_unref (GResource *resource)
169 if (g_atomic_int_dec_and_test (&resource->ref_count))
171 gvdb_table_unref (resource->table);
177 * g_resource_new_from_data:
179 * @error: return location for a #GError, or %NULL.
181 * Creates a GResource from a reference to the binary resource bundle.
182 * This will keep a reference to @data while the resource lives, so
183 * the data should not be modified or freed.
185 * If you want to use this resource in the global resource namespace you need
186 * to register it with g_resources_register().
188 * Return value: (transfer full): a new #GResource, or %NULL on error.
193 g_resource_new_from_data (GBytes *data,
199 table = gvdb_table_new_from_data (g_bytes_get_data (data, NULL),
200 g_bytes_get_size (data),
203 (GvdbRefFunc)g_bytes_ref,
204 (GDestroyNotify)g_bytes_unref,
210 resource = g_new0 (GResource, 1);
211 resource->ref_count = 1;
212 resource->table = table;
219 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding.
220 * @error: return location for a #GError, or %NULL.
222 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
223 * you to query it for data.
225 * If you want to use this resource in the global resource namespace you need
226 * to register it with g_resources_register().
228 * Return value: (transfer full): a new #GResource, or %NULL on error.
233 g_resource_load (const gchar *filename,
239 table = gvdb_table_new (filename, FALSE, error);
243 resource = g_new0 (GResource, 1);
244 resource->table = table;
249 static gboolean do_lookup (GResource *resource,
251 GResourceLookupFlags lookup_flags,
258 char *free_path = NULL;
260 gboolean res = FALSE;
263 path_len = strlen (path);
264 if (path[path_len-1] == '/')
266 path = free_path = g_strdup (path);
267 free_path[path_len-1] = 0;
270 value = gvdb_table_get_value (resource->table, path);
274 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
275 _("The resource at '%s' does not exist"),
280 guint32 _size, _flags;
283 g_variant_get (value, "(uu@ay)",
295 *data = g_variant_get_data (array);
298 /* Don't report trailing newline that non-compressed files has */
299 if (_flags & G_RESOURCE_FLAGS_COMPRESSED)
300 *data_size = g_variant_get_size (array);
302 *data_size = g_variant_get_size (array) - 1;
313 * g_resource_open_stream:
314 * @resource: A #GResource.
315 * @path: A pathname inside the resource.
316 * @lookup_flags: A #GResourceLookupFlags.
317 * @error: return location for a #GError, or %NULL.
319 * Looks for a file at the specified @path in the resource and
320 * returns a #GInputStream that lets you read the data.
322 * @lookup_flags controls the behaviour of the lookup.
324 * Returns: (transfer full): #GInputStream or %NULL on error.
325 * Free the returned object with g_object_unref().
330 g_resource_open_stream (GResource *resource,
332 GResourceLookupFlags lookup_flags,
338 GInputStream *stream, *stream2;
340 if (!do_lookup (resource, path, lookup_flags, NULL, &flags, &data, &data_size, error))
343 stream = g_memory_input_stream_new_from_data (data, data_size, NULL);
344 g_object_set_data_full (G_OBJECT (stream), "g-resource",
345 g_resource_ref (resource),
346 (GDestroyNotify)g_resource_unref);
348 if (flags & G_RESOURCE_FLAGS_COMPRESSED)
350 GZlibDecompressor *decompressor =
351 g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
353 stream2 = g_converter_input_stream_new (stream, G_CONVERTER (decompressor));
354 g_object_unref (decompressor);
355 g_object_unref (stream);
363 * g_resource_lookup_data:
364 * @resource: A #GResource.
365 * @path: A pathname inside the resource.
366 * @lookup_flags: A #GResourceLookupFlags.
367 * @error: return location for a #GError, or %NULL.
369 * Looks for a file at the specified @path in the resource and
370 * returns a #GBytes that lets you directly access the data in
373 * The data is always followed by a zero byte, so you
374 * can safely use the data as a C string. However, that byte
375 * is not included in the size of the GBytes.
377 * For uncompressed resource files this is a pointer directly into
378 * the resource bundle, which is typically in some readonly data section
379 * in the program binary. For compressed files we allocate memory on
380 * the heap and automatically uncompress the data.
382 * @lookup_flags controls the behaviour of the lookup.
384 * Returns: (transfer full): #GBytes or %NULL on error.
385 * Free the returned object with g_bytes_unref().
390 g_resource_lookup_data (GResource *resource,
392 GResourceLookupFlags lookup_flags,
400 if (!do_lookup (resource, path, lookup_flags, &size, &flags, &data, &data_size, error))
403 if (flags & G_RESOURCE_FLAGS_COMPRESSED)
405 char *uncompressed, *d;
407 GConverterResult res;
408 gsize d_size, s_size;
409 gsize bytes_read, bytes_written;
412 GZlibDecompressor *decompressor =
413 g_zlib_decompressor_new (G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
415 uncompressed = g_malloc (size + 1);
424 res = g_converter_convert (G_CONVERTER (decompressor),
427 G_CONVERTER_INPUT_AT_END,
431 if (res == G_CONVERTER_ERROR)
433 g_free (uncompressed);
434 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_INTERNAL,
435 _("The resource at '%s' failed to decompress"),
441 s_size -= bytes_read;
443 d_size -= bytes_written;
445 while (res != G_CONVERTER_FINISHED);
447 uncompressed[size] = 0; /* Zero terminate */
449 return g_bytes_new_take (uncompressed, size);
452 return g_bytes_new_with_free_func (data, data_size, (GDestroyNotify)g_resource_unref, g_resource_ref (resource));
456 * g_resource_get_info:
457 * @resource: A #GResource.
458 * @path: A pathname inside the resource.
459 * @lookup_flags: A #GResourceLookupFlags.
460 * @size: (out) (allow-none): a location to place the length of the contents of the file,
461 * or %NULL if the length is not needed
462 * @flags: (out) (allow-none): a location to place the flags about the file,
463 * or %NULL if the length is not needed
464 * @error: return location for a #GError, or %NULL.
466 * Looks for a file at the specified @path in the resource and
467 * if found returns information about it.
469 * @lookup_flags controls the behaviour of the lookup.
471 * Returns: %TRUE if the file was found. %FALSE if there were errors.
476 g_resource_get_info (GResource *resource,
478 GResourceLookupFlags lookup_flags,
483 return do_lookup (resource, path, lookup_flags, size, flags, NULL, NULL, error);
487 * g_resource_enumerate_children:
488 * @resource: A #GResource.
489 * @path: A pathname inside the resource.
490 * @lookup_flags: A #GResourceLookupFlags.
491 * @error: return location for a #GError, or %NULL.
493 * Returns all the names of children at the specified @path in the resource.
494 * The return result is a %NULL terminated list of strings which should
495 * be released with g_strfreev().
497 * @lookup_flags controls the behaviour of the lookup.
499 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
504 g_resource_enumerate_children (GResource *resource,
506 GResourceLookupFlags lookup_flags,
511 char *path_with_slash;
515 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
516 _("The resource at '%s' does not exist"),
521 path_len = strlen (path);
522 if (path[path_len-1] != '/')
523 path_with_slash = g_strconcat (path, "/", NULL);
525 path_with_slash = g_strdup (path);
527 children = gvdb_table_list (resource->table, path_with_slash);
528 g_free (path_with_slash);
530 if (children == NULL)
532 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
533 _("The resource at '%s' does not exist"),
541 static GRWLock resources_lock;
542 static GList *registered_resources;
545 * g_resources_register:
546 * @resource: A #GResource.
548 * Registers the resource with the process-global set of resources.
549 * Once a resource is registered the files in it can be accessed
550 * with the global resource lookup functions like g_resources_lookup_data().
555 g_resources_register (GResource *resource)
557 g_rw_lock_writer_lock (&resources_lock);
559 registered_resources = g_list_prepend (registered_resources,
560 g_resource_ref (resource));
562 g_rw_lock_writer_unlock (&resources_lock);
566 * g_resources_unregister:
567 * @resource: A #GResource.
569 * Unregisters the resource from the process-global set of resources.
574 g_resources_unregister (GResource *resource)
576 g_rw_lock_writer_lock (&resources_lock);
578 if (g_list_find (registered_resources, resource) == NULL)
580 g_warning ("Tried to remove not registred resource");
584 registered_resources = g_list_remove (registered_resources,
586 g_resource_unref (resource);
589 g_rw_lock_writer_unlock (&resources_lock);
593 * g_resources_open_stream:
594 * @path: A pathname inside the resource.
595 * @lookup_flags: A #GResourceLookupFlags.
596 * @error: return location for a #GError, or %NULL.
598 * Looks for a file at the specified @path in the set of
599 * globally registred resources and returns a #GInputStream
600 * that lets you read the data.
602 * @lookup_flags controls the behaviour of the lookup.
604 * Returns: (transfer full): #GInputStream or %NULL on error.
605 * Free the returned object with g_object_unref().
610 g_resources_open_stream (const char *path,
611 GResourceLookupFlags lookup_flags,
614 GInputStream *res = NULL;
616 GInputStream *stream;
618 g_rw_lock_reader_lock (&resources_lock);
620 for (l = registered_resources; l != NULL; l = l->next)
622 GResource *r = l->data;
623 GError *my_error = NULL;
625 stream = g_resource_open_stream (r, path, lookup_flags, &my_error);
626 if (stream == NULL &&
627 g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
629 g_clear_error (&my_error);
634 g_propagate_error (error, my_error);
641 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
642 _("The resource at '%s' does not exist"),
645 g_rw_lock_reader_unlock (&resources_lock);
651 * g_resources_lookup_data:
652 * @path: A pathname inside the resource.
653 * @lookup_flags: A #GResourceLookupFlags.
654 * @error: return location for a #GError, or %NULL.
656 * Looks for a file at the specified @path in the set of
657 * globally registred resources and returns a #GBytes that
658 * lets you directly access the data in memory.
660 * The data is always followed by a zero byte, so you
661 * can safely use the data as a C string. However, that byte
662 * is not included in the size of the GBytes.
664 * For uncompressed resource files this is a pointer directly into
665 * the resource bundle, which is typically in some readonly data section
666 * in the program binary. For compressed files we allocate memory on
667 * the heap and automatically uncompress the data.
669 * @lookup_flags controls the behaviour of the lookup.
671 * Returns: (transfer full): #GBytes or %NULL on error.
672 * Free the returned object with g_bytes_unref().
677 g_resources_lookup_data (const char *path,
678 GResourceLookupFlags lookup_flags,
685 g_rw_lock_reader_lock (&resources_lock);
687 for (l = registered_resources; l != NULL; l = l->next)
689 GResource *r = l->data;
690 GError *my_error = NULL;
692 data = g_resource_lookup_data (r, path, lookup_flags, &my_error);
694 g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
696 g_clear_error (&my_error);
701 g_propagate_error (error, my_error);
708 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
709 _("The resource at '%s' does not exist"),
712 g_rw_lock_reader_unlock (&resources_lock);
718 * g_resources_enumerate_children:
719 * @path: A pathname inside the resource.
720 * @lookup_flags: A #GResourceLookupFlags.
721 * @error: return location for a #GError, or %NULL.
723 * Returns all the names of children at the specified @path in the set of
724 * globally registred resources.
725 * The return result is a %NULL terminated list of strings which should
726 * be released with g_strfreev().
728 * @lookup_flags controls the behaviour of the lookup.
730 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
735 g_resources_enumerate_children (const char *path,
736 GResourceLookupFlags lookup_flags,
739 GHashTable *hash = NULL;
744 g_rw_lock_reader_lock (&resources_lock);
746 for (l = registered_resources; l != NULL; l = l->next)
748 GResource *r = l->data;
750 children = g_resource_enumerate_children (r, path, 0, NULL);
752 if (children != NULL)
755 hash = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
757 for (i = 0; children[i] != NULL; i++)
758 g_hash_table_insert (hash, children[i], children[i]);
763 g_rw_lock_reader_unlock (&resources_lock);
767 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
768 _("The resource at '%s' does not exist"),
777 n_children = g_hash_table_size (hash);
778 children = g_new (char *, n_children + 1);
781 g_hash_table_iter_init (&iter, hash);
782 while (g_hash_table_iter_next (&iter, (gpointer *)&key, NULL))
783 children[i++] = g_strdup (key);
784 children[i++] = NULL;
786 g_hash_table_destroy (hash);
793 * g_resources_get_info:
794 * @path: A pathname inside the resource.
795 * @lookup_flags: A #GResourceLookupFlags.
796 * @size: (out) (allow-none): a location to place the length of the contents of the file,
797 * or %NULL if the length is not needed
798 * @flags: (out) (allow-none): a location to place the flags about the file,
799 * or %NULL if the length is not needed
800 * @error: return location for a #GError, or %NULL.
802 * Looks for a file at the specified @path in the set of
803 * globally registred resources and if found returns information about it.
805 * @lookup_flags controls the behaviour of the lookup.
807 * Returns: %TRUE if the file was found. %FALSE if there were errors.
812 g_resources_get_info (const char *path,
813 GResourceLookupFlags lookup_flags,
818 gboolean res = FALSE;
822 g_rw_lock_reader_lock (&resources_lock);
824 for (l = registered_resources; l != NULL; l = l->next)
826 GResource *r = l->data;
827 GError *my_error = NULL;
829 r_res = g_resource_get_info (r, path, lookup_flags, size, flags, &my_error);
831 g_error_matches (my_error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND))
833 g_clear_error (&my_error);
838 g_propagate_error (error, my_error);
845 g_set_error (error, G_RESOURCE_ERROR, G_RESOURCE_ERROR_NOT_FOUND,
846 _("The resource at '%s' does not exist"),
849 g_rw_lock_reader_unlock (&resources_lock);