/**
- * 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:
*
* The DER (binary) encoded representation of the certificate's
/**
- * GTlsCertificate:private-key-pkcs11-uri: (nullable)
- *
- * A URI referencing a PKCS \#11 object containing a private key.
- *
- * Since: 2.64
- */
-
-
-/**
* GTlsClientConnection:
*
* Abstract base class for the backend-specific client connection
* initialization for all of these in a single place.
*
* Regardless of which of these entry points is used to start the
- * application, GApplication passes some "platform data from the
+ * application, GApplication passes some ‘platform data’ from the
* launching instance to the primary instance, in the form of a
* #GVariant dictionary mapping strings to variants. To use platform
* data, override the @before_emit or @after_emit virtual functions
*
* It is important to use the proper GVariant format when retrieving
* the options with g_variant_dict_lookup():
- * - for %G_OPTION_ARG_NONE, use b
- * - for %G_OPTION_ARG_STRING, use &s
- * - for %G_OPTION_ARG_INT, use i
- * - for %G_OPTION_ARG_INT64, use x
- * - for %G_OPTION_ARG_DOUBLE, use d
- * - for %G_OPTION_ARG_FILENAME, use ^ay
- * - for %G_OPTION_ARG_STRING_ARRAY, use &as
- * - for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay
+ * - for %G_OPTION_ARG_NONE, use `b`
+ * - for %G_OPTION_ARG_STRING, use `&s`
+ * - for %G_OPTION_ARG_INT, use `i`
+ * - for %G_OPTION_ARG_INT64, use `x`
+ * - for %G_OPTION_ARG_DOUBLE, use `d`
+ * - for %G_OPTION_ARG_FILENAME, use `^&ay`
+ * - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s`
+ * - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay`
*
* Since: 2.40
*/
*
* Stops owning a name.
*
+ * Note that there may still be D-Bus traffic to process (relating to owning
+ * and unowning the name) in the current thread-default #GMainContext after
+ * this function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to g_bus_own_name() is called, in
+ * order to avoid memory leaks through callbacks queued on the #GMainContext
+ * after it’s stopped being iterated.
+ *
* Since: 2.26
*/
*
* Stops watching a name.
*
+ * Note that there may still be D-Bus traffic to process (relating to watching
+ * and unwatching the name) in the current thread-default #GMainContext after
+ * this function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to g_bus_watch_name() is called, in
+ * order to avoid memory leaks through callbacks queued on the #GMainContext
+ * after it’s stopped being iterated.
+ *
* Since: 2.26
*/
* 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.
*
*
* Unsubscribes from signals.
*
+ * Note that there may still be D-Bus traffic to process (relating to this
+ * signal subscription) in the current thread-default #GMainContext after this
+ * function has returned. You should continue to iterate the #GMainContext
+ * until the #GDestroyNotify function passed to
+ * g_dbus_connection_signal_subscribe() is called, in order to avoid memory
+ * leaks through callbacks queued on the #GMainContext after it’s stopped being
+ * iterated.
+ *
* Since: 2.26
*/
* 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.
/**
* 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.
*
/**
- * 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
* @identity: (nullable): the expected peer identity
* to iterate over the elements of a #GHashTable. GHashTableIter
* structures are typically allocated on the stack and then initialized
* with g_hash_table_iter_init().
+ *
+ * The iteration order of a #GHashTableIter over the keys/values in a hash
+ * table is not defined.
*/
* |[<!-- language="C" -->
* #define G_SPAWN_ERROR g_spawn_error_quark ()
*
- * GQuark
- * g_spawn_error_quark (void)
- * {
- * return g_quark_from_static_string ("g-spawn-error-quark");
- * }
+ * G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error)
* ]|
*
* - The quark function for the error domain is called
*
* To call a function for each key and value pair use
* g_hash_table_foreach() or use an iterator to iterate over the
- * key/value pairs in the hash table, see #GHashTableIter.
+ * key/value pairs in the hash table, see #GHashTableIter. The iteration order
+ * of a hash table is not defined, and you must not rely on iterating over
+ * keys/values in the same order as they were inserted.
*
* To destroy a #GHashTable use g_hash_table_destroy().
*
/**
* 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.
* items). To remove all items matching a predicate, use
* g_hash_table_foreach_remove().
*
+ * The order in which g_hash_table_foreach() iterates over the keys/values in
+ * the hash table is not defined.
+ *
* See g_hash_table_find() for performance caveats for linear
* order searches in contrast to g_hash_table_lookup().
*/
* Initializes a key/value pair iterator and associates it with
* @hash_table. Modifying the hash table after calling this function
* invalidates the returned iterator.
+ *
+ * The iteration order of a #GHashTableIter over the keys/values in a hash
+ * table is not defined.
+ *
* |[<!-- language="C" -->
* GHashTableIter iter;
* gpointer key, value;
*
* 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:
+ * |[<!-- language="C" -->
+ * GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
+ * g_list_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
*/
* @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:
+ * |[<!-- language="C" -->
+ * 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
*/
* 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:
+ * |[<!-- language="C" -->
+ * GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
+ * g_slist_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
*/
* @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:
+ * |[<!-- language="C" -->
+ * 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
*/
projects / platform / upstream / gobject-introspection.git / commitdiff