summaryrefslogtreecommitdiff
path: root/gir/glib-2.0.c
diff options
context:
space:
mode:
authorRico Tzschichholz <ricotz@ubuntu.com>2017-02-13 09:35:21 +0100
committerRico Tzschichholz <ricotz@ubuntu.com>2017-02-13 09:35:21 +0100
commit149ba912b6e19fc9b3613b58e4dc5d297f77e28a (patch)
tree5e45822f7dde9fff2a2de2b277a8d914ced9da95 /gir/glib-2.0.c
parent132f58239a2de7f960ca0a7f5c70242e6ac6c0c6 (diff)
downloadgobject-introspection-149ba912b6e19fc9b3613b58e4dc5d297f77e28a.tar.gz
gir: Update annotations from GLib git master
Diffstat (limited to 'gir/glib-2.0.c')
-rw-r--r--gir/glib-2.0.c134
1 files changed, 117 insertions, 17 deletions
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
@@ -8347,6 +8347,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
* @Short_description: variables and functions to check the GLib version
@@ -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
@@ -33559,6 +33601,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
* @format_string: a #GVariant varargs format string
@@ -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:
+ * |[<!-- language="C" -->
+ * 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
*/