diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2017-11-18 16:07:44 +0100 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2017-11-18 16:07:44 +0100 |
commit | 5c3f20e243929e8f37b23f2e8f48ecbcdbd4303f (patch) | |
tree | 29c65f180da4d86645141f815953b16c5cbef16e | |
parent | 1db35a9f754920ba67514ff904178fb0e5a98e22 (diff) | |
download | gobject-introspection-5c3f20e243929e8f37b23f2e8f48ecbcdbd4303f.tar.gz |
gir: Update annotations from GLib git master1.55.0
-rw-r--r-- | gir/gio-2.0.c | 81 | ||||
-rw-r--r-- | gir/glib-2.0.c | 54 |
2 files changed, 121 insertions, 14 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 24bbb321..fa8c679d 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -16503,7 +16503,8 @@ /** * g_dbus_action_group_get: * @connection: A #GDBusConnection - * @bus_name: the bus name which exports the action group + * @bus_name: (nullable): the bus name which exports the action + * group or %NULL if @connection is not a message bus connection * @object_path: the object path at which the action group is exported * * Obtains a #GDBusActionGroup for the action group which is exported at @@ -18598,7 +18599,8 @@ /** * g_dbus_menu_model_get: * @connection: a #GDBusConnection - * @bus_name: the bus name which exports the menu model + * @bus_name: (nullable): the bus name which exports the menu model + * or %NULL if @connection is not a message bus connection * @object_path: the object path at which the menu model is exported * * Obtains a #GDBusMenuModel for the menu model which is exported @@ -24375,6 +24377,77 @@ /** + * g_file_load_bytes: + * @file: a #GFile + * @cancellable: (nullable): a #GCancellable or %NULL + * @etag_out: (out) (nullable) (optional): a location to place the current + * entity tag for the file, or %NULL if the entity tag is not needed + * @error: a location for a #GError or %NULL + * + * Loads the contents of @file and returns it as #GBytes. + * + * If @file is a resource:// based URI, the resulting bytes will reference the + * embedded resource instead of a copy. Otherwise, this is equivalent to calling + * g_file_load_contents() and g_bytes_new_take(). + * + * For resources, @etag_out will be set to %NULL. + * + * The data contained in the resulting #GBytes is always zero-terminated, but + * this is not included in the #GBytes length. The resulting #GBytes should be + * freed with g_bytes_unref() when no longer in use. + * + * Returns: (transfer full): a #GBytes or %NULL and @error is set + * Since: 2.56 + */ + + +/** + * g_file_load_bytes_async: + * @file: a #GFile + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied + * @user_data: (closure): the data to pass to callback function + * + * Asynchronously loads the contents of @file as #GBytes. + * + * If @file is a resource:// based URI, the resulting bytes will reference the + * embedded resource instead of a copy. Otherwise, this is equivalent to calling + * g_file_load_contents_async() and g_bytes_new_take(). + * + * @callback should call g_file_load_bytes_finish() to get the result of this + * asynchronous operation. + * + * See g_file_load_bytes() for more information. + * + * Since: 2.56 + */ + + +/** + * g_file_load_bytes_finish: + * @file: a #GFile + * @result: a #GAsyncResult provided to the callback + * @etag_out: (out) (nullable) (optional): a location to place the current + * entity tag for the file, or %NULL if the entity tag is not needed + * @error: a location for a #GError, or %NULL + * + * Completes an asynchronous request to g_file_load_bytes_async(). + * + * For resources, @etag_out will be set to %NULL. + * + * The data contained in the resulting #GBytes is always zero-terminated, but + * this is not included in the #GBytes length. The resulting #GBytes should be + * freed with g_bytes_unref() when no longer in use. + * + * See g_file_load_bytes() for more information. + * + * Returns: (transfer full): a #GBytes or %NULL and @error is set + * Since: 2.56 + */ + + +/** * g_file_load_contents: * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore @@ -32563,6 +32636,10 @@ * If you want to use this resource in the global resource namespace you need * to register it with g_resources_register(). * + * 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 + * GLib 2.56, or in older versions fail and exit the process. + * * Returns: (transfer full): a new #GResource, or %NULL on error * Since: 2.32 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 23509cf5..1651e312 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -12972,6 +12972,10 @@ * function is NOT thread-safe. So unless @datalist can be protected * from any modifications during invocation of this function, it should * not be called. + * + * @func can make changes to @datalist, but the iteration will not + * reflect changes made during the g_datalist_foreach() call, other + * than skipping over elements that are removed. */ @@ -13230,8 +13234,12 @@ * * Calls the given function for each data element which is associated * with the given location. Note that this function is NOT thread-safe. - * So unless @datalist can be protected from any modifications during - * invocation of this function, it should not be called. + * So unless @dataset_location can be protected from any modifications + * during invocation of this function, it should not be called. + * + * @func can make changes to the dataset, but the iteration will not + * reflect changes made during the g_dataset_foreach() call, other + * than skipping over elements that are removed. */ @@ -19329,6 +19337,9 @@ * @user_data: user data to pass to the function * * Calls a function for each element of a #GList. + * + * It is safe for @func to remove the element from @list, but it must + * not modify any part of the list after that element. */ @@ -19371,6 +19382,9 @@ * Convenience method, which frees all the memory used by a #GList, * and calls @free_func on every element's data. * + * @free_func must not modify the list (eg, by removing the freed + * element from it). + * * Since: 2.28 */ @@ -22245,8 +22259,9 @@ * @func: the function to call for each visited node * @data: user data to pass to the function * - * Calls a function for each of the children of a #GNode. - * Note that it doesn't descend beneath the child nodes. + * Calls a function for each of the children of a #GNode. Note that it + * doesn't descend beneath the child nodes. @func must not do anything + * that would modify the structure of the tree. */ @@ -22516,6 +22531,7 @@ * Traverses a tree starting at the given root #GNode. * It calls the given function for each node visited. * The traversal can be halted at any point by returning %TRUE from @func. + * @func must not do anything that would modify the structure of the tree. */ @@ -23734,7 +23750,8 @@ * @func: the function to call for each array element * @user_data: user data to pass to the function * - * Calls a function for each element of a #GPtrArray. + * Calls a function for each element of a #GPtrArray. @func must not + * add elements to or remove elements from the array. * * Since: 2.4 */ @@ -24164,6 +24181,9 @@ * Calls @func for each element in the queue passing @user_data to the * function. * + * It is safe for @func to remove the element from @queue, but it must + * not modify any part of the queue after that element. + * * Since: 2.4 */ @@ -24189,6 +24209,9 @@ * Convenience method, which frees all the memory used by a #GQueue, * and calls the specified destroy function on every element's data. * + * @free_func should not modify the queue (eg, by removing the freed + * element from it). + * * Since: 2.32 */ @@ -26113,7 +26136,7 @@ * @user_data: user data passed to @func * * Calls @func for each item in the sequence passing @user_data - * to the function. + * to the function. @func must not modify the sequence itself. * * Since: 2.14 */ @@ -26127,7 +26150,8 @@ * @user_data: user data passed to @func * * Calls @func for each item in the range (@begin, @end) passing - * @user_data to the function. + * @user_data to the function. @func must not modify the sequence + * itself. * * Since: 2.14 */ @@ -27297,6 +27321,9 @@ * @user_data: user data to pass to the function * * Calls a function for each element of a #GSList. + * + * It is safe for @func to remove the element from @list, but it must + * not modify any part of the list after that element. */ @@ -27339,6 +27366,9 @@ * Convenience method, which frees all the memory used by a #GSList, and * calls the specified destroy function on every element's data. * + * @free_func must not modify the list (eg, by removing the freed + * element from it). + * * Since: 2.28 */ @@ -28804,11 +28834,11 @@ * call g_str_tokenize_and_fold() on the search term and * perform lookups into that index. * - * As some examples, searching for "fred" would match the potential hit - * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match - * "Frédéric" but not "Frederic" (due to the one-directional nature of - * accent matching). Searching "fo" would match "Foo" and "Bar Foo - * Baz", but not "SFO" (because no word as "fo" as a prefix). + * As some examples, searching for ‘fred’ would match the potential hit + * ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match + * ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of + * accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo + * Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). * * Returns: %TRUE if @potential_hit is a hit * Since: 2.40 |