From 80799e2453f4f6213892f191a785f298be1ee715 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 17 Feb 2020 19:22:11 +0100 Subject: Update glib annotations --- gir/gio-2.0.c | 81 ++++++++++++++-------------------------------------------- gir/glib-2.0.c | 38 ++++++++++++++++++++++++++- 2 files changed, 56 insertions(+), 63 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 197a7616..f9df1751 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -3627,19 +3627,6 @@ */ -/** - * GTlsCertificate:pkcs11-uri: (nullable) - * - * A URI referencing the PKCS \#11 objects containing an X.509 certificate - * and optionally a private key. - * - * If %NULL the certificate is either not backed by PKCS \#11 or the - * #GTlsBackend does not support PKCS \#11. - * - * Since: 2.64 - */ - - /** * GTlsCertificate:private-key: * @@ -3675,15 +3662,6 @@ */ -/** - * GTlsCertificate:private-key-pkcs11-uri: (nullable) - * - * A URI referencing a PKCS \#11 object containing a private key. - * - * Since: 2.64 - */ - - /** * GTlsClientConnection: * @@ -16389,6 +16367,24 @@ * signal is unsubscribed from, and may be called after @connection * has been destroyed.) * + * As @callback is potentially invoked in a different thread from where it’s + * emitted, it’s possible for this to happen after + * g_dbus_connection_signal_unsubscribe() has been called in another thread. + * Due to this, @user_data should have a strong reference which is freed with + * @user_data_free_func, rather than pointing to data whose lifecycle is tied + * to the signal subscription. For example, if a #GObject is used to store the + * subscription ID from g_dbus_connection_signal_subscribe(), a strong reference + * to that #GObject must be passed to @user_data, and g_object_unref() passed to + * @user_data_free_func. You are responsible for breaking the resulting + * reference count cycle by explicitly unsubscribing from the signal when + * dropping the last external reference to the #GObject. Alternatively, a weak + * reference may be used. + * + * It is guaranteed that if you unsubscribe from a signal using + * g_dbus_connection_signal_unsubscribe() from the same thread which made the + * corresponding g_dbus_connection_signal_subscribe() call, @callback will not + * be invoked after g_dbus_connection_signal_unsubscribe() returns. + * * The returned subscription identifier is an opaque value which is guaranteed * to never be zero. * @@ -23714,10 +23710,6 @@ * If the flag #G_FILE_COPY_OVERWRITE is specified an already * existing @destination file is overwritten. * - * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks - * will be copied as symlinks, otherwise the target of the - * @source symlink will be copied. - * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. @@ -29319,7 +29311,7 @@ /** * g_network_monitor_base_add_network: * @monitor: the #GNetworkMonitorBase - * @network: a #GInetAddressMask + * @network: (transfer none): a #GInetAddressMask * * Adds @network to @monitor's list of available networks. * @@ -39092,41 +39084,6 @@ */ -/** - * g_tls_certificate_new_from_pkcs11_uris: - * @pkcs11_uri: A PKCS \#11 URI - * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a #GTlsCertificate from a PKCS \#11 URI. - * - * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` - * - * Where the token’s layout is: - * - * ``` - * Object 0: - * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private - * Type: Private key (RSA-2048) - * ID: 01 - * - * Object 1: - * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert - * Type: X.509 Certificate (RSA-2048) - * ID: 01 - * ``` - * - * In this case the certificate and private key would both be detected and used as expected. - * @pkcs_uri may also just reference an X.509 certificate object and then optionally - * @private_key_pkcs11_uri allows using a private key exposed under a different URI. - * - * Note that the private key is not accessed until usage and may fail or require a PIN later. - * - * Returns: (transfer full): the new certificate, or %NULL on error - * Since: 2.64 - */ - - /** * g_tls_certificate_verify: * @cert: a #GTlsCertificate diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 4830ee57..cb671c7a 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -17264,12 +17264,16 @@ /** * g_hash_table_add: * @hash_table: a #GHashTable - * @key: a key to insert + * @key: (transfer full): a key to insert * * This is a convenience function for using a #GHashTable as a set. It * is equivalent to calling g_hash_table_replace() with @key as both the * key and the value. * + * In particular, this means that if @key already exists in the hash table, then + * the old copy of @key in the hash table is freed and @key replaces it in the + * table. + * * When a hash table only ever contains keys that have themselves as the * corresponding value it is able to be stored more efficiently. See * the discussion in the section description. @@ -20323,6 +20327,13 @@ * * If list elements contain dynamically-allocated memory, you should * either use g_list_free_full() or free them manually first. + * + * It can be combined with g_steal_pointer() to ensure the list head pointer + * is not left dangling: + * |[ + * GList *list_of_borrowed_things = …; /* (transfer container) */ + * g_list_free (g_steal_pointer (&list_of_borrowed_things)); + * ]| */ @@ -20356,6 +20367,15 @@ * @free_func must not modify the list (eg, by removing the freed * element from it). * + * It can be combined with g_steal_pointer() to ensure the list head pointer + * is not left dangling ­— this also has the nice property that the head pointer + * is cleared before any of the list elements are freed, to prevent double frees + * from @free_func: + * |[ + * GList *list_of_owned_things = …; /* (transfer full) (element-type GObject) */ + * g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); + * ]| + * * Since: 2.28 */ @@ -28900,6 +28920,13 @@ * If list elements contain dynamically-allocated memory, * you should either use g_slist_free_full() or free them manually * first. + * + * It can be combined with g_steal_pointer() to ensure the list head pointer + * is not left dangling: + * |[ + * GSList *list_of_borrowed_things = …; /* (transfer container) */ + * g_slist_free (g_steal_pointer (&list_of_borrowed_things)); + * ]| */ @@ -28932,6 +28959,15 @@ * @free_func must not modify the list (eg, by removing the freed * element from it). * + * It can be combined with g_steal_pointer() to ensure the list head pointer + * is not left dangling ­— this also has the nice property that the head pointer + * is cleared before any of the list elements are freed, to prevent double frees + * from @free_func: + * |[ + * GSList *list_of_owned_things = …; /* (transfer full) (element-type GObject) */ + * g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); + * ]| + * * Since: 2.28 */ -- cgit v1.2.1