From 918a7720a03a8284a9c1e2626a62d4f8930f633d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 7 Jan 2023 22:34:05 +0000 Subject: Update GLib introspection data Use GLib commit ec3b1bfc45216850c1a861055ad2fd9d9906813a (tag: 2.75.2) --- gir/gio-2.0.c | 75 ++++++--- gir/glib-2.0.c | 450 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- gir/gobject-2.0.c | 34 +++-- 3 files changed, 509 insertions(+), 50 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 407293d3..10d7d78c 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -11594,8 +11594,9 @@ /** * g_action_parse_detailed_name: * @detailed_name: a detailed action name - * @action_name: (out): the action name - * @target_value: (out): the target value, or %NULL for no target + * @action_name: (out) (optional) (not nullable) (transfer full): the action name + * @target_value: (out) (optional) (nullable) (transfer full): the target value, + * or %NULL for no target * @error: a pointer to a %NULL #GError, or %NULL * * Parses a detailed action name into its separate name and target @@ -11605,23 +11606,29 @@ * * The first format is used to represent an action name with no target * value and consists of just an action name containing no whitespace - * nor the characters ':', '(' or ')'. For example: "app.action". + * nor the characters `:`, `(` or `)`. For example: `app.action`. * * The second format is used to represent an action with a target value - * that is a non-empty string consisting only of alphanumerics, plus '-' - * and '.'. In that case, the action name and target value are - * separated by a double colon ("::"). For example: - * "app.action::target". + * that is a non-empty string consisting only of alphanumerics, plus `-` + * and `.`. In that case, the action name and target value are + * separated by a double colon (`::`). For example: + * `app.action::target`. * * The third format is used to represent an action with any type of * target value, including strings. The target value follows the action - * name, surrounded in parens. For example: "app.action(42)". The + * name, surrounded in parens. For example: `app.action(42)`. The * target value is parsed using g_variant_parse(). If a tuple-typed * value is desired, it must be specified in the same way, resulting in - * two sets of parens, for example: "app.action((1,2,3))". A string - * target can be specified this way as well: "app.action('target')". - * For strings, this third format must be used if * target value is - * empty or contains characters other than alphanumerics, '-' and '.'. + * two sets of parens, for example: `app.action((1,2,3))`. A string + * target can be specified this way as well: `app.action('target')`. + * For strings, this third format must be used if target value is + * empty or contains characters other than alphanumerics, `-` and `.`. + * + * If this function returns %TRUE, a non-%NULL value is guaranteed to be returned + * in @action_name (if a pointer is passed in). A %NULL value may still be + * returned in @target_value, as the @detailed_name may not contain a target. + * + * If returned, the #GVariant in @target_value is guaranteed to not be floating. * * Returns: %TRUE if successful, else %FALSE with @error set * Since: 2.38 @@ -12028,9 +12035,9 @@ * environment variable with the path of the launched desktop file and * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, - * should it be inherited by further processes. The `DISPLAY` and - * `DESKTOP_STARTUP_ID` environment variables are also set, based - * on information provided in @context. + * should it be inherited by further processes. The `DISPLAY`, + * `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment + * variables are also set, based on information provided in @context. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ @@ -12298,10 +12305,18 @@ * @files: (element-type GFile): a #GList of of #GFile objects * * Initiates startup notification for the application and returns the - * `DESKTOP_STARTUP_ID` for the launched operation, if supported. + * `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, + * if supported. + * + * The returned token may be referred to equivalently as an ‘activation token’ + * (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology). + * The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst). + * + * Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1), + * and startup notification IDs are defined in the + * [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). * - * Startup notification IDs are defined in the - * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). + * Support for the XDG Activation Protocol was added in GLib 2.76. * * Returns: (nullable): a startup notification ID for the application, or %NULL if * not supported. @@ -12419,6 +12434,8 @@ * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is * set, then the resulting dictionary is sent to the primary instance, * where g_application_command_line_get_options_dict() will return it. + * As it has been passed outside the process at this point, the types of all + * values in the options dict must be checked before being used. * This "packing" is done according to the type of the argument -- * booleans for normal flags, strings for strings, bytestrings for * filenames, etc. The packing only occurs if the flag is given (ie: we @@ -12625,7 +12642,7 @@ * g_application_command_line_get_options_dict: * @cmdline: a #GApplicationCommandLine * - * Gets the options there were passed to g_application_command_line(). + * Gets the options that were passed to g_application_command_line(). * * If you did not override local_command_line() then these are the same * options that were parsed according to the #GOptionEntrys added to the @@ -12635,6 +12652,9 @@ * If no options were sent then an empty dictionary is returned so that * you don't need to check for %NULL. * + * The data has been passed via an untrusted external process, so the types of + * all values must be checked before being used. + * * Returns: (transfer none): a #GVariantDict with the options * Since: 2.40 */ @@ -12651,9 +12671,12 @@ * information like the current working directory and the startup * notification ID. * + * It comes from an untrusted external process and hence the types of all + * values must be validated before being used. + * * For local invocation, it will be %NULL. * - * Returns: (nullable): the platform data, or %NULL + * Returns: (nullable) (transfer full): the platform data, or %NULL * Since: 2.28 */ @@ -16586,6 +16609,10 @@ * constraint is violated, the export will fail and 0 will be * returned (with @error set accordingly). * + * Exporting menus with sections containing more than + * %G_MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in + * undefined behavior. + * * You can unexport the menu model using * g_dbus_connection_unexport_menu_model() with the return value of * this function. @@ -17282,7 +17309,7 @@ * @user_data_free_func: (nullable): function to free @user_data with when * subscription is removed or %NULL * - * Subscribes to signals on @connection and invokes @callback with a whenever + * Subscribes to signals on @connection and invokes @callback whenever * the signal is received. Note that @callback will be invoked in the * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. @@ -31226,7 +31253,7 @@ * application-wide action (start with "app."). * * If @target is non-%NULL, @action will be activated with @target as - * its parameter. + * its parameter. If @target is floating, it will be consumed. * * When no default action is set, the application that the notification * was sent on is activated. @@ -32764,7 +32791,7 @@ * * Looks into the system proxy configuration to determine what proxy, * if any, to use to connect to @uri. The returned proxy URIs are of - * the form `://[user[:password]@]host:port` or + * the form `://[user[:password]@]host[:port]` or * `direct://`, where could be http, rtsp, socks * or other proxying protocol. * @@ -37019,7 +37046,7 @@ * If there is no implementation for this kind of control message, %NULL * will be returned. * - * Returns: (transfer full): the deserialized message or %NULL + * Returns: (nullable) (transfer full): the deserialized message or %NULL * Since: 2.22 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index e99535dc..5aff475b 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -2942,6 +2942,89 @@ */ +/** + * G_CXX_STD_CHECK_VERSION: + * @version: The C++ version to be checked for compatibility + * + * Macro to check if the current compiler supports a specified @version + * of the C++ standard. Such value must be numeric and can be provided both + * in the short form for the well-known versions (e.g. `11`, `17`...) or in + * the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...). + * + * When a C compiler is used, the macro is defined and returns always %FALSE. + * + * This value is compared against %G_CXX_STD_VERSION. + * + * |[ + * #if G_CXX_STD_CHECK_VERSION(20) + * #endif + * ]| + * + * See also: %G_C_STD_CHECK_VERSION + * + * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise + * Since: 2.76 + */ + + +/** + * G_CXX_STD_VERSION: + * + * The C++ standard version the code is compiling against, it's defined + * with the same value of `__cplusplus` for C++ standard compatible + * compilers, while it uses `_MSVC_LANG` in MSVC, given that the + * standard definition depends on a compilation flag in such compiler. + * + * This is granted to be undefined when not compiling with a C++ compiler. + * + * See also: %G_CXX_STD_CHECK_VERSION and %G_C_STD_VERSION + * + * Since: 2.76 + */ + + +/** + * G_C_STD_CHECK_VERSION: + * @version: The C version to be checked for compatibility + * + * Macro to check if the current compiler supports a specified @version + * of the C standard. Such value must be numeric and can be provided both + * in the short form for the well-known versions (e.g. `90`, `99`...) or in + * the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...). + * + * When a C++ compiler is used, the macro is defined and returns always %FALSE. + * + * This value is compared against %G_C_STD_VERSION. + * + * |[ + * #if G_C_STD_CHECK_VERSION(17) + * #endif + * ]| + * + * See also: %G_CXX_STD_CHECK_VERSION + * + * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise + * Since: 2.76 + */ + + +/** + * G_C_STD_VERSION: + * + * The C standard version the code is compiling against, it's normally + * defined with the same value of `__STDC_VERSION__` for C standard + * compatible compilers, while it uses the lowest standard version + * in pure MSVC, given that in such compiler the definition depends on + * a compilation flag. + * + * This is granted to be undefined when compiling with a C++ compiler. + * + * See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION + * + * Since: 2.76 + */ + + /** * G_DATE_BAD_DAY: * @@ -9634,6 +9717,65 @@ */ +/** + * g_array_new_take: (skip) + * @data: (array length=len) (transfer full) (nullable): an array of + * elements of @element_size, or %NULL for an empty array + * @len: the number of elements in @data + * @clear: %TRUE if #GArray elements should be automatically cleared + * to 0 when they are allocated + * @element_size: the size of each element in bytes + * + * Creates a new #GArray with @data as array data, @len as length and a + * reference count of 1. + * + * This avoids having to copy the data manually, when it can just be + * inherited. @data will eventually be freed using g_free(), so must + * have been allocated with a suitable allocator. + * + * In case the elements need to be cleared when the array is freed, use + * g_array_set_clear_func() to set a #GDestroyNotify function to perform + * such task. + * + * Do not use it if @len or @element_size are greater than %G_MAXUINT. + * #GArray stores the length of its data in #guint, which may be shorter + * than #gsize. + * + * Returns: (transfer full): A new #GArray + * Since: 2.76 + */ + + +/** + * g_array_new_take_zero_terminated: (skip) + * @data: (array zero-terminated=1): an array of elements of @element_size + * @clear: %TRUE if #GArray elements should be automatically cleared + * to 0 when they are allocated + * @element_size: the size of each element in bytes + * + * Creates a new #GArray with @data as array data, computing the length of it + * and setting the reference count to 1. + * + * This avoids having to copy the data manually, when it can just be + * inherited. @data will eventually be freed using g_free(), so must + * have been allocated with a suitable allocator. + * + * The length is calculated by iterating through @data until the first %NULL + * element is found. + * + * In case the elements need to be cleared when the array is freed, use + * g_array_set_clear_func() to set a #GDestroyNotify function to perform + * such task. + * + * Do not use it if @data length or @element_size are greater than %G_MAXUINT. + * #GArray stores the length of its data in #guint, which may be shorter + * than #gsize. + * + * Returns: (transfer full): A new #GArray + * Since: 2.76 + */ + + /** * g_array_prepend_val: * @a: a #GArray @@ -14234,7 +14376,7 @@ /** * g_clear_fd: (skip) - * @fd_ptr: (not nullable): a pointer to a file descriptor + * @fd_ptr: (not optional) (inout) (transfer full): a pointer to a file descriptor * @error: Used to return an error on failure * * If @fd_ptr points to a file descriptor, close it and return @@ -14325,8 +14467,8 @@ /** * g_clear_pointer: (skip) - * @pp: (not nullable): a pointer to a variable, struct member etc. holding a - * pointer + * @pp: (nullable) (not optional) (inout) (transfer full): a pointer to a + * variable, struct member etc. holding a pointer * @destroy: a function to which a gpointer can be passed, to destroy *@pp * * Clears a reference to a variable. @@ -17806,6 +17948,34 @@ */ +/** + * g_find_program_for_path: + * @program: (type filename): a program name in the GLib file name encoding + * @path: (type filename) (nullable): the current dir where to search program + * @working_dir: (type filename) (nullable): the working dir where to search + * program + * + * Locates the first executable named @program in @path, in the + * same way that execvp() would locate it. Returns an allocated string + * with the absolute path name (taking in account the @working_dir), or + * %NULL if the program is not found in @path. If @program is already an + * absolute path, returns a copy of @program if @program exists and is + * executable, and %NULL otherwise. + * + * On Windows, if @path is %NULL, it looks for the file in the same way as + * CreateProcess() would. This means first in the directory where the + * executing program was loaded from, then in the current directory, then in + * the Windows 32-bit system directory, then in the Windows directory, and + * finally in the directories in the `PATH` environment variable. If + * the program is found, the return value contains the full name + * including the type suffix. + * + * Returns: (type filename) (transfer full) (nullable): a newly-allocated + * string with the absolute path, or %NULL + * Since: 2.76 + */ + + /** * g_find_program_in_path: * @program: (type filename): a program name in the GLib file name encoding @@ -18855,6 +19025,25 @@ */ +/** + * g_hash_table_get_keys_as_ptr_array: (skip) + * @hash_table: a #GHashTable + * + * Retrieves every key inside @hash_table, as a #GPtrArray. + * The returned data is valid until changes to the hash release those keys. + * + * This iterates over every entry in the hash table to build its return value. + * To iterate over the entries in a #GHashTable more efficiently, use a + * #GHashTableIter. + * + * You should always unref the returned array with g_ptr_array_unref(). + * + * Returns: (transfer container): a #GPtrArray containing each key from + * the table. Unref with with g_ptr_array_unref() when done. + * Since: 2.76 + */ + + /** * g_hash_table_get_values: * @hash_table: a #GHashTable @@ -18874,6 +19063,25 @@ */ +/** + * g_hash_table_get_values_as_ptr_array: (skip) + * @hash_table: a #GHashTable + * + * Retrieves every value inside @hash_table, as a #GPtrArray. + * The returned data is valid until changes to the hash release those values. + * + * This iterates over every entry in the hash table to build its return value. + * To iterate over the entries in a #GHashTable more efficiently, use a + * #GHashTableIter. + * + * You should always unref the returned array with g_ptr_array_unref(). + * + * Returns: (transfer container): a #GPtrArray containing each value from + * the table. Unref with with g_ptr_array_unref() when done. + * Since: 2.76 + */ + + /** * g_hash_table_insert: * @hash_table: a #GHashTable @@ -19211,6 +19419,36 @@ */ +/** + * g_hash_table_steal_all_keys: (skip) + * @hash_table: a #GHashTable + * + * Removes all keys and their associated values from a #GHashTable + * without calling the key destroy functions, returning the keys + * as a #GPtrArray with the free func set to the @hash_table key + * destroy function. + * + * Returns: (transfer container): a #GPtrArray containing each key of + * the table. Unref with with g_ptr_array_unref() when done. + * Since: 2.76 + */ + + +/** + * g_hash_table_steal_all_values: (skip) + * @hash_table: a #GHashTable + * + * Removes all keys and their associated values from a #GHashTable + * without calling the value destroy functions, returning the values + * as a #GPtrArray with the free func set to the @hash_table value + * destroy function. + * + * Returns: (transfer container): a #GPtrArray containing each value of + * the table. Unref with with g_ptr_array_unref() when done. + * Since: 2.76 + */ + + /** * g_hash_table_steal_extended: * @hash_table: a #GHashTable @@ -26655,6 +26893,67 @@ */ +/** + * g_ptr_array_new_from_array: (skip) + * @data: (array length=len) (transfer none) (nullable): an array of pointers, + * or %NULL for an empty array + * @len: the number of pointers in @data + * @copy_func: (nullable): a copy function used to copy every element in the + * array or %NULL. + * @copy_func_user_data: user data passed to @copy_func, or %NULL + * @element_free_func: (nullable): a function to free elements on @array + * destruction or %NULL + * + * Creates a new #GPtrArray, copying @len pointers from @data, and setting + * the array’s reference count to 1. + * + * This avoids having to manually add each element one by one. + * + * If @copy_func is provided, then it is used to copy each element before + * adding them to the new array. If it is %NULL then the pointers are copied + * directly. + * + * It also sets @element_free_func for freeing each element when the array is + * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called + * with @free_segment set to %TRUE or when removing elements. + * + * Do not use it if @len is greater than %G_MAXUINT. #GPtrArray + * stores the length of its data in #guint, which may be shorter than + * #gsize. + * + * Returns: (transfer full): A new #GPtrArray + * Since: 2.76 + */ + + +/** + * g_ptr_array_new_from_null_terminated_array: (skip) + * @data: (array zero-terminated=1) (transfer none) (nullable): an array of + * pointers, %NULL terminated; or %NULL for an empty array + * @copy_func: (nullable): a copy function used to copy every element in the + * array or %NULL. + * @copy_func_user_data: user data passed to @copy_func, or %NULL + * @element_free_func: (nullable): a function to free elements on @array + * destruction or %NULL + * + * Creates a new #GPtrArray copying the pointers from @data after having + * computed the length of it and with a reference count of 1. + * This avoids having to manually add each element one by one. + * If @copy_func is provided, then it is used to copy the data in the new + * array. + * It also set @element_free_func for freeing each element when the array is + * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called + * with @free_segment set to %TRUE or when removing elements. + * + * Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray + * stores the length of its data in #guint, which may be shorter than + * #gsize. + * + * Returns: (transfer full): A new #GPtrArray + * Since: 2.76 + */ + + /** * g_ptr_array_new_full: * @reserved_size: number of pointers preallocated @@ -26705,6 +27004,62 @@ */ +/** + * g_ptr_array_new_take: (skip) + * @data: (array length=len) (transfer full) (nullable): an array of pointers, + * or %NULL for an empty array + * @len: the number of pointers in @data + * @element_free_func: (nullable): A function to free elements on @array + * destruction or %NULL + * + * Creates a new #GPtrArray with @data as pointers, @len as length and a + * reference count of 1. + * + * This avoids having to copy such data manually. @data will eventually be + * freed using g_free(), so must have been allocated with a suitable allocator. + * + * It also sets @element_free_func for freeing each element when the array is + * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called + * with @free_segment set to %TRUE or when removing elements. + * + * Do not use it if @len is greater than %G_MAXUINT. #GPtrArray + * stores the length of its data in #guint, which may be shorter than + * #gsize. + * + * Returns: (transfer full): A new #GPtrArray + * Since: 2.76 + */ + + +/** + * g_ptr_array_new_take_null_terminated: (skip) + * @data: (array zero-terminated=1) (transfer full) (nullable): an array + * of pointers, %NULL terminated, or %NULL for an empty array + * @element_free_func: (nullable): a function to free elements on @array + * destruction or %NULL + * + * Creates a new #GPtrArray with @data as pointers, computing the length of it + * and setting the reference count to 1. + * + * This avoids having to copy such data manually. @data will eventually be + * freed using g_free(), so must have been allocated with a suitable allocator. + * + * The length is calculated by iterating through @data until the first %NULL + * element is found. + * + * It also sets @element_free_func for freeing each element when the array is + * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called + * with @free_segment set to %TRUE or when removing elements. + * + * Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray + * stores the length of its data in #guint, which may be shorter than + * #gsize. + * + * Returns: (transfer full): A new #GPtrArray + * Since: 2.76 + */ + + /** * g_ptr_array_new_with_free_func: * @element_free_func: (nullable): A function to free elements with @@ -26862,12 +27217,15 @@ * * Sorts the array, using @compare_func which should be a qsort()-style * comparison function (returns less than zero for first arg is less - * than second arg, zero for equal, greater than zero if irst arg is + * than second arg, zero for equal, greater than zero if first arg is * greater than second arg). * * Note that the comparison function for g_ptr_array_sort() doesn't * take the pointers from the array as arguments, it takes pointers to - * the pointers in the array. Here is a full example of usage: + * the pointers in the array. + * + * Use g_ptr_array_sort_with_data() if you want to use normal + * #GCompareFuncs, otherwise here is a full example of use: * * |[ * typedef struct @@ -26898,6 +27256,37 @@ */ +/** + * g_ptr_array_sort_values: + * @array: a #GPtrArray + * @compare_func: a #GCompareFunc comparison function + * + * Sorts the array, using @compare_func which should be a qsort()-style + * comparison function (returns less than zero for first arg is less + * than second arg, zero for equal, greater than zero if first arg is + * greater than second arg). + * + * This is guaranteed to be a stable sort. + * + * Since: 2.76 + */ + + +/** + * g_ptr_array_sort_values_with_data: + * @array: a #GPtrArray + * @compare_func: a #GCompareDataFunc comparison function + * @user_data: data to pass to @compare_func + * + * Like g_ptr_array_sort_values(), but the comparison function has an extra + * user data argument. + * + * This is guaranteed to be a stable sort. + * + * Since: 2.76 + */ + + /** * g_ptr_array_sort_with_data: * @array: a #GPtrArray @@ -26909,7 +27298,10 @@ * * Note that the comparison function for g_ptr_array_sort_with_data() * doesn't take the pointers from the array as arguments, it takes - * pointers to the pointers in the array. Here is a full example of use: + * pointers to the pointers in the array. + * + * Use g_ptr_array_sort_with_data() if you want to use normal + * #GCompareDataFuncs, otherwise here is a full example of use: * * |[ * typedef enum { SORT_NAME, SORT_SIZE } SortMode; @@ -32379,12 +32771,12 @@ * @dest: destination buffer. * @src: source string. * - * Copies a nul-terminated string into the dest buffer, include the - * trailing nul, and return a pointer to the trailing nul byte. - * This is useful for concatenating multiple strings together - * without having to repeatedly scan for the end. + * Copies a nul-terminated string into the destination buffer, including + * the trailing nul byte, and returns a pointer to the trailing nul byte + * in `dest`. The return value is useful for concatenating multiple + * strings without having to repeatedly scan for the end. * - * Returns: a pointer to trailing nul byte. + * Returns: a pointer to the trailing nul byte in `dest`. */ @@ -34313,6 +34705,8 @@ * * This function returns a valid string only within a test function. * + * Note that this is a test path, not a file system path. + * * Returns: the test path for the test currently being run * Since: 2.68 */ @@ -39597,6 +39991,11 @@ * contain multi-byte numeric data. That include strings, booleans, * bytes and containers containing only these things (recursively). * + * While this function can safely handle untrusted, non-normal data, it is + * recommended to check whether the input is in normal form beforehand, using + * g_variant_is_normal_form(), and to reject non-normal inputs if your + * application can be strict about what inputs it rejects. + * * The returned value is always in normal form and is marked as trusted. * A full, not floating, reference is returned. * @@ -40352,7 +40751,9 @@ * marked as trusted and a new reference to it is returned. * * If @value is found not to be in normal form then a new trusted - * #GVariant is created with the same value as @value. + * #GVariant is created with the same value as @value. The non-normal parts of + * @value will be replaced with default values which are guaranteed to be in + * normal form. * * It makes sense to call this function if you've received #GVariant * data from untrusted sources and you want to ensure your serialized @@ -41006,6 +41407,31 @@ */ +/** + * g_variant_maybe_get_child_value: + * @value: a container #GVariant + * @index_: the index of the child to fetch + * + * Reads a child item out of a container #GVariant instance, if it is in normal + * form. If it is not in normal form, return %NULL. + * + * This function behaves the same as g_variant_get_child_value(), except that it + * returns %NULL if the child is not in normal form. g_variant_get_child_value() + * would instead return a new default value of the correct type. + * + * This is intended to be used internally to avoid unnecessary #GVariant + * allocations. + * + * The returned value is never floating. You should free it with + * g_variant_unref() when you're done with it. + * + * This function is O(1). + * + * Returns: (transfer full): the child at the specified index + * Since: 2.74 + */ + + /** * g_variant_n_children: * @value: a container #GVariant diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 2eed6c7b..ca6d1dd3 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -2088,7 +2088,7 @@ * * @destroy_data will be called as a finalize notifier on the #GClosure. * - * Returns: (transfer none): a floating reference to a new #GCClosure + * Returns: (transfer floating): a floating reference to a new #GCClosure */ @@ -2133,7 +2133,7 @@ * * @destroy_data will be called as a finalize notifier on the #GClosure. * - * Returns: (transfer none): a floating reference to a new #GCClosure + * Returns: (transfer floating): a floating reference to a new #GCClosure */ @@ -2322,7 +2322,7 @@ * } * ]| * - * Returns: (transfer none): a floating reference to a new #GClosure + * Returns: (transfer floating): a floating reference to a new #GClosure */ @@ -3331,7 +3331,7 @@ * @object_type: the type id of the #GObject subtype to instantiate * @first_property_name: the name of the first property * @...: the value of the first property, followed optionally by more - * name/value pairs, followed by %NULL + * name/value pairs, followed by %NULL * * Creates a new instance of a #GObject subtype and sets its properties. * @@ -3341,22 +3341,22 @@ * per g_type_create_instance(). * * Note that in C, small integer types in variable argument lists are promoted - * up to #gint or #guint as appropriate, and read back accordingly. #gint is 32 - * bits on every platform on which GLib is currently supported. This means that - * you can use C expressions of type #gint with g_object_new() and properties of - * type #gint or #guint or smaller. Specifically, you can use integer literals + * up to `gint` or `guint` as appropriate, and read back accordingly. `gint` is + * 32 bits on every platform on which GLib is currently supported. This means that + * you can use C expressions of type `gint` with g_object_new() and properties of + * type `gint` or `guint` or smaller. Specifically, you can use integer literals * with these property types. * - * When using property types of #gint64 or #guint64, you must ensure that the + * When using property types of `gint64` or `guint64`, you must ensure that the * value that you provide is 64 bit. This means that you should use a cast or * make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. * - * Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value - * you provide is a #gdouble, even for a property of type #gfloat. + * Similarly, `gfloat` is promoted to `gdouble`, so you must ensure that the value + * you provide is a `gdouble`, even for a property of type `gfloat`. * * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the - * alignment of the largest basic GLib type (typically this is #guint64 or - * #gdouble). If you need larger alignment for an element in a #GObject, you + * alignment of the largest basic GLib type (typically this is `guint64` or + * `gdouble`). If you need larger alignment for an element in a #GObject, you * should allocate it on the heap (aligned), or arrange for your #GObject to be * appropriately padded. * @@ -4842,6 +4842,9 @@ * * Connects a closure to a signal for a particular object. * + * If @closure is a floating reference (see g_closure_sink()), this function + * takes ownership of @closure. + * * Returns: the handler ID (always greater than 0 for successful connections) */ @@ -4857,6 +4860,9 @@ * * Connects a closure to a signal for a particular object. * + * If @closure is a floating reference (see g_closure_sink()), this function + * takes ownership of @closure. + * * Returns: the handler ID (always greater than 0 for successful connections) */ @@ -5694,7 +5700,7 @@ * @struct_offset in the class structure of the interface or classed type * identified by @itype. * - * Returns: (transfer none): a floating reference to a new #GCClosure + * Returns: (transfer floating): a floating reference to a new #GCClosure */ -- cgit v1.2.1