diff options
author | Marco Trevisan (Treviño) <mail@3v1n0.net> | 2022-06-28 04:18:59 +0200 |
---|---|---|
committer | Marco Trevisan (Treviño) <mail@3v1n0.net> | 2022-06-28 04:18:59 +0200 |
commit | 81f710be203d8f6d91dfcebc793c538024862ea2 (patch) | |
tree | 34da00115f1b8935193984bd2ddd69809ad9c2b9 /gir | |
parent | 79c4759db4043fd10cb3dd962cb2e8f9e926395e (diff) | |
download | gobject-introspection-81f710be203d8f6d91dfcebc793c538024862ea2.tar.gz |
gir: Update introspection data to GLib 2.73.1
Based on https://gitlab.gnome.org/GNOME/glib/-/commit/113d7263
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 255 | ||||
-rw-r--r-- | gir/glib-2.0.c | 284 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 41 |
3 files changed, 526 insertions, 54 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index d0adef41..c7480616 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -1681,7 +1681,20 @@ * ways indicated here will be rejected unless the application * overrides the default via #GDtlsConnection::accept-certificate. * + * GLib guarantees that if certificate verification fails, at least one + * flag will be set, but it does not guarantee that all possible flags + * will be set. Accordingly, you may not safely decide to ignore any + * particular type of error. For example, it would be incorrect to mask + * %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, + * because this could potentially be the only error flag set even if + * other problems exist with the certificate. Therefore, there is no + * safe way to use this property. This is not a horrible problem, + * though, because you should not be attempting to ignore validation + * errors anyway. If you really must ignore TLS certificate errors, + * connect to #GDtlsConnection::accept-certificate. + * * Since: 2.48 + * Deprecated: 2.74: Do not attempt to ignore validation errors. */ @@ -2251,6 +2264,15 @@ /** + * GListStore:n-items: + * + * The number of items contained in this list store. + * + * Since: 2.74 + */ + + +/** * GMemoryMonitor: * * #GMemoryMonitor monitors system memory and indicates when @@ -6739,6 +6761,8 @@ * - g_file_new_for_uri() if you have a URI. * - g_file_new_for_commandline_arg() for a command line argument. * - g_file_new_tmp() to create a temporary file from a template. + * - g_file_new_tmp_async() to asynchronously create a temporary file. + * - g_file_new_tmp_dir_async() to asynchronously create a temporary directory. * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). * - g_file_new_build_filename() to create a file from path elements. * @@ -7420,6 +7444,21 @@ * implementation, but typically it will be from the thread that owns * the [thread-default main context][g-main-context-push-thread-default] * in effect at the time that the model was created. + * + * Over time, it has established itself as good practice for listmodel + * implementations to provide properties `item-type` and `n-items` to + * ease working with them. While it is not required, it is recommended + * that implementations provide these two properties. They should return + * the values of g_list_model_get_item_type() and g_list_model_get_n_items() + * respectively and be defined as such: + * |[<!-- language="C" --> + * properties[PROP_ITEM_TYPE] = + * g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT, + * G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); + * properties[PROP_N_ITEMS] = + * g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0, + * G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + * ]| */ @@ -10340,9 +10379,11 @@ * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() * and received using g_socket_receive_message(). * - * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. + * Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO + * interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when + * using it. + * + * Since 2.74, the API is available for Windows. */ @@ -11737,6 +11778,37 @@ /** + * g_app_info_get_default_for_type_async: + * @content_type: the content type to find a #GAppInfo for + * @must_support_uris: if %TRUE, the #GAppInfo is expected to + * support URIs + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done + * @user_data: (nullable): data to pass to @callback + * + * Asynchronously gets the default #GAppInfo for a given content type. + * + * Since: 2.74 + */ + + +/** + * g_app_info_get_default_for_type_finish: + * @result: a #GAsyncResult + * @error: (nullable): a #GError + * + * Finishes a default #GAppInfo lookup started by + * g_app_info_get_default_for_type_async(). + * + * If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. + * + * Returns: (transfer full): #GAppInfo for given @content_type or + * %NULL on error. + * Since: 2.74 + */ + + +/** * g_app_info_get_default_for_uri_scheme: * @uri_scheme: a string containing a URI scheme. * @@ -11751,6 +11823,38 @@ /** + * g_app_info_get_default_for_uri_scheme_async: + * @uri_scheme: a string containing a URI scheme. + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done + * @user_data: (nullable): data to pass to @callback + * + * Asynchronously gets the default application for handling URIs with + * the given URI scheme. A URI scheme is the initial part + * of the URI, up to but not including the ':', e.g. "http", + * "ftp" or "sip". + * + * Since: 2.74 + */ + + +/** + * g_app_info_get_default_for_uri_scheme_finish: + * @result: a #GAsyncResult + * @error: (nullable): a #GError + * + * Finishes a default #GAppInfo lookup started by + * g_app_info_get_default_for_uri_scheme_async(). + * + * If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. + * + * Returns: (transfer full): #GAppInfo for given @uri_scheme or + * %NULL on error. + * Since: 2.74 + */ + + +/** * g_app_info_get_description: * @appinfo: a #GAppInfo. * @@ -21244,8 +21348,13 @@ * * Gets @conn's validation flags * + * This function does not work as originally designed and is impossible + * to use correctly. See #GDtlsClientConnection:validation-flags for more + * information. + * * Returns: the validation flags * Since: 2.48 + * Deprecated: 2.74: Do not attempt to ignore validation errors. */ @@ -21287,7 +21396,12 @@ * checks performed when validating a server certificate. By default, * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. * + * This function does not work as originally designed and is impossible + * to use correctly. See #GDtlsClientConnection:validation-flags for more + * information. + * * Since: 2.48 + * Deprecated: 2.74: Do not attempt to ignore validation errors. */ @@ -23369,6 +23483,9 @@ * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime * will have microsecond precision. * + * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must + * be queried separately using g_file_info_get_attribute_uint32(). + * * Returns: (transfer full) (nullable): access time, or %NULL if unknown * Since: 2.70 */ @@ -23568,6 +23685,9 @@ * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime * will have microsecond precision. * + * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must + * be queried separately using g_file_info_get_attribute_uint32(). + * * Returns: (transfer full) (nullable): creation time, or %NULL if unknown * Since: 2.70 */ @@ -23679,6 +23799,9 @@ * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime * will have microsecond precision. * + * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must + * be queried separately using g_file_info_get_attribute_uint32(). + * * Returns: (transfer full) (nullable): modification time, or %NULL if unknown * Since: 2.62 */ @@ -23818,6 +23941,8 @@ * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the * given date/time value. * + * %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared. + * * Since: 2.70 */ @@ -23982,6 +24107,8 @@ * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the * given date/time value. * + * %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared. + * * Since: 2.70 */ @@ -24055,6 +24182,8 @@ * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the * given date/time value. * + * %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. + * * Since: 2.62 */ @@ -24068,6 +24197,8 @@ * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the * given time value. * + * %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. + * * Deprecated: 2.62: Use g_file_info_set_modification_date_time() instead, as * #GTimeVal is deprecated due to the year 2038 problem. */ @@ -24577,6 +24708,39 @@ /** + * g_file_make_symbolic_link_async: (virtual make_symbolic_link_async) + * @file: a #GFile with the name of the symlink to create + * @symlink_value: (type filename): a string with the path for the target + * of the new symlink + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously creates a symbolic link named @file which contains the + * string @symlink_value. + * + * Since: 2.74 + */ + + +/** + * g_file_make_symbolic_link_finish: (virtual make_symbolic_link_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous symbolic link creation, started with + * g_file_make_symbolic_link_async(). + * + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.74 + */ + + +/** * g_file_measure_disk_usage: * @file: a #GFile * @flags: #GFileMeasureFlags @@ -25069,6 +25233,74 @@ /** + * g_file_new_tmp_async: + * @tmpl: (type filename) (nullable): Template for the file + * name, as in g_file_open_tmp(), or %NULL for a default template + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done + * @user_data: (nullable): data to pass to @callback + * + * Asynchronously opens a file in the preferred directory for temporary files + * (as returned by g_get_tmp_dir()) as g_file_new_tmp(). + * + * @tmpl should be a string in the GLib file name encoding + * containing a sequence of six 'X' characters, and containing no + * directory components. If it is %NULL, a default template is used. + * + * Since: 2.74 + */ + + +/** + * g_file_new_tmp_dir_async: + * @tmpl: (type filename) (nullable): Template for the file + * name, as in g_dir_make_tmp(), or %NULL for a default template + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done + * @user_data: (nullable): data to pass to @callback + * + * Asynchronously creates a directory in the preferred directory for + * temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). + * + * @tmpl should be a string in the GLib file name encoding + * containing a sequence of six 'X' characters, and containing no + * directory components. If it is %NULL, a default template is used. + * + * Since: 2.74 + */ + + +/** + * g_file_new_tmp_dir_finish: + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes a temporary directory creation started by + * g_file_new_tmp_dir_async(). + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). + * Since: 2.74 + */ + + +/** + * g_file_new_tmp_finish: + * @result: a #GAsyncResult + * @iostream: (out) (not nullable) (transfer full): on return, a #GFileIOStream for the created file + * @error: a #GError, or %NULL + * + * Finishes a temporary file creation started by g_file_new_tmp_async(). + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). + * Since: 2.74 + */ + + +/** * g_file_open_readwrite: * @file: #GFile to open * @cancellable: (nullable): a #GCancellable @@ -27631,6 +27863,17 @@ /** + * g_io_error_from_file_error: + * @file_error: a #GFileError. + * + * Converts #GFileError error codes into GIO error codes. + * + * Returns: #GIOErrorEnum value for the given #GFileError error value. + * Since: 2.74 + */ + + +/** * g_io_error_from_win32_error: * @error_code: Windows error number. * @@ -35651,7 +35894,7 @@ * internal errors (other than @cancellable being triggered) will be * ignored. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * Returns: (transfer full) (nullable): a #GSocketAddress (owned by the caller), or %NULL on * error (in which case *@error will be set) or if there are no * more addresses. */ @@ -35684,7 +35927,7 @@ * g_socket_address_enumerator_next() for more information about * error handling. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * Returns: (transfer full) (nullable): a #GSocketAddress (owned by the caller), or %NULL on * error (in which case *@error will be set) or if there are no * more addresses. */ @@ -40601,6 +40844,8 @@ * check a certificate against a CA that is not part of the system * CA database. * + * If @cert is valid, %G_TLS_CERTIFICATE_FLAGS_NONE is returned. + * * If @identity is not %NULL, @cert's name(s) will be compared against * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return * value if it does not match. If @identity is %NULL, that bit will diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index ba9e2b8f..ecd53364 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -682,7 +682,7 @@ /** * GHookCheckMarshaller: * @hook: a #GHook - * @marshal_data: user data + * @user_data: user data * * Defines the type of function used by g_hook_list_marshal_check(). * @@ -715,7 +715,7 @@ /** * GHookFindFunc: * @hook: a #GHook - * @data: user data passed to g_hook_find_func() + * @user_data: user data passed to g_hook_find_func() * * Defines the type of the function passed to g_hook_find(). * @@ -761,7 +761,7 @@ /** * GHookMarshaller: * @hook: a #GHook - * @marshal_data: user data + * @user_data: user data * * Defines the type of function used by g_hook_list_marshal(). */ @@ -994,6 +994,7 @@ /** * GIOFlags: + * @G_IO_FLAG_NONE: no special flags set. Since: 2.74 * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND * (see the documentation of the UNIX open() syscall) * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to @@ -1025,7 +1026,7 @@ * GIOFunc: * @source: the #GIOChannel event source * @condition: the condition which has been satisfied - * @data: user data set in g_io_add_watch() or g_io_add_watch_full() + * @user_data: user data set in g_io_add_watch() or g_io_add_watch_full() * * Specifies the type of function passed to g_io_add_watch() or * g_io_add_watch_full(), which is called when the requested condition @@ -1127,8 +1128,10 @@ * @minor: the minor version to check for * @micro: the micro version to check for * - * Checks the version of the GLib library that is being compiled - * against. See glib_check_version() for a runtime check. + * Checks whether the version of the GLib library that is being compiled + * against is greater than or equal to the given one. + * + * See glib_check_version() for a runtime check. * * Returns: %TRUE if the version of the GLib header files * is the same as or newer than the passed-in version. @@ -1384,7 +1387,7 @@ /** * GNodeForeachFunc: * @node: a #GNode. - * @data: user data passed to g_node_children_foreach(). + * @user_data: user data passed to g_node_children_foreach(). * * Specifies the type of function passed to g_node_children_foreach(). * The function is called with each child node, together with the user @@ -1395,7 +1398,7 @@ /** * GNodeTraverseFunc: * @node: a #GNode. - * @data: user data passed to g_node_traverse(). + * @user_data: user data passed to g_node_traverse(). * * Specifies the type of function passed to g_node_traverse(). The * function is called with each of the nodes visited, together with the @@ -1855,7 +1858,7 @@ * GSequenceIterCompareFunc: * @a: a #GSequenceIter * @b: a #GSequenceIter - * @data: user data + * @user_data: user data * * A #GSequenceIterCompareFunc is a function used to compare iterators. * It must return zero if the iterators compare equal, a negative value @@ -1991,6 +1994,7 @@ /** * GTestSubprocessFlags: + * @G_TEST_SUBPROCESS_DEFAULT: Default behaviour. Since: 2.74 * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child * process will inherit the parent's stdin. Otherwise, the child's * stdin is redirected to `/dev/null`. @@ -2047,7 +2051,7 @@ /** * GThreadFunc: - * @data: data passed to the thread + * @user_data: data passed to the thread * * Specifies the type of the @func functions passed to g_thread_new() * or g_thread_try_new(). @@ -2220,7 +2224,7 @@ * GTraverseFunc: * @key: a key of a #GTree node * @value: the value corresponding to the key - * @data: user data passed to g_tree_traverse() + * @user_data: user data passed to g_tree_traverse() * * Specifies the type of function passed to g_tree_traverse(). It is * passed the key and value of each node, together with the @user_data @@ -11154,6 +11158,31 @@ /** + * g_atomic_int_compare_and_exchange_full: + * @atomic: a pointer to a #gint or #guint + * @oldval: the value to compare with + * @newval: the value to conditionally replace with + * @preval: (out): the contents of @atomic before this operation + * + * Compares @atomic to @oldval and, if equal, sets it to @newval. + * If @atomic was not equal to @oldval then no change occurs. + * In any case the value of @atomic before this operation is stored in @preval. + * + * This compare and exchange is done atomically. + * + * Think of this operation as an atomic version of + * `{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. + * + * This call acts as a full compiler and hardware memory barrier. + * + * See also g_atomic_int_compare_and_exchange() + * + * Returns: %TRUE if the exchange took place + * Since: 2.74 + */ + + +/** * g_atomic_int_dec_and_test: * @atomic: a pointer to a #gint or #guint * @@ -11173,6 +11202,25 @@ /** + * g_atomic_int_exchange: + * @atomic: a pointer to a #gint or #guint + * @newval: the value to replace with + * + * Sets the @atomic to @newval and returns the old value from @atomic. + * + * This exchange is done atomically. + * + * Think of this operation as an atomic version of + * `{ tmp = *atomic; *atomic = val; return tmp; }`. + * + * This call acts as a full compiler and hardware memory barrier. + * + * Returns: the value of @atomic before the exchange, signed + * Since: 2.74 + */ + + +/** * g_atomic_int_exchange_and_add: * @atomic: a pointer to a #gint * @val: the value to add @@ -11346,6 +11394,50 @@ /** + * g_atomic_pointer_compare_and_exchange_full: + * @atomic: (not nullable): a pointer to a #gpointer-sized value + * @oldval: the value to compare with + * @newval: the value to conditionally replace with + * @preval: (not nullable) (out): the contents of @atomic before this operation + * + * Compares @atomic to @oldval and, if equal, sets it to @newval. + * If @atomic was not equal to @oldval then no change occurs. + * In any case the value of @atomic before this operation is stored in @preval. + * + * This compare and exchange is done atomically. + * + * Think of this operation as an atomic version of + * `{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. + * + * This call acts as a full compiler and hardware memory barrier. + * + * See also g_atomic_pointer_compare_and_exchange() + * + * Returns: %TRUE if the exchange took place + * Since: 2.74 + */ + + +/** + * g_atomic_pointer_exchange: + * @atomic: a pointer to a #gpointer-sized value + * @newval: the value to replace with + * + * Sets the @atomic to @newval and returns the old value from @atomic. + * + * This exchange is done atomically. + * + * Think of this operation as an atomic version of + * `{ tmp = *atomic; *atomic = val; return tmp; }`. + * + * This call acts as a full compiler and hardware memory barrier. + * + * Returns: the value of @atomic before the exchange + * Since: 2.74 + */ + + +/** * g_atomic_pointer_get: * @atomic: (not nullable): a pointer to a #gpointer-sized value * @@ -14573,6 +14665,21 @@ /** + * g_datalist_id_remove_multiple: + * @datalist: a datalist + * @keys: (array length=n_keys): keys to remove + * @n_keys: length of @keys, must be <= 16 + * + * Removes multiple keys from a datalist. + * + * This is more efficient than calling g_datalist_id_remove_data() + * multiple times in a row. + * + * Since: 2.74 + */ + + +/** * g_datalist_id_remove_no_notify: (skip) * @datalist: a datalist. * @key_id: the #GQuark identifying a data element. @@ -15618,7 +15725,8 @@ * - \%c: the preferred date and time representation for the current locale * - \%C: the century number (year/100) as a 2-digit integer (00-99) * - \%d: the day of the month as a decimal number (range 01 to 31) - * - \%e: the day of the month as a decimal number (range 1 to 31) + * - \%e: the day of the month as a decimal number (range 1 to 31); + * single digits are preceded by a figure space * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) * - \%g: the last two digits of the ISO 8601 week-based year as a * decimal number (00-99). This works well with \%V and \%u. @@ -15629,9 +15737,9 @@ * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) * - \%j: the day of the year as a decimal number (range 001 to 366) * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); - * single digits are preceded by a blank + * single digits are preceded by a figure space * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); - * single digits are preceded by a blank + * single digits are preceded by a figure space * - \%m: the month as a decimal number (range 01 to 12) * - \%M: the minute as a decimal number (range 00 to 59) * - \%f: the microsecond as a decimal number (range 000000 to 999999) @@ -19456,6 +19564,25 @@ /** + * g_idle_add_once: + * @function: function to call + * @data: data to pass to @function + * + * Adds a function to be called whenever there are no higher priority + * events pending to the default main loop. The function is given the + * default idle priority, %G_PRIORITY_DEFAULT_IDLE. + * + * The function will only be called once and then the source will be + * automatically removed from the main context. + * + * This function otherwise behaves like g_idle_add(). + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.74 + */ + + +/** * g_idle_remove_by_data: * @data: the data for the idle source's callback. * @@ -24328,7 +24455,7 @@ * Calling g_mutex_clear() on a locked mutex leads to undefined * behaviour. * - * Sine: 2.32 + * Since: 2.32 */ @@ -25999,7 +26126,8 @@ * pointing to) are copied to the new #GPtrArray. * * The copy of @array will have the same #GDestroyNotify for its elements as - * @array. + * @array. The copy will also be %NULL terminated if (and only if) the source + * array is. * * Returns: (transfer full): a deep copy of the initial #GPtrArray. * Since: 2.62 @@ -26026,6 +26154,8 @@ * If @func is %NULL, then only the pointers (and not what they are * pointing to) are copied to the new #GPtrArray. * + * Whether @array_to_extend is %NULL terminated stays unchanged by this function. + * * Since: 2.62 */ @@ -26122,6 +26252,10 @@ * be freed separately if @free_seg is %TRUE and no #GDestroyNotify * function has been set for @array. * + * Note that if the array is %NULL terminated and @free_seg is %FALSE + * then this will always return an allocated %NULL terminated buffer. + * If pdata is previously %NULL, a new buffer will be allocated. + * * This function is not thread-safe. If using a #GPtrArray from multiple * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() * functions. @@ -26159,6 +26293,22 @@ /** + * g_ptr_array_is_null_terminated: + * @array: the #GPtrArray + * + * Gets whether the @array was constructed as %NULL-terminated. + * + * This will only return %TRUE for arrays constructed by passing %TRUE to the + * `null_terminated` argument of g_ptr_array_new_null_terminated(). It will not + * return %TRUE for normal arrays which have had a %NULL element appended to + * them. + * + * Returns: %TRUE if the array is made to be %NULL terminated. + * Since: 2.74 + */ + + +/** * g_ptr_array_new: * * Creates a new #GPtrArray with a reference count of 1. @@ -26181,12 +26331,43 @@ * g_ptr_array_unref(), when g_ptr_array_free() is called with * @free_segment set to %TRUE or when removing elements. * - * Returns: A new #GPtrArray + * Returns: (transfer full): A new #GPtrArray * Since: 2.30 */ /** + * g_ptr_array_new_null_terminated: + * @reserved_size: number of pointers preallocated. + * If @null_terminated is %TRUE, the actually allocated + * buffer size is @reserved_size plus 1, unless @reserved_size + * is zero, in which case no initial buffer gets allocated. + * @element_free_func: (nullable): A function to free elements with + * destroy @array or %NULL + * @null_terminated: whether to make the array as %NULL terminated. + * + * Like g_ptr_array_new_full() but also allows to set the array to + * be %NULL terminated. A %NULL terminated pointer array has an + * additional %NULL pointer after the last element, beyond the + * current length. + * + * #GPtrArray created by other constructors are not automatically %NULL + * terminated. + * + * Note that if the @array's length is zero and currently no + * data array is allocated, then pdata will still be %NULL. + * %GPtrArray will only %NULL terminate pdata, if an actual + * array is allocated. It does not guarantee that an array + * is always allocated. In other words, if the length is zero, + * then pdata may either point to a %NULL terminated array of length + * zero or be %NULL. + * + * Returns: (transfer full): A new #GPtrArray + * Since: 2.74 + */ + + +/** * g_ptr_array_new_with_free_func: * @element_free_func: (nullable): A function to free elements with * destroy @array or %NULL @@ -26196,7 +26377,7 @@ * either via g_ptr_array_unref(), when g_ptr_array_free() is called with * @free_segment set to %TRUE or when removing elements. * - * Returns: A new #GPtrArray + * Returns: (transfer full): A new #GPtrArray * Since: 2.22 */ @@ -26451,6 +26632,10 @@ * the underlying array is preserved for use elsewhere and returned * to the caller. * + * Note that if the array is %NULL terminated this may still return + * %NULL if the length of the array was zero and pdata was not yet + * allocated. + * * Even if set, the #GDestroyNotify function will never be called * on the current contents of the array and the caller is * responsible for freeing the array elements. @@ -26488,8 +26673,9 @@ * g_assert (chunk_buffer->len == 0); * ]| * - * Returns: (transfer full): the element data, which should be - * freed using g_free(). + * Returns: (transfer full) (nullable): the element data, which should be + * freed using g_free(). This may be %NULL if the array doesn’t have any + * elements (i.e. if `*len` is zero). * Since: 2.64 */ @@ -27542,7 +27728,7 @@ * Calling g_rec_mutex_clear() on a locked recursive mutex leads * to undefined behaviour. * - * Sine: 2.32 + * Since: 2.32 */ @@ -27936,7 +28122,7 @@ * GRegex *regex; * GMatchInfo *match_info; * - * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); + * regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); * g_regex_match (regex, string, 0, &match_info); * while (g_match_info_matches (match_info)) * { @@ -28086,7 +28272,7 @@ * GMatchInfo *match_info; * GError *error = NULL; * - * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); + * regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); * while (g_match_info_matches (match_info)) * { @@ -28252,7 +28438,7 @@ * g_hash_table_insert (h, "3", "THREE"); * g_hash_table_insert (h, "4", "FOUR"); * - * reg = g_regex_new ("1|2|3|4", 0, 0, NULL); + * reg = g_regex_new ("1|2|3|4", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL); * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); * g_hash_table_destroy (h); * @@ -28511,7 +28697,7 @@ * Calling g_rw_lock_clear() when any thread holds the lock * leads to undefined behaviour. * - * Sine: 2.32 + * Since: 2.32 */ @@ -31456,17 +31642,23 @@ * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP * are used, the value from @envp takes precedence over the environment. * + * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's + * standard input (by default, the child's standard input is attached to + * `/dev/null`). %G_SPAWN_STDIN_FROM_DEV_NULL explicitly imposes the default + * behavior. Both flags cannot be enabled at the same time and, in both cases, + * the @stdin_pipe_out argument is ignored. + * * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output - * will be discarded, instead of going to the same location as the parent's - * standard output. If you use this flag, @stdout_pipe_out must be %NULL. + * will be discarded (by default, it goes to the same location as the parent's + * standard output). %G_SPAWN_CHILD_INHERITS_STDOUT explicitly imposes the + * default behavior. Both flags cannot be enabled at the same time and, in + * both cases, the @stdout_pipe_out argument is ignored. * * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error - * will be discarded, instead of going to the same location as the parent's - * standard error. If you use this flag, @stderr_pipe_out must be %NULL. - * - * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's - * standard input (by default, the child's standard input is attached to - * `/dev/null`). If you use this flag, @stdin_pipe_out must be %NULL. + * will be discarded (by default, it goes to the same location as the parent's + * standard error). %G_SPAWN_CHILD_INHERITS_STDERR explicitly imposes the + * default behavior. Both flags cannot be enabled at the same time and, in + * both cases, the @stderr_pipe_out argument is ignored. * * It is valid to pass the same FD in multiple parameters (e.g. you can pass * a single FD for both @stdout_fd and @stderr_fd, and include it in @@ -34578,7 +34770,7 @@ * } * * // Reruns this same test in a subprocess - * g_test_trap_subprocess (NULL, 0, 0); + * g_test_trap_subprocess (NULL, 0, G_TEST_SUBPROCESS_DEFAULT); * g_test_trap_assert_failed (); * g_test_trap_assert_stderr ("*ERROR*too large*"); * } @@ -35555,6 +35747,26 @@ /** + * g_timeout_add_once: + * @interval: the time after which the function will be called, in + * milliseconds (1/1000ths of a second) + * @function: function to call + * @data: data to pass to @function + * + * Sets a function to be called after @interval milliseconds have elapsed, + * with the default priority, %G_PRIORITY_DEFAULT. + * + * The given @function is called once and then the source will be automatically + * removed from the main context. + * + * This function otherwise behaves like g_timeout_add(). + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.74 + */ + + +/** * g_timeout_add_seconds: * @interval: the time between calls to the function, in seconds * @function: function to call @@ -37134,7 +37346,7 @@ /** * g_unix_open_pipe: - * @fds: Array of two integers + * @fds: (array fixed-size=2): Array of two integers * @flags: Bitfield of file descriptor flags, as for fcntl() * @error: a #GError * @@ -39266,7 +39478,7 @@ * returned. If @expected_type was specified then any non-%NULL return * value will have this type. * - * Returns: (transfer full): the value of the dictionary key, or %NULL + * Returns: (transfer full) (nullable): the value of the dictionary key, or %NULL * Since: 2.40 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index cfbf3473..4a0cc83a 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -2879,9 +2879,11 @@ * class initialization: * * |[<!-- language="C" --> - * enum { - * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES - * }; + * typedef enum { + * PROP_FOO = 1, + * PROP_BAR, + * N_PROPERTIES + * } MyObjectProperty; * * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; * @@ -2894,17 +2896,17 @@ * g_param_spec_int ("foo", "Foo", "Foo", * -1, G_MAXINT, * 0, - * G_PARAM_READWRITE); + * G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); * * obj_properties[PROP_BAR] = * g_param_spec_string ("bar", "Bar", "Bar", * NULL, - * G_PARAM_READWRITE); + * G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); * * gobject_class->set_property = my_object_set_property; * gobject_class->get_property = my_object_get_property; * g_object_class_install_properties (gobject_class, - * N_PROPERTIES, + * G_N_ELEMENTS (obj_properties), * obj_properties); * } * ]| @@ -2998,8 +3000,8 @@ * * The signal specs expected by this function have the form * "modifier::signal_name", where modifier can be one of the following: - * - signal: equivalent to g_signal_connect_data (..., NULL, 0) - * - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) + * - signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT) + * - object-signal, object_signal: equivalent to g_signal_connect_object (..., G_CONNECT_DEFAULT) * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) @@ -3451,12 +3453,11 @@ * g_object_class_install_property() inside a static array, e.g.: * * |[<!-- language="C" --> - * enum + * typedef enum * { - * PROP_0, - * PROP_FOO, + * PROP_FOO = 1, * PROP_LAST - * }; + * } MyObjectProperty; * * static GParamSpec *properties[PROP_LAST]; * @@ -3466,7 +3467,7 @@ * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", * 0, 100, * 50, - * G_PARAM_READWRITE); + * G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); * g_object_class_install_property (gobject_class, * PROP_FOO, * properties[PROP_FOO]); @@ -4676,6 +4677,20 @@ /** + * g_param_value_is_valid: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Return whether the contents of @value comply with the specifications + * set out by @pspec. + * + * Returns: whether the contents of @value comply with the specifications + * set out by @pspec. + * Since: 2.74 + */ + + +/** * g_param_value_set_default: * @pspec: a valid #GParamSpec * @value: a #GValue of correct type for @pspec; since 2.64, you |