GNOME.org
 

[glib/wip/resources] Add documentation for GResource

commit e60e3940fcbbe48849dd1b11a5747ffa1a0e1e08
Author: Alexander Larsson <alexl redhat com>
Date:   Thu Jan 12 11:25:55 2012 +0100

    Add documentation for GResource

 docs/reference/gio/Makefile.am                |    1 +
 docs/reference/gio/gio-docs.xml               |    5 +
 docs/reference/gio/gio-sections.txt           |   43 ++++
 docs/reference/gio/glib-compile-resources.xml |  101 ++++++++
 gio/gioenums.h                                |   28 +++
 gio/giotypes.h                                |    7 +
 gio/gresource.c                               |  322 +++++++++++++++++++++++++
 gio/gresource.h                               |    7 +
 8 files changed, 514 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 3c2a4ca..27f3119 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -140,6 +140,7 @@ EXTRA_DIST +=			\
 man_MANS =			\
 	gio-querymodules.1	\
 	glib-compile-schemas.1	\
+	glib-compile-resources.1	\
 	gsettings.1		\
 	gdbus.1			\
 	gdbus-codegen.1
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 2dce7b4..1987c30 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -185,6 +185,10 @@
         <xi:include href="xml/gsettingsbackend.xml"/>
         <xi:include href="xml/gsettingsschema.xml"/>
     </chapter>
+    <chapter id="resources">
+        <title>Resources</title>
+        <xi:include href="xml/gresource.xml"/>
+    </chapter>
     <chapter id='permissions'>
         <title>Permissions</title>
         <xi:include href="xml/gpermission.xml"/>
@@ -219,6 +223,7 @@
         <xi:include href="gio-querymodules.xml"/>
         <xi:include href="gsettings.xml"/>
         <xi:include href="glib-compile-schemas.xml"/>
+        <xi:include href="glib-compile-resources.xml"/>
         <xi:include href="gdbus.xml"/>
         <xi:include href="xml/gdbus-codegen.xml"/>
     </chapter>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 62b233a..361b47b 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3755,3 +3755,46 @@ g_menu_markup_parser_start_menu
 g_menu_markup_print_stderr
 g_menu_markup_print_string
 </SECTION>
+
+<SECTION>
+<FILE>gresource</FILE>
+<TITLE>GResource</TITLE>
+GResource
+GResourceFlags
+GResourceLookupFlags
+g_resource_load
+g_resource_new_from_data
+g_resource_ref
+g_resource_unref
+g_resource_lookup_data
+g_resource_open_stream
+g_resource_enumerate_children
+g_resource_get_info
+g_resource_set_module
+
+<SUBSECTION Global>
+g_resources_register
+g_resources_unregister
+g_resources_lookup_data
+g_resources_open_stream
+g_resources_enumerate_children
+g_resources_get_info
+
+<SUBSECTION>
+G_RESOURCE_ERROR
+GResourceError
+
+<SUBSECTION Standard>
+G_TYPE_RESOURCE
+G_TYPE_RESOURCE_ERROR
+G_TYPE_RESOURCE_FILE
+G_TYPE_RESOURCE_FLAGS
+G_TYPE_RESOURCE_LOOKUP_FLAGS
+
+<SUBSECTION Private>
+g_resource_get_type
+g_resource_error_get_type
+g_resource_flags_get_type
+g_resource_lookup_flags_get_type
+g_resource_error_quark
+</SECTION>
diff --git a/docs/reference/gio/glib-compile-resources.xml b/docs/reference/gio/glib-compile-resources.xml
new file mode 100644
index 0000000..18c3e88
--- /dev/null
+++ b/docs/reference/gio/glib-compile-resources.xml
@@ -0,0 +1,101 @@
+<refentry id="glib-compile-resources" lang="en">
+
+<refmeta>
+  <refentrytitle>glib-compile-resources</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>glib-compile-resources</refname>
+  <refpurpose>glib resource compiler</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>glib-compile-resources</command>
+    <arg choice="opt" rep="repeat">option</arg>
+    <arg choice="req">file</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-compile-resources</command> reads the resource description from
+<replaceable>file</replaceable> and the files that it references
+and creates a binary resource bundle that is suitable for use with the
+<link linkend="GResource"><type>GResource</type></link> API.
+The resulting bundle is then written out as-is, or as C source for linking into
+an application.
+</para>
+<para>
+The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
+For a detailed description of the XML file format, see the
+<link linkend="GResource"><type>GResource</type></link> documentation.
+</para>
+
+<refsect2><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--target=<replaceable>TARGETFILE</replaceable></option></term>
+<listitem><para>
+Store the compiled resources in <replaceable>TARGETFILE</replaceable>. If not specified a filename based
+on the <replaceable>file</replaceable> basename is used.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--sourcedir</option></term>
+<listitem><para>
+The files references in <replaceable>file</replaceable> are loaded from this directory. If
+not specified the current directory is used.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-source</option></term>
+<listitem><para>
+Instead of a writing the resource bundle in binary form create a C source file that contains the
+resource bundle. This can then be compiled into an application for easy access.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-header</option></term>
+<listitem><para>
+Generate a header file for use with C code generated by <option>--generate-source</option>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--c-name</option></term>
+<listitem><para>
+Specify the prefix used for the C identifiers in the code generated by
+<option>--generate-source</option> and <option>--generate-headers</option>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--manual-register</option></term>
+<listitem><para>
+By default code generated by <option>--generate-source</option> uses automatic initialization
+of the resource. This works on most systems by using the compiler support for constructors.
+However, some (uncommon) compilers may not support this, you can then specify <option>--manual-register</option>,
+which will generate custom register and unregister functions that your code can manually call
+at initialization and uninitialization time.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+</refsect1>
+<refsect1><title>See also</title>
+</refsect1>
+</refentry>
diff --git a/gio/gioenums.h b/gio/gioenums.h
index 241ae81..17ddb10 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -630,17 +630,45 @@ typedef enum {
   G_RESOLVER_ERROR_INTERNAL
 } GResolverError;
 
+/**
+ * GResourceError:
+ * @G_RESOURCE_ERROR_NOT_FOUND: no file was found at the requested path
+ * @G_RESOURCE_ERROR_INTERNAL: unknown error
+ *
+ * An error code used with %G_RESOURCE_ERROR in a #GError returned
+ * from a #GResource routine.
+ *
+ * Since: 2.32
+ */
 typedef enum {
   G_RESOURCE_ERROR_NOT_FOUND,
   G_RESOURCE_ERROR_INTERNAL
 } GResourceError;
 
+/**
+ * GResourceFlags:
+ * @G_RESOURCE_FLAGS_NONE: No flags set.
+ * @G_RESOURCE_FLAGS_COMPRESSED: The file is compressed.
+ * @G_RESOURCE_FLAGS_LOCALIZED: The file has alternate versions based on locale.
+ *
+ * GResourceFlags give information about a particular file inside a resource
+ * bundle.
+ **/
 typedef enum {
   G_RESOURCE_FLAGS_NONE       = 0,
   G_RESOURCE_FLAGS_COMPRESSED = (1<<0),
   G_RESOURCE_FLAGS_LOCALIZED  = (1<<1)
 } GResourceFlags;
 
+/**
+ * GResourceLookupFlags:
+ * @G_RESOURCE_LOOKUP_FLAGS_NONE: No flags set.
+ * @G_RESOURCE_LOOKUP_FLAGS_NO_ALTERNATIVE: If there is an alternative
+ * (for instance a locale-specific version of the file) return the original
+ * version, not the alternative.
+ *
+ * GResourceLookupFlags determine how resource path lookups are handled.
+ **/
 typedef enum {
   G_RESOURCE_LOOKUP_FLAGS_NONE       = 0,
   G_RESOURCE_LOOKUP_FLAGS_NO_ALTERNATIVE = (1<<0),
diff --git a/gio/giotypes.h b/gio/giotypes.h
index 8537748..2e4c367 100644
--- a/gio/giotypes.h
+++ b/gio/giotypes.h
@@ -135,6 +135,13 @@ typedef struct _GIOStream                     GIOStream;
 typedef struct _GPollableInputStream          GPollableInputStream; /* Dummy typedef */
 typedef struct _GPollableOutputStream         GPollableOutputStream; /* Dummy typedef */
 typedef struct _GResolver                     GResolver;
+/**
+ * GResource:
+ *
+ * A resource bundle.
+ *
+ * Since: 2.32
+ */
 typedef struct _GResource                     GResource;
 typedef struct _GSeekable                     GSeekable;
 typedef struct _GSimpleAsyncResult            GSimpleAsyncResult;
diff --git a/gio/gresource.c b/gio/gresource.c
index e399696..25a6726 100644
--- a/gio/gresource.c
+++ b/gio/gresource.c
@@ -46,6 +46,81 @@ G_DEFINE_BOXED_TYPE (GResource, g_resouces, g_resource_ref, g_resource_unref)
  * @short_description: Resource framework
  * @include: gio/gio.h
  *
+ * Applications and libraries often contain binary or textual data that is really part of the
+ * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
+ * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
+ * manually included as literal strings in the code.
+ *
+ * The #GResource API and the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
+ * provide a convenient and efficient alternative to this which has some nice properties. You
+ * maintain the files as normal files, so its easy to edit them, but during the build the files
+ * are combined into a binary bundle that is linked into the executable. This means that loading
+ * the resource files are efficient (as they are already in memory, shared with other instances) and
+ * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
+ * also makes it easier to create relocatable applications.
+ *
+ * Resource files can have locale specific alternatives, so that the current locale causes resource
+ * lookups to automatically pick up an alternate file.
+ *
+ * Resource files can also be marked as compresses. Such files will be included in the resource bundle
+ * in a compressed form, but will be automatically uncompressed when the resource is used. This
+ * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
+ *
+ * Resource bundles are created by the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
+ * which takes an xml file that describes the bundle, and a set of files that the xml references. These
+ * are combined into a binary resource bundle.
+ *
+ * <example id="resource-example"><title>Example resource description</title>
+ * <programlisting><![CDATA[
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <gresources>
+ *   <gresource prefix="/org/gtk/Example">
+ *     <file>data/splashscreen.png</file>
+ *     <file compressed="true">dialog.ui</file>
+ *     <file>menumarkup.xml</file>
+ *   </gresource>
+ *   <gresource lang="sv" prefix="/org/gtk/Example">
+ *     <file alias="menumarkup.xml">menumarkup_SV.xml</file>
+ *   </gresource>
+ * </gresources>
+ * ]]></programlisting></example>
+ *
+ * This will create a resource bundle with the following files:
+ * <programlisting><![CDATA[
+ * /org/gtk/Example/data/splashscreen.png
+ * /org/gtk/Example/dialog.ui
+ * /org/gtk/Example/menumarkup.xml
+ * /sv/org/gtk/Example/menumarkup.xml
+ * ]]></programlisting>
+ *
+ * Where the contents at "/org/gtk/Example/menumarkup.xml" automatically redirects
+ * to "/sv/org/gtk/Example/menumarkup.xml" when run in e.g. a sv_SE locale.
+ *
+ * Note that all resources in the process share the same namespace, so use java-style
+ * path prefixes (like in the above example) to avoid conflicts.
+ *
+ * You can then use <link linkend="glib-compile-schemas">glib-compile-resources</link> to compile the xml to a
+ * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
+ * --generate-header arguments to create a source file and header to link directly into your application.
+ *
+ * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
+ * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
+ * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
+ * the resource data.
+ *
+ * There are two forms of the generated source, the default version uses the compiler support for constructor
+ * and destructor functions (where availible) to automatically create and register the #GResource on startup
+ * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
+ * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
+ * even on the minor ones where this is not availible. (Constructor support is availible for at least Win32, MacOS and Linux.)
+ *
+ * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
+ * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
+ * when the library is unloaded. For modules using #GTypeModule we support disallowing unload while resources are
+ * outstanding by using g_resource_set_module(), but not all libraries might use this. However, in practice this is
+ * not generally a problem, since most resource accesses is for your own resources, and resource data is often
+ * used once, during parsing, and then released.
+ *
  * Since: 2.32
  */
 
@@ -64,6 +139,17 @@ g_resource_error_quark (void)
   return g_quark_from_static_string ("g-resource-error-quark");
 }
 
+/**
+ * g_resource_ref:
+ * @resource: A #GResource.
+ *
+ * Atomically increments the reference count of @array by one. This
+ * function is MT-safe and may be called from any thread.
+ *
+ * Returns: The passed in #GResource.
+ *
+ * Since: 2.32
+ **/
 GResource *
 g_resource_ref (GResource *resource)
 {
@@ -71,6 +157,17 @@ g_resource_ref (GResource *resource)
   return resource;
 }
 
+/**
+ * g_resource_unref:
+ * @resource: A #GResource.
+ *
+ * Atomically decrements the reference count of @resource by one. If the
+ * reference count drops to 0, all memory allocated by the array is
+ * released. This function is MT-safe and may be called from any
+ * thread.
+ *
+ * Since: 2.32
+ **/
 void
 g_resource_unref (GResource *resource)
 {
@@ -81,6 +178,22 @@ g_resource_unref (GResource *resource)
     }
 }
 
+/**
+ * g_resource_set_module:
+ * @resource: A #GResource.
+ * @type_module: (allow-none): A #GTypeModule, or %NULL.
+ *
+ * Allows setting a #GTypeModule to be associated with the
+ * resource. As long as any reference to data from the
+ * resource is outstanding the GTypeModule is used, and
+ * thus will not be unloaded.
+ *
+ * This is useful if you link a resource into a module
+ * and want to ensure that its not unloaded while there
+ * is outstanding pointers into the linked in data.
+ *
+ * Since: 2.32
+ **/
 void
 g_resource_set_module (GResource *resource,
 		       GTypeModule *type_module)
@@ -110,6 +223,22 @@ g_resource_unuse (GResource *resource)
   g_resource_unref (resource);
 }
 
+/**
+ * g_resource_new_from_data:
+ * @data: A #GBytes.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Creates a GResource from a reference to the binary resource bundle.
+ * This will keep a reference to @data while the resource lives, so
+ * the data should not be modified or freed.
+ *
+ * If you want to use this resource in the global resource namespace you need
+ * to register it with g_resources_register().
+ *
+ * Return value: (transfer full): a new #GResource, or %NULL on error.
+ *
+ * Since: 2.32
+ **/
 GResource *
 g_resource_new_from_data (GBytes *data,
 			  GError **error)
@@ -135,6 +264,21 @@ g_resource_new_from_data (GBytes *data,
   return resource;
 }
 
+/**
+ * g_resource_load:
+ * @filename: (type filename): the path of a filename to load, in the GLib filename encoding.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Loads a binary resource bundle and creates a #GResource representation of it, allowing
+ * you to query it for data.
+ *
+ * If you want to use this resource in the global resource namespace you need
+ * to register it with g_resources_register().
+ *
+ * Return value: (transfer full): a new #GResource, or %NULL on error.
+ *
+ * Since: 2.32
+ **/
 GResource *
 g_resource_load (const gchar *filename,
 		 GError **error)
@@ -238,6 +382,23 @@ static gboolean do_lookup (GResource *resource,
   return res;
 }
 
+/**
+ * g_resource_open_stream:
+ * @resource: A #GResource.
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the resource and
+ * returns a #GInputStream that lets you read the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GInputStream or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ *
+ * Since: 2.32
+ **/
 GInputStream *
 g_resource_open_stream (GResource *resource,
 			const char *path,
@@ -271,6 +432,33 @@ g_resource_open_stream (GResource *resource,
   return stream;
 }
 
+/**
+ * g_resource_lookup_data:
+ * @resource: A #GResource.
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the resource and
+ * returns a #GBytes that lets you directly access the data in
+ * memory.
+ *
+ * The data is always followed by a zero byte, so you
+ * can safely use the data as a C string. However, that byte
+ * is not included in the size of the GBytes.
+ *
+ * For uncompressed resource files this is a pointer directly into
+ * the resource bundle, which is typically in some readonly data section
+ * in the program binary. For compressed files we allocate memory on
+ * the heap and automatically uncompress the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GBytes or %NULL on error.
+ *     Free the returned object with g_bytes_unref().
+ *
+ * Since: 2.32
+ **/
 GBytes *
 g_resource_lookup_data (GResource *resource,
 			const char *path,
@@ -337,6 +525,26 @@ g_resource_lookup_data (GResource *resource,
     return g_bytes_new_with_free_func (data, data_size, (GDestroyNotify)g_resource_unuse, g_resource_use (resource));
 }
 
+/**
+ * g_resource_get_info:
+ * @resource: A #GResource.
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @size:  (out) (allow-none): a location to place the length of the contents of the file,
+ *    or %NULL if the length is not needed
+ * @flags:  (out) (allow-none): a location to place the flags about the file,
+ *    or %NULL if the length is not needed
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the resource and
+ * if found returns information about it.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: %TRUE if the file was found. %FALSE if there were errors.
+ *
+ * Since: 2.32
+ **/
 gboolean
 g_resource_get_info (GResource *resource,
 		     const char *path,
@@ -348,6 +556,23 @@ g_resource_get_info (GResource *resource,
   return do_lookup (resource, path, lookup_flags, size, flags, NULL, NULL, error);
 }
 
+/**
+ * g_resource_enumerate_children:
+ * @resource: A #GResource.
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Returns all the names of children at the specified @path in the resource.
+ * The return result is a %NULL terminated list of strings which should
+ * be released with g_strfreev().
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
+ *
+ * Since: 2.32
+ **/
 char **
 g_resource_enumerate_children (GResource *resource,
 			       const char *path,
@@ -389,6 +614,16 @@ g_resource_enumerate_children (GResource *resource,
 static GRWLock resources_lock;
 static GList *registred_resources;
 
+/**
+ * g_resources_register:
+ * @resource: A #GResource.
+ *
+ * Registers the resource with the process-global set of resources.
+ * Once a resource is registered the files in it can be accessed
+ * with the global resource lookup functions like g_resources_lookup_data().
+ *
+ * Since: 2.32
+ **/
 void
 g_resources_register (GResource *resource)
 {
@@ -400,6 +635,14 @@ g_resources_register (GResource *resource)
   g_rw_lock_writer_unlock (&resources_lock);
 }
 
+/**
+ * g_resources_unregister:
+ * @resource: A #GResource.
+ *
+ * Unregisters the resource from the process-global set of resources.
+ *
+ * Since: 2.32
+ **/
 void
 g_resources_unregister (GResource *resource)
 {
@@ -419,6 +662,23 @@ g_resources_unregister (GResource *resource)
   g_rw_lock_writer_unlock (&resources_lock);
 }
 
+/**
+ * g_resources_open_stream:
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the set of
+ * globally registred resources and returns a #GInputStream
+ * that lets you read the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GInputStream or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ *
+ * Since: 2.32
+ **/
 GInputStream *
 g_resources_open_stream (const char *path,
 			 GResourceLookupFlags lookup_flags,
@@ -460,6 +720,32 @@ g_resources_open_stream (const char *path,
   return res;
 }
 
+/**
+ * g_resources_lookup_data:
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the set of
+ * globally registred resources and returns a #GBytes that
+ * lets you directly access the data in memory.
+ *
+ * The data is always followed by a zero byte, so you
+ * can safely use the data as a C string. However, that byte
+ * is not included in the size of the GBytes.
+ *
+ * For uncompressed resource files this is a pointer directly into
+ * the resource bundle, which is typically in some readonly data section
+ * in the program binary. For compressed files we allocate memory on
+ * the heap and automatically uncompress the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GBytes or %NULL on error.
+ *     Free the returned object with g_bytes_unref().
+ *
+ * Since: 2.32
+ **/
 GBytes *
 g_resources_lookup_data (const char *path,
 			 GResourceLookupFlags lookup_flags,
@@ -501,6 +787,23 @@ g_resources_lookup_data (const char *path,
   return res;
 }
 
+/**
+ * g_resources_enumerate_children:
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Returns all the names of children at the specified @path in the set of
+ * globally registred resources.
+ * The return result is a %NULL terminated list of strings which should
+ * be released with g_strfreev().
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
+ *
+ * Since: 2.32
+ **/
 char **
 g_resources_enumerate_children (const char *path,
 				GResourceLookupFlags lookup_flags,
@@ -559,6 +862,25 @@ g_resources_enumerate_children (const char *path,
     }
 }
 
+/**
+ * g_resources_get_info:
+ * @path: A pathname inside the resource.
+ * @lookup_flags: A #GResourceLookupFlags.
+ * @size:  (out) (allow-none): a location to place the length of the contents of the file,
+ *    or %NULL if the length is not needed
+ * @flags:  (out) (allow-none): a location to place the flags about the file,
+ *    or %NULL if the length is not needed
+ * @error: return location for a #GError, or %NULL.
+ *
+ * Looks for a file at the specified @path in the set of
+ * globally registred resources and if found returns information about it.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: %TRUE if the file was found. %FALSE if there were errors.
+ *
+ * Since: 2.32
+ **/
 gboolean
 g_resources_get_info (const char   *path,
 		      GResourceLookupFlags lookup_flags,
diff --git a/gio/gresource.h b/gio/gresource.h
index d063c02..4691057 100644
--- a/gio/gresource.h
+++ b/gio/gresource.h
@@ -39,6 +39,13 @@ G_BEGIN_DECLS
 #define G_TYPE_RESOURCE (g_resource_get_type ())
 
 
+/**
+ * G_RESOURCE_ERROR:
+ *
+ * Error domain for #GResource. Errors in this domain will be from the
+ * #GResourceError enumeration. See #GError for more information on
+ * error domains.
+ */
 #define G_RESOURCE_ERROR (g_resource_error_quark ())
 GQuark g_resource_error_quark (void);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]