luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 07:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'resource-docs' into 'main'

Browse Source 
gresource: Convert docs to gi-docgen linking syntax

See merge request GNOME/glib!4243
This commit is contained in:
Philip Withnall 2024-09-17 13:46:10 +00:00
commit 99c749f4ec
1 changed files with 100 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
gio/gresource.c
View File

@ -218,7 +218,7 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
/** /**
* GStaticResource: * GStaticResource:
* *
* #GStaticResource is an opaque data structure and can only be accessed * `GStaticResource` is an opaque data structure and can only be accessed
* using the following functions. * using the following functions.
**/ **/
typedef gboolean (* CheckCandidate) (const gchar *candidate, gpointer user_data); typedef gboolean (* CheckCandidate) (const gchar *candidate, gpointer user_data);
@ -509,9 +509,9 @@ g_resource_find_overlay (const gchar *path,
/** /**
* g_resource_error_quark: * g_resource_error_quark:
* *
* Gets the #GResource Error Quark. * Gets the [struct@Gio.Resource] Error Quark.
* *
* Returns: a #GQuark * Returns: a [type@GLib.Quark]
* *
* Since: 2.32 * Since: 2.32
*/ */
@ -519,12 +519,13 @@ G_DEFINE_QUARK (g-resource-error-quark, g_resource_error)
/** /**
* g_resource_ref: * g_resource_ref:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* *
* Atomically increments the reference count of @resource by one. This * Atomically increments the reference count of @resource by one.
* function is MT-safe and may be called from any thread.
* *
* Returns: The passed in #GResource * This function is threadsafe and may be called from any thread.
*
* Returns: The passed in [struct@Gio.Resource]
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -537,11 +538,12 @@ g_resource_ref (GResource *resource)
/** /**
* g_resource_unref: * g_resource_unref:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* *
* Atomically decrements the reference count of @resource by one. If the * Atomically decrements the reference count of @resource by one.
* reference count drops to 0, all memory allocated by the resource is *
* released. This function is MT-safe and may be called from any * If the reference count drops to 0, all memory allocated by the resource is
* released. This function is threadsafe and may be called from any
* thread. * thread.
* *
* Since: 2.32 * Since: 2.32
@ -589,15 +591,16 @@ g_resource_error_from_gvdb_table_error (GError **g_resource_error,
/** /**
* g_resource_new_from_data: * g_resource_new_from_data:
* @data: A #GBytes * @data: A [struct@GLib.Bytes]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
*
* Creates a [struct@Gio.Resource] from a reference to the binary resource bundle.
* *
* Creates a GResource from a reference to the binary resource bundle.
* This will keep a reference to @data while the resource lives, so * This will keep a reference to @data while the resource lives, so
* the data should not be modified or freed. * the data should not be modified or freed.
* *
* If you want to use this resource in the global resource namespace you need * If you want to use this resource in the global resource namespace you need
* to register it with g_resources_register(). * to register it with [func@Gio.resources_register].
* *
* Note: @data must be backed by memory that is at least pointer aligned. * Note: @data must be backed by memory that is at least pointer aligned.
* Otherwise this function will internally create a copy of the memory since * Otherwise this function will internally create a copy of the memory since
@ -605,7 +608,7 @@ g_resource_error_from_gvdb_table_error (GError **g_resource_error,
* *
* If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. * If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned.
* *
* Returns: (transfer full): a new #GResource, or %NULL on error * Returns: (transfer full): a new [struct@Gio.Resource], or `NULL` on error
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -641,20 +644,20 @@ g_resource_new_from_data (GBytes *data,
/** /**
* g_resource_load: * g_resource_load:
* @filename: (type filename): the path of a filename to load, in the GLib filename encoding * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Loads a binary resource bundle and creates a #GResource representation of it, allowing * Loads a binary resource bundle and creates a [struct@Gio.Resource]
* you to query it for data. * representation of it, allowing you to query it for data.
* *
* If you want to use this resource in the global resource namespace you need * If you want to use this resource in the global resource namespace you need
* to register it with g_resources_register(). * to register it with [func@Gio.resources_register].
* *
* If @filename is empty or the data in it is corrupt, * If @filename is empty or the data in it is corrupt,
* %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or * %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or
* there is an error in reading it, an error from g_mapped_file_new() will be * there is an error in reading it, an error from [ctor@GLib.MappedFile.new]
* returned. * will be returned.
* *
* Returns: (transfer full): a new #GResource, or %NULL on error * Returns: (transfer full): a new [struct@Gio.Resource], or `NULL` on error
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -755,21 +758,20 @@ do_lookup (GResource *resource,
/** /**
* g_resource_open_stream: * g_resource_open_stream:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the resource and * Looks for a file at the specified @path in the resource and
* returns a #GInputStream that lets you read the data. * returns a [class@Gio.InputStream] that lets you read the data.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
* The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was * The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was
* not found in @resource. * not found in @resource.
* *
* Returns: (transfer full): #GInputStream or %NULL on error. * Returns: (transfer full): [class@Gio.InputStream] or `NULL` on error
* Free the returned object with g_object_unref()
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -816,23 +818,23 @@ static GBytes *resource_to_bytes (GResource *resource,
/** /**
* g_resource_lookup_data: * g_resource_lookup_data:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the resource and * Looks for a file at the specified @path in the resource and
* returns a #GBytes that lets you directly access the data in * returns a [struct@GLib.Bytes] that lets you directly access the data in
* memory. * memory.
* *
* The data is always followed by a zero byte, so you * The data is always followed by a zero byte, so you
* can safely use the data as a C string. However, that byte * can safely use the data as a C string. However, that byte
* is not included in the size of the GBytes. * is not included in the size of the [struct@GLib.Bytes].
* *
* For uncompressed resource files this is a pointer directly into * For uncompressed resource files this is a pointer directly into
* the resource bundle, which is typically in some readonly data section * the resource bundle, which is typically in some read-only data section
* in the program binary. For compressed files we allocate memory on * in the program binary. For compressed files, memory is allocated on
* the heap and automatically uncompress the data. * the heap and the data is automatically uncompressed.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
@ -840,8 +842,7 @@ static GBytes *resource_to_bytes (GResource *resource,
* @resource, or %G_RESOURCE_ERROR_INTERNAL if decompression of a compressed * @resource, or %G_RESOURCE_ERROR_INTERNAL if decompression of a compressed
* resource failed. * resource failed.
* *
* Returns: (transfer full): #GBytes or %NULL on error. * Returns: (transfer full): [struct@GLib.Bytes] or `NULL` on error
* Free the returned object with g_bytes_unref()
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -931,14 +932,14 @@ resource_to_bytes (GResource *resource,
/** /**
* g_resource_get_info: * g_resource_get_info:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @size: (out) (optional): a location to place the length of the contents of the file, * @size: (out) (optional): a location to place the length of the contents of the file,
* or %NULL if the length is not needed * or `NULL` if the length is not needed
* @flags: (out) (optional): a location to place the flags about the file, * @flags: (out) (optional): a location to place the flags about the file,
* or %NULL if the length is not needed * or `NULL` if the length is not needed
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the resource and * Looks for a file at the specified @path in the resource and
* if found returns information about it. * if found returns information about it.
@ -948,7 +949,7 @@ resource_to_bytes (GResource *resource,
* The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was * The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was
* not found in @resource. * not found in @resource.
* *
* Returns: %TRUE if the file was found. %FALSE if there were errors * Returns: `TRUE` if the file was found, `FALSE` if there were errors
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -1003,16 +1004,17 @@ ensure_slash_suffix (const char *path,
/** /**
* g_resource_enumerate_children: * g_resource_enumerate_children:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Returns all the names of children at the specified @path in the resource. * 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().
* *
* If @path is invalid or does not exist in the #GResource, * The return result is a `NULL` terminated list of strings which should
* be released with [func@GLib.strfreev].
*
* If @path is invalid or does not exist in the [struct@Gio.Resource],
* %G_RESOURCE_ERROR_NOT_FOUND will be returned. * %G_RESOURCE_ERROR_NOT_FOUND will be returned.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
@ -1125,11 +1127,13 @@ g_resources_unregister_unlocked (GResource *resource)
/** /**
* g_resources_register: * g_resources_register:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* *
* Registers the resource with the process-global set of resources. * Registers the resource with the process-global set of resources.
*
* Once a resource is registered the files in it can be accessed * Once a resource is registered the files in it can be accessed
* with the global resource lookup functions like g_resources_lookup_data(). * with the global resource lookup functions like
* [func@Gio.resources_lookup_data].
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -1143,7 +1147,7 @@ g_resources_register (GResource *resource)
/** /**
* g_resources_unregister: * g_resources_unregister:
* @resource: A #GResource * @resource: A [struct@Gio.Resource]
* *
* Unregisters the resource from the process-global set of resources. * Unregisters the resource from the process-global set of resources.
* *
@ -1159,18 +1163,17 @@ g_resources_unregister (GResource *resource)
/** /**
* g_resources_open_stream: * g_resources_open_stream:
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the set of * Looks for a file at the specified @path in the set of
* globally registered resources and returns a #GInputStream * globally registered resources and returns a [class@Gio.InputStream]
* that lets you read the data. * that lets you read the data.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
* Returns: (transfer full): #GInputStream or %NULL on error. * Returns: (transfer full): [class@Gio.InputStream] or `NULL` on error
* Free the returned object with g_object_unref()
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -1217,27 +1220,26 @@ g_resources_open_stream (const gchar *path,
/** /**
* g_resources_lookup_data: * g_resources_lookup_data:
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the set of * Looks for a file at the specified @path in the set of
* globally registered resources and returns a #GBytes that * globally registered resources and returns a [struct@GLib.Bytes] that
* lets you directly access the data in memory. * lets you directly access the data in memory.
* *
* The data is always followed by a zero byte, so you * The data is always followed by a zero byte, so you
* can safely use the data as a C string. However, that byte * can safely use the data as a C string. However, that byte
* is not included in the size of the GBytes. * is not included in the size of the [struct@GLib.Bytes].
* *
* For uncompressed resource files this is a pointer directly into * For uncompressed resource files this is a pointer directly into
* the resource bundle, which is typically in some readonly data section * the resource bundle, which is typically in some read-only data section
* in the program binary. For compressed files we allocate memory on * in the program binary. For compressed files we allocate memory on
* the heap and automatically uncompress the data. * the heap and automatically uncompress the data.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
* Returns: (transfer full): #GBytes or %NULL on error. * Returns: (transfer full): [struct@GLib.Bytes] or `NULL` on error
* Free the returned object with g_bytes_unref()
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -1283,14 +1285,15 @@ g_resources_lookup_data (const gchar *path,
/** /**
* g_resources_enumerate_children: * g_resources_enumerate_children:
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Returns all the names of children at the specified @path in the set of * Returns all the names of children at the specified @path in the set of
* globally registered resources. * globally registered resources.
* The return result is a %NULL terminated list of strings which should *
* be released with g_strfreev(). * The return result is a `NULL` terminated list of strings which should
* be released with [func@GLib.strfreev].
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
@ -1393,20 +1396,20 @@ g_resources_has_children (const char *path)
/** /**
* g_resources_get_info: * g_resources_get_info:
* @path: A pathname inside the resource * @path: A path name inside the resource
* @lookup_flags: A #GResourceLookupFlags * @lookup_flags: A [flags@Gio.ResourceLookupFlags]
* @size: (out) (optional): a location to place the length of the contents of the file, * @size: (out) (optional): a location to place the length of the contents of the file,
* or %NULL if the length is not needed * or `NULL` if the length is not needed
* @flags: (out) (optional): a location to place the #GResourceFlags about the file, * @flags: (out) (optional): a location to place the [flags@Gio.ResourceFlags] about the file,
* or %NULL if the flags are not needed * or `NULL` if the flags are not needed
* @error: return location for a #GError, or %NULL * @error: return location for a [type@GLib.Error], or `NULL`
* *
* Looks for a file at the specified @path in the set of * Looks for a file at the specified @path in the set of
* globally registered resources and if found returns information about it. * globally registered resources and if found returns information about it.
* *
* @lookup_flags controls the behaviour of the lookup. * @lookup_flags controls the behaviour of the lookup.
* *
* Returns: %TRUE if the file was found. %FALSE if there were errors * Returns: `TRUE` if the file was found, `FALSE` if there were errors
* *
* Since: 2.32 * Since: 2.32
**/ **/
@ -1510,13 +1513,13 @@ register_lazy_static_resources (void)
/** /**
* g_static_resource_init: * g_static_resource_init:
* @static_resource: pointer to a static #GStaticResource * @static_resource: pointer to a static [struct@Gio.StaticResource]
* *
* Initializes a GResource from static data using a * Initializes a [struct@Gio.Resource] from static data using a
* GStaticResource. * [struct@Gio.StaticResource].
* *
* This is normally used by code generated by * This is normally used by code generated by
* [glib-compile-resources][glib-compile-resources] * [`glib-compile-resources`](glib-compile-resources.html)
* and is not typically used by other code. * and is not typically used by other code.
* *
* Since: 2.32 * Since: 2.32
@ -1536,12 +1539,13 @@ g_static_resource_init (GStaticResource *static_resource)
/** /**
* g_static_resource_fini: * g_static_resource_fini:
* @static_resource: pointer to a static #GStaticResource * @static_resource: pointer to a static [struct@Gio.StaticResource]
* *
* Finalized a GResource initialized by g_static_resource_init(). * Finalizes a [struct@Gio.Resource] initialized by
* [method@Gio.StaticResource.init].
* *
* This is normally used by code generated by * This is normally used by code generated by
* [glib-compile-resources][glib-compile-resources] * [`glib-compile-resources`](glib-compile-resources.html)
* and is not typically used by other code. * and is not typically used by other code.
* *
* Since: 2.32 * Since: 2.32
@ -1571,15 +1575,16 @@ g_static_resource_fini (GStaticResource *static_resource)
/** /**
* g_static_resource_get_resource: * g_static_resource_get_resource:
* @static_resource: pointer to a static #GStaticResource * @static_resource: pointer to a static [struct@Gio.StaticResource]
* *
* Gets the GResource that was registered by a call to g_static_resource_init(). * Gets the [struct@Gio.Resource] that was registered by a call to
* [method@Gio.StaticResource.init].
* *
* This is normally used by code generated by * This is normally used by code generated by
* [glib-compile-resources][glib-compile-resources] * [`glib-compile-resources`](glib-compile-resources.html)
* and is not typically used by other code. * and is not typically used by other code.
* *
* Returns: (transfer none): a #GResource * Returns: (transfer none): a [struct@Gio.Resource]
* *
* Since: 2.32 * Since: 2.32
**/ **/