From 65be48bdefe8c48a92cc54a2c525f4acccc9b5e8 Mon Sep 17 00:00:00 2001 From: Christoph Reiter Date: Mon, 31 Dec 2018 13:28:00 +0100 Subject: Update glib annotations --- gir/gio-2.0.c | 267 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- gir/glib-2.0.c | 125 ++++++++++++++++++------- gir/gobject-2.0.c | 8 +- 3 files changed, 356 insertions(+), 44 deletions(-) (limited to 'gir') diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 87a9db7d..f4fa552d 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -1645,6 +1645,17 @@ */ +/** + * GDtlsConnection:advertised-protocols: + * + * The list of application-layer protocols that the connection + * advertises that it is willing to speak. See + * g_dtls_connection_set_advertised_protocols(). + * + * Since: 2.60 + */ + + /** * GDtlsConnection:base-socket: * @@ -1687,6 +1698,16 @@ */ +/** + * GDtlsConnection:negotiated-protocol: + * + * The application-layer protocol negotiated during the TLS + * handshake. See g_dtls_connection_get_negotiated_protocol(). + * + * Since: 2.60 + */ + + /** * GDtlsConnection:peer-certificate: * @@ -3692,6 +3713,17 @@ */ +/** + * GTlsConnection:advertised-protocols: + * + * The list of application-layer protocols that the connection + * advertises that it is willing to speak. See + * g_tls_connection_set_advertised_protocols(). + * + * Since: 2.60 + */ + + /** * GTlsConnection:base-io-stream: * @@ -3737,6 +3769,16 @@ */ +/** + * GTlsConnection:negotiated-protocol: + * + * The application-layer protocol negotiated during the TLS + * handshake. See g_tls_connection_get_negotiated_protocol(). + * + * Since: 2.60 + */ + + /** * GTlsConnection:peer-certificate: * @@ -5162,13 +5204,13 @@ * * A content type is a platform specific string that defines the type * of a file. On UNIX it is a - * [mime type](http://www.wikipedia.org/wiki/Internet_media_type) - * like "text/plain" or "image/png". - * On Win32 it is an extension string like ".doc", ".txt" or a perceived - * string like "audio". Such strings can be looked up in the registry at - * HKEY_CLASSES_ROOT. - * On OSX it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) - * such as "com.apple.application". + * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type) + * like `text/plain` or `image/png`. + * On Win32 it is an extension string like `.doc`, `.txt` or a perceived + * string like `audio`. Such strings can be looked up in the registry at + * `HKEY_CLASSES_ROOT`. + * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) + * such as `com.apple.application`. */ @@ -7259,6 +7301,23 @@ */ +/** + * SECTION:gproxyaddressenumerator + * @short_description: Proxy wrapper enumerator for socket addresses + * @include: gio/gio.h + * + * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which + * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator + * and wraps them in #GProxyAddress instances, using the given + * #GProxyAddressEnumerator:proxy-resolver. + * + * This enumerator will be returned (for example, by + * g_socket_connectable_enumerate()) as appropriate when a proxy is configured; + * there should be no need to manually wrap a #GSocketAddressEnumerator instance + * with one. + */ + + /** * SECTION:gproxyresolver * @short_description: Asynchronous and cancellable network proxy resolver @@ -8235,6 +8294,28 @@ */ +/** + * SECTION:gsocketaddressenumerator + * @short_description: Enumerator for socket addresses + * @include: gio/gio.h + * + * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress + * instances. It is returned by enumeration functions such as + * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator + * to list all the #GSocketAddresses which could be used to connect to that + * #GSocketConnectable. + * + * Enumeration is typically a blocking operation, so the asynchronous methods + * g_socket_address_enumerator_next_async() and + * g_socket_address_enumerator_next_finish() should be used where possible. + * + * Each #GSocketAddressEnumerator can only be enumerated once. Once + * g_socket_address_enumerator_next() has returned %NULL (and no error), further + * enumeration with that #GSocketAddressEnumerator is not possible, and it can + * be unreffed. + */ + + /** * SECTION:gsocketclient * @short_description: Helper for connecting to a network service @@ -13487,6 +13568,19 @@ */ +/** + * g_content_type_get_mime_dirs: + * + * Get the list of directories which MIME data is loaded from. See + * g_content_type_set_mime_dirs() for details. + * + * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of + * directories to load MIME data from, including any `mime/` subdirectory, + * and with the first directory to try listed first + * Since: 2.60 + */ + + /** * g_content_type_get_mime_type: * @type: a content type string @@ -13590,12 +13684,46 @@ */ +/** + * g_content_type_set_mime_dirs: + * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of + * directories to load MIME data from, including any `mime/` subdirectory, + * and with the first directory to try listed first + * + * Set the list of directories used by GIO to load the MIME database. + * If @dirs is %NULL, the directories used are the default: + * + * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` + * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` + * + * This function is intended to be used when writing tests that depend on + * information stored in the MIME database, in order to control the data. + * + * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they + * depend on the system’s MIME database, you should call this function + * with @dirs set to %NULL before calling g_test_init(), for instance: + * + * |[ + * // Load MIME data from the system + * g_content_type_set_mime_dirs (NULL); + * // Isolate the environment + * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); + * + * … + * + * return g_test_run (); + * ]| + * + * Since: 2.60 + */ + + /** * g_content_types_get_registered: * * Gets a list of strings containing all the registered content types * known to the system. The list and its data should be freed using - * g_list_free_full (list, g_free). + * `g_list_free_full (list, g_free)`. * * Returns: (element-type utf8) (transfer full): list of the registered * content types @@ -15413,6 +15541,17 @@ */ +/** + * g_dbus_connection_get_flags: + * @connection: a #GDBusConnection + * + * Gets the flags used to construct this connection + * + * Returns: zero or more flags from the #GDBusConnectionFlags enumeration + * Since: 2.60 + */ + + /** * g_dbus_connection_get_guid: * @connection: a #GDBusConnection @@ -20039,6 +20178,23 @@ */ +/** + * g_dtls_connection_get_negotiated_protocol: + * @conn: a #GDtlsConnection + * + * Gets the name of the application-layer protocol negotiated during + * the handshake. + * + * If the peer did not use the ALPN extension, or did not advertise a + * protocol that matched one of @conn's protocols, or the TLS backend + * does not support ALPN, then this will be %NULL. See + * g_dtls_connection_set_advertised_protocols(). + * + * Returns: (nullable): the negotiated protocol, or %NULL + * Since: 2.60 + */ + + /** * g_dtls_connection_get_peer_certificate: * @conn: a #GDtlsConnection @@ -20161,6 +20317,27 @@ */ +/** + * g_dtls_connection_set_advertised_protocols: + * @conn: a #GDtlsConnection + * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated + * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL + * + * Sets the list of application-layer protocols to advertise that the + * caller is willing to speak on this connection. The + * Application-Layer Protocol Negotiation (ALPN) extension will be + * used to negotiate a compatible protocol with the peer; use + * g_dtls_connection_get_negotiated_protocol() to find the negotiated + * protocol after the handshake. Specifying %NULL for the the value + * of @protocols will disable ALPN negotiation. + * + * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) + * for a list of registered protocol IDs. + * + * Since: 2.60 + */ + + /** * g_dtls_connection_set_certificate: * @conn: a #GDtlsConnection @@ -36434,6 +36611,9 @@ * * Like g_subprocess_communicate(), but validates the output of the * process as UTF-8, and returns it as a regular NUL terminated string. + * + * On error, @stdout_buf and @stderr_buf will be set to undefined values and + * should not be used. */ @@ -37149,6 +37329,9 @@ * #GMainContext with @task's [priority][io-priority], and sets @source's * callback to @callback, with @task as the callback's `user_data`. * + * It will set the @source’s name to the task’s name (as set with + * g_task_set_name()), if one has been set. + * * This takes a reference on @task until @source is destroyed. * * Since: 2.36 @@ -37207,6 +37390,17 @@ */ +/** + * g_task_get_name: + * @task: a #GTask + * + * Gets @task’s name. See g_task_set_name(). + * + * Returns: (nullable) (transfer none): @task’s name, or %NULL + * Since: 2.60 + */ + + /** * g_task_get_priority: * @task: a #GTask @@ -37606,6 +37800,25 @@ */ +/** + * g_task_set_name: + * @task: a #GTask + * @name: (nullable): a human readable name for the task, or %NULL to unset it + * + * Sets @task’s name, used in debugging and profiling. The name defaults to + * %NULL. + * + * The task name should describe in a human readable way what the task does. + * For example, ‘Open file’ or ‘Connect to network host’. It is used to set the + * name of the #GSource used for idle completion of the task. + * + * This function may only be called before the @task is first used in a thread + * other than the one it was constructed in. + * + * Since: 2.60 + */ + + /** * g_task_set_priority: * @task: the #GTask @@ -38452,6 +38665,23 @@ */ +/** + * g_tls_connection_get_negotiated_protocol: + * @conn: a #GTlsConnection + * + * Gets the name of the application-layer protocol negotiated during + * the handshake. + * + * If the peer did not use the ALPN extension, or did not advertise a + * protocol that matched one of @conn's protocols, or the TLS backend + * does not support ALPN, then this will be %NULL. See + * g_tls_connection_set_advertised_protocols(). + * + * Returns: (nullable): the negotiated protocol, or %NULL + * Since: 2.60 + */ + + /** * g_tls_connection_get_peer_certificate: * @conn: a #GTlsConnection @@ -38590,6 +38820,27 @@ */ +/** + * g_tls_connection_set_advertised_protocols: + * @conn: a #GTlsConnection + * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated + * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL + * + * Sets the list of application-layer protocols to advertise that the + * caller is willing to speak on this connection. The + * Application-Layer Protocol Negotiation (ALPN) extension will be + * used to negotiate a compatible protocol with the peer; use + * g_tls_connection_get_negotiated_protocol() to find the negotiated + * protocol after the handshake. Specifying %NULL for the the value + * of @protocols will disable ALPN negotiation. + * + * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) + * for a list of registered protocol IDs. + * + * Since: 2.60 + */ + + /** * g_tls_connection_set_certificate: * @conn: a #GTlsConnection diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index c70f2746..aa46726e 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1514,6 +1514,10 @@ * simultaneous read-only access (by holding the 'reader' lock via * g_rw_lock_reader_lock()). * + * It is unspecified whether readers or writers have priority in acquiring the + * lock when a reader already holds the lock and a writer is queued to acquire + * it. + * * Here is an example for an array with access functions: * |[ * GRWLock lock; @@ -2732,6 +2736,19 @@ */ +/** + * G_ALIGNOF: + * @a: a type-name + * + * Return the minimum alignment required by the platform ABI for values of the given + * type. The address of a variable or struct member of the given type must always be + * a multiple of this alignment. For example, most platforms require int variables + * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. + * + * Since: 2.60 + */ + + /** * G_APPROX_VALUE: * @a: a numeric value @@ -7408,7 +7425,8 @@ * The "GMarkup" parser is intended to parse a simple markup format * that's a subset of XML. This is a small, efficient, easy-to-use * parser. It should not be used if you expect to interoperate with - * other applications generating full-scale XML. However, it's very + * other applications generating full-scale XML, and must not be used if you + * expect to parse untrusted input. However, it's very * useful for application data files, config files, etc. where you * know your application will be the only one writing the file. * Full-scale XML parsers should be able to parse the subset used by @@ -8497,7 +8515,8 @@ * In addition to the traditional g_assert_true(), the test framework provides * an extended set of assertions for comparisons: g_assert_cmpfloat(), * g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), - * g_assert_cmphex(), g_assert_cmpstr(), and g_assert_cmpmem(). The + * g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and + * g_assert_cmpvariant(). The * advantage of these variants over plain g_assert_true() is that the assertion * messages can be more elaborate, and include the values of the compared * entities. @@ -10068,7 +10087,7 @@ * g_assert_cmpfloat: * @n1: an floating point number * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * @n2: another floating point number * * Debugging macro to compare two floating point numbers. @@ -10104,7 +10123,7 @@ * g_assert_cmphex: * @n1: an unsigned integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * @n2: another unsigned integer * * Debugging macro to compare to unsigned integers. @@ -10120,7 +10139,7 @@ * g_assert_cmpint: * @n1: an integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * @n2: another integer * * Debugging macro to compare two integers. @@ -10162,7 +10181,7 @@ * g_assert_cmpstr: * @s1: a string (may be %NULL) * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * @s2: another string (may be %NULL) * * Debugging macro to compare two strings. If the comparison fails, @@ -10187,7 +10206,7 @@ * g_assert_cmpuint: * @n1: an unsigned integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * @n2: another unsigned integer * * Debugging macro to compare two unsigned integers. @@ -10201,6 +10220,24 @@ */ +/** + * g_assert_cmpvariant: + * @v1: pointer to a #GVariant + * @v2: pointer to another #GVariant + * + * Debugging macro to compare two #GVariants. If the comparison fails, + * an error message is logged and the application is either terminated + * or the testcase marked as failed. The variants are compared using + * g_variant_equal(). + * + * The effect of `g_assert_cmpvariant (v1, v2)` is the same as + * `g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is + * that it can produce a message that includes the actual values of @v1 and @v2. + * + * Since: 2.60 + */ + + /** * g_assert_error: * @err: a #GError, possibly %NULL @@ -10218,7 +10255,7 @@ * * This can only be used to test for a specific error. If you want to * test that @err is set, but don't care what it's set to, just use - * `g_assert (err != NULL)` + * `g_assert_nonnull (err)`. * * Since: 2.20 */ @@ -11131,6 +11168,9 @@ * The data will be freed when its reference count drops to * zero. * + * The allocated data is guaranteed to be suitably aligned for any + * built-in type. + * * Returns: (transfer full) (not nullable): a pointer to the allocated memory * Since: 2.58 */ @@ -11148,6 +11188,9 @@ * The data will be freed when its reference count drops to * zero. * + * The allocated data is guaranteed to be suitably aligned for any + * built-in type. + * * Returns: (transfer full) (not nullable): a pointer to the allocated memory * Since: 2.58 */ @@ -25924,6 +25967,9 @@ * The data will be freed when its reference count drops to * zero. * + * The allocated data is guaranteed to be suitably aligned for any + * built-in type. + * * Returns: (transfer full) (not nullable): a pointer to the allocated memory * Since: 2.58 */ @@ -25941,6 +25987,9 @@ * The data will be freed when its reference count drops to * zero. * + * The allocated data is guaranteed to be suitably aligned for any + * built-in type. + * * Returns: (transfer full) (not nullable): a pointer to the allocated memory * Since: 2.58 */ @@ -26946,7 +26995,7 @@ * that the latest on-disk version is used. Call this only * if you just changed the data on disk yourself. * - * Due to threadsafety issues this may cause leaking of strings + * Due to thread safety issues this may cause leaking of strings * that were previously returned from g_get_user_special_dir() * that can't be freed. We ensure to only leak the data for * the directories that actually changed value though. @@ -31556,35 +31605,31 @@ /** - * g_strv_length: - * @str_array: a %NULL-terminated array of strings + * g_strv_equal: + * @strv1: a %NULL-terminated array of strings + * @strv2: another %NULL-terminated array of strings * - * Returns the length of the given %NULL-terminated - * string array @str_array. @str_array must not be %NULL. + * Checks if @strv1 and @strv2 contain exactly the same elements in exactly the + * same order. Elements are compared using g_str_equal(). To match independently + * of order, sort the arrays first (using g_qsort_with_data() or similar). * - * Returns: length of @str_array. - * Since: 2.6 + * Two empty arrays are considered equal. Neither @strv1 not @strv2 may be + * %NULL. + * + * Returns: %TRUE if @strv1 and @strv2 are equal + * Since: 2.60 */ /** - * g_test_add: - * @testpath: The test path for a new test case. - * @Fixture: The type of a fixture data structure. - * @tdata: Data argument for the test functions. - * @fsetup: The function to set up the fixture data. - * @ftest: The actual test function. - * @fteardown: The function to tear down the fixture data. - * - * Hook up a new test case at @testpath, similar to g_test_add_func(). - * A fixture data structure with setup and teardown functions may be provided, - * similar to g_test_create_case(). + * g_strv_length: + * @str_array: a %NULL-terminated array of strings * - * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and - * fteardown() callbacks can expect a @Fixture pointer as their first argument - * in a type safe manner. They otherwise have type #GTestFixtureFunc. + * Returns the length of the given %NULL-terminated + * string array @str_array. @str_array must not be %NULL. * - * Since: 2.16 + * Returns: length of @str_array. + * Since: 2.6 */ @@ -31604,6 +31649,10 @@ * the test will be skipped by default, and only run if explicitly * required via the `-p` command-line option or g_test_trap_subprocess(). * + * No component of @testpath may start with a dot (`.`) if the + * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to + * do so even if it isn’t. + * * Since: 2.16 */ @@ -31636,6 +31685,10 @@ * the test will be skipped by default, and only run if explicitly * required via the `-p` command-line option or g_test_trap_subprocess(). * + * No component of @testpath may start with a dot (`.`) if the + * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to + * do so even if it isn’t. + * * Since: 2.16 */ @@ -31923,9 +31976,7 @@ * Changed if any arguments were handled. * @argv: Address of the @argv parameter of main(). * Any parameters understood by g_test_init() stripped before return. - * @...: %NULL-terminated list of special options. Currently the only - * defined option is `"no_g_set_prgname"`, which - * will cause g_test_init() to not call g_set_prgname(). + * @...: %NULL-terminated list of special options, documented below. * * Initialize the GLib testing framework, e.g. by seeding the * test random number generator, the name for g_get_prgname() @@ -31959,6 +32010,14 @@ * * - `--debug-log`: Debug test logging output. * + * Options which can be passed to @... are: + * + * - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname(). + * - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each + * unit test and uses g_set_user_dirs() to set XDG directories to point into + * that temporary directory for the duration of the unit test. See the + * documentation for %G_TEST_OPTION_ISOLATE_DIRS. + * * Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, * g_test_init() will print an error and exit. This is to prevent no-op tests * from being executed, as g_assert() is commonly (erroneously) used in unit diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 079a6248..67539ec5 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -2380,9 +2380,11 @@ * of bidirectional bindings, otherwise it will be ignored * * The binding will automatically be removed when either the @source or the - * @target instances are finalized. To remove the binding without affecting the - * @source and the @target you can just call g_object_unref() on the returned - * #GBinding instance. + * @target instances are finalized. This will release the reference that is + * being held on the #GBinding instance; if you want to hold on to the + * #GBinding instance, you will need to hold a reference to it. + * + * To remove the binding, call g_binding_unbind(). * * A #GObject can have multiple bindings. * -- cgit v1.2.1