From 149ba912b6e19fc9b3613b58e4dc5d297f77e28a Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 13 Feb 2017 09:35:21 +0100 Subject: gir: Update annotations from GLib git master --- gir/gio-2.0.c | 60 +++++++++++++++++++------- gir/glib-2.0.c | 134 +++++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 162 insertions(+), 32 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 841cad4b..10a2f672 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -5653,8 +5653,9 @@ * @include: gio/gio.h * * Routines for working with D-Bus addresses. A D-Bus address is a string - * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses). + * like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses + * is explained in detail in the + * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). */ @@ -16326,6 +16327,9 @@ * bus instance specified by @bus_type. This may involve using various * platform specific mechanisms. * + * The returned address will be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * * Returns: a valid D-Bus address string for @bus_type or %NULL if * @error is set * Since: 2.26 @@ -16341,7 +16345,8 @@ * * Asynchronously connects to an endpoint specified by @address and * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. + * of the D-Bus authentication conversation. @address must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * When the operation is finished, @callback will be invoked. You can * then call g_dbus_address_get_stream_finish() to get the result of @@ -16376,7 +16381,8 @@ * * Synchronously connects to an endpoint specified by @address and * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. + * of the D-Bus authentication conversation. @address must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * This is a synchronous failable function. See * g_dbus_address_get_stream() for the asynchronous version. @@ -17122,7 +17128,8 @@ * * Asynchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the D-Bus address format. + * which must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * This constructor can only be used to initiate client-side * connections - use g_dbus_connection_new() if you need to act as the @@ -17169,7 +17176,8 @@ * * Synchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the D-Bus address format. + * which must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * This constructor can only be used to initiate client-side * connections - use g_dbus_connection_new_sync() if you need to act @@ -18270,7 +18278,8 @@ * g_dbus_is_address: * @string: A string. * - * Checks if @string is a D-Bus address. + * Checks if @string is a + * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * This doesn't check if @string is actually supported by #GDBusServer * or #GDBusConnection - use g_dbus_is_supported_address() to do more @@ -18333,9 +18342,10 @@ * @string: A string. * @error: Return location for error or %NULL. * - * Like g_dbus_is_address() but also checks if the library suppors the + * Like g_dbus_is_address() but also checks if the library supports the * transports in @string and that key/value pairs for each transport - * are valid. + * are valid. See the specification of the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * * Returns: %TRUE if @string is a valid D-Bus address that is * supported by this library, %FALSE if @error is set. @@ -19284,7 +19294,26 @@ * Finishes handling a D-Bus method call by returning @parameters. * If the @parameters GVariant is floating, it is consumed. * - * It is an error if @parameters is not of the right format. + * It is an error if @parameters is not of the right format: it must be a tuple + * containing the out-parameters of the D-Bus method. Even if the method has a + * single out-parameter, it must be contained in a tuple. If the method has no + * out-parameters, @parameters may be %NULL or an empty tuple. + * + * |[ + * GDBusMethodInvocation *invocation = some_invocation; + * g_autofree gchar *result_string = NULL; + * g_autoptr (GError) error = NULL; + * + * result_string = calculate_result (&error); + * + * if (error != NULL) + * g_dbus_method_invocation_return_gerror (invocation, error); + * else + * g_dbus_method_invocation_return_value (invocation, + * g_variant_new ("(s)", result_string)); + * + * /* Do not free @invocation here; returning a value does that */ + * ]| * * This method will take ownership of @invocation. See * #GDBusInterfaceVTable for more information about the ownership of @@ -20442,8 +20471,9 @@ * g_dbus_server_get_client_address: * @server: A #GDBusServer. * - * Gets a D-Bus address string that can be used by clients to connect - * to @server. + * Gets a + * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) + * string that can be used by clients to connect to @server. * * Returns: A D-Bus address string. Do not free, the string is owned * by @server. @@ -30540,7 +30570,7 @@ * * For behaviour details see g_output_stream_close(). * - * The asyncronous methods have a default fallback that uses threads + * The asynchronous methods have a default fallback that uses threads * to implement asynchronicity, so they are optional for inheriting * classes. However, if you override one you must override all. */ @@ -30614,7 +30644,7 @@ * g_output_stream_has_pending: * @stream: a #GOutputStream. * - * Checks if an ouput stream has pending actions. + * Checks if an output stream has pending actions. * * Returns: %TRUE if @stream has pending actions. */ @@ -30923,7 +30953,7 @@ * value) will be executed before an outstanding request with lower * priority. Default priority is %G_PRIORITY_DEFAULT. * - * The asyncronous methods have a default fallback that uses threads + * The asynchronous methods have a default fallback that uses threads * to implement asynchronicity, so they are optional for inheriting * classes. However, if you override one you must override all. * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 97296056..9a35f49d 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -8346,6 +8346,29 @@ */ +/** + * SECTION:uuid + * @title: GUuid + * @short_description: a universally unique identifier + * + * A UUID, or Universally unique identifier, is intended to uniquely + * identify information in a distributed environment. For the + * definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). + * + * The creation of UUIDs does not require a centralized authority. + * + * UUIDs are of relatively small size (128 bits, or 16 bytes). The + * common string representation (ex: + * 1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. + * + * The UUID specification defines 5 versions, and calling + * g_uuid_string_random() will generate a unique (or rather random) + * UUID of the most common version, version 4. + * + * Since: 2.52 + */ + + /** * SECTION:version * @Title: Version Information @@ -18040,7 +18063,8 @@ * * If @key cannot be found then 0 is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated - * with @key cannot be interpreted as an integer then 0 is returned + * with @key cannot be interpreted as an integer, or is out of range + * for a #gint, then 0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: the value associated with the key as an integer, or @@ -18062,7 +18086,8 @@ * * If @key cannot be found then %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as integers then %NULL is returned + * with @key cannot be interpreted as integers, or are out of range for + * #gint, then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * * Returns: (array length=length) (element-type gint) (transfer container): @@ -18334,9 +18359,13 @@ * * This function looks for a key file named @file in the paths * specified in @search_dirs, loads the file into @key_file and - * returns the file's full path in @full_path. If the file could not - * be loaded then an %error is set to either a #GFileError or - * #GKeyFileError. + * returns the file's full path in @full_path. + * + * If the file could not be found in any of the @search_dirs, + * %G_KEY_FILE_ERROR_NOT_FOUND is returned. If + * the file is found but the OS returns an error when opening or reading the + * file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a + * %G_KEY_FILE_ERROR is returned. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.14 @@ -18351,8 +18380,13 @@ * @error: return location for a #GError, or %NULL * * Loads a key file into an empty #GKeyFile structure. - * If the file could not be loaded then @error is set to - * either a #GFileError or #GKeyFileError. + * + * If the OS returns an error when opening or reading the file, a + * %G_FILE_ERROR is returned. If there is a problem parsing the file, a + * %G_KEY_FILE_ERROR is returned. + * + * This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the + * @file is not found, %G_FILE_ERROR_NOENT is returned. * * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.6 @@ -21553,7 +21587,7 @@ /** - * g_mkdtemp: + * g_mkdtemp: (skip) * @tmpl: (type filename): template directory name * * Creates a temporary directory. See the mkdtemp() documentation @@ -21562,12 +21596,16 @@ * The parameter is a string that should follow the rules for * mkdtemp() templates, i.e. contain the string "XXXXXX". * g_mkdtemp() is slightly more flexible than mkdtemp() in that the - * sequence does not have to occur at the very end of the template - * and you can pass a @mode and additional @flags. The X string will - * be modified to form the name of a directory that didn't exist. + * sequence does not have to occur at the very end of the template. + * The X string will be modified to form the name of a directory that + * didn't exist. * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * + * If you are going to be creating a temporary directory inside the + * directory returned by g_get_tmp_dir(), you might want to use + * g_dir_make_tmp() instead. + * * Returns: (nullable) (type filename): A pointer to @tmpl, which has been * modified to hold the directory name. In case of errors, %NULL is * returned and %errno will be set. @@ -21576,7 +21614,7 @@ /** - * g_mkdtemp_full: + * g_mkdtemp_full: (skip) * @tmpl: (type filename): template directory name * @mode: permissions to create the temporary directory with * @@ -21585,13 +21623,17 @@ * * The parameter is a string that should follow the rules for * mkdtemp() templates, i.e. contain the string "XXXXXX". - * g_mkdtemp() is slightly more flexible than mkdtemp() in that the + * g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the * sequence does not have to occur at the very end of the template * and you can pass a @mode. The X string will be modified to form * the name of a directory that didn't exist. The string should be * in the GLib file name encoding. Most importantly, on Windows it * should be in UTF-8. * + * If you are going to be creating a temporary directory inside the + * directory returned by g_get_tmp_dir(), you might want to use + * g_dir_make_tmp() instead. + * * Returns: (nullable) (type filename): A pointer to @tmpl, which has been * modified to hold the directory name. In case of errors, %NULL is * returned, and %errno will be set. @@ -21600,7 +21642,7 @@ /** - * g_mkstemp: + * g_mkstemp: (skip) * @tmpl: (type filename): template filename * * Opens a temporary file. See the mkstemp() documentation @@ -21623,7 +21665,7 @@ /** - * g_mkstemp_full: + * g_mkstemp_full: (skip) * @tmpl: (type filename): template filename * @flags: flags to pass to an open() call in addition to O_EXCL * and O_CREAT, which are passed automatically @@ -33558,6 +33600,34 @@ */ +/** + * g_uuid_string_is_valid: + * @str: a string representing a UUID + * + * Parses the string @str and verify if it is a UUID. + * + * The function accepts the following syntax: + * + * - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`) + * + * Note that hyphens are required within the UUID string itself, + * as per the aforementioned RFC. + * + * Returns: %TRUE if @str is a valid UUID, %FALSE otherwise. + * Since: 2.52 + */ + + +/** + * g_uuid_string_random: + * + * Generates a random UUID (RFC 4122 version 4) as a string. + * + * Returns: (transfer full): A string that should be freed with g_free(). + * Since: 2.52 + */ + + /** * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder @@ -33782,15 +33852,45 @@ /** * g_variant_builder_open: * @builder: a #GVariantBuilder - * @type: a #GVariantType + * @type: the #GVariantType of the container * * Opens a subcontainer inside the given @builder. When done adding - * items to the subcontainer, g_variant_builder_close() must be called. + * items to the subcontainer, g_variant_builder_close() must be called. @type + * is the type of the container: so to build a tuple of several values, @type + * must include the tuple itself. * * It is an error to call this function in any way that would cause an * inconsistent value to be constructed (ie: adding too many values or * a value of an incorrect type). * + * Example of building a nested variant: + * |[ + * GVariantBuilder builder; + * guint32 some_number = get_number (); + * g_autoptr (GHashTable) some_dict = get_dict (); + * GHashTableIter iter; + * const gchar *key; + * const GVariant *value; + * g_autoptr (GVariant) output = NULL; + * + * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); + * g_variant_builder_add (&builder, "u", some_number); + * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); + * + * g_hash_table_iter_init (&iter, some_dict); + * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) + * { + * g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); + * g_variant_builder_add (&builder, "s", key); + * g_variant_builder_add (&builder, "v", value); + * g_variant_builder_close (&builder); + * } + * + * g_variant_builder_close (&builder); + * + * output = g_variant_builder_end (&builder); + * ]| + * * Since: 2.24 */ -- cgit v1.2.1