diff options
Diffstat (limited to 'gir/gio-2.0.c')
| -rw-r--r-- | gir/gio-2.0.c | 2509 |
1 files changed, 2388 insertions, 121 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index b763786e..89ec0e0d 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -261,6 +261,13 @@ /** + * GBytesIcon:bytes: + * + * The bytes containing the icon. + */ + + +/** * GCancellable::cancelled: * @cancellable: a #GCancellable. * @@ -1868,6 +1875,89 @@ /** + * GPropertyAction: + * + * This type is opaque. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:enabled: + * + * If @action is currently enabled. + * + * If the action is disabled then calls to g_action_activate() and + * g_action_change_state() have no effect. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:name: + * + * The name of the action. This is mostly meaningful for identifying + * the action once it has been added to a #GActionMap. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:object: + * + * The object to wrap a property on. + * + * The object must be a non-%NULL #GObject with properties. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:parameter-type: + * + * The type of the parameter that must be given when activating the + * action. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:property-name: + * + * The name of the property to wrap on the object. + * + * The property must exist on the passed-in object and it must be + * readable and writable (and not construct-only). + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state: + * + * The state of the action, or %NULL if the action is stateless. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state-type: + * + * The #GVariantType of the state that the action has, or %NULL if the + * action is stateless. + * + * Since: 2.38 + */ + + +/** * GProxyAddress: * * A #GInetSocketAddress representing a connection via a proxy server @@ -1897,6 +1987,25 @@ /** + * GProxyAddressEnumerator:default-port: + * + * The default port to use if #GProxyAddressEnumerator:uri does not + * specify one. + * + * Since: 2.38 + */ + + +/** + * GProxyAddressEnumerator:proxy-resolver: + * + * The proxy resolver to use. + * + * Since: 2.36 + */ + + +/** * GRemoteActionGroupInterface: * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full() * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full() @@ -2213,9 +2322,78 @@ /** + * GSimpleProxyResolver:default-proxy: + * + * The default proxy URI that will be used for any URI that doesn't + * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any + * of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). + * + * Note that as a special case, if this URI starts with + * "<literal>socks://</literal>", #GSimpleProxyResolver will treat + * it as referring to all three of the <literal>socks5</literal>, + * <literal>socks4a</literal>, and <literal>socks4</literal> proxy + * types. + */ + + +/** + * GSimpleProxyResolver:ignore-hosts: + * + * A list of hostnames and IP addresses that the resolver should + * allow direct connections to. + * + * Entries can be in one of 4 formats: + * + * <itemizedlist> + * <listitem> + * A hostname, such as "<literal>example.com</literal>", + * "<literal>.example.com</literal>", or + * "<literal>*.example.com</literal>", any of which match + * "<literal>example.com</literal>" or any subdomain of it. + * </listitem> + * <listitem> + * An IPv4 or IPv6 address, such as + * "<literal>192.168.1.1</literal>", which matches only + * that address. + * </listitem> + * <listitem> + * A hostname or IP address followed by a port, such as + * "<literal>example.com:80</literal>", which matches whatever + * the hostname or IP address would match, but only for URLs + * with the (explicitly) indicated port. In the case of an IPv6 + * address, the address part must appear in brackets: + * "<literal>[::1]:443</literal>" + * </listitem> + * <listitem> + * An IP address range, given by a base address and prefix length, + * such as "<literal>fe80::/10</literal>", which matches any + * address in that range. + * </listitem> + * </itemizedlist> + * + * Note that when dealing with Unicode hostnames, the matching is + * done against the ASCII form of the name. + * + * Also note that hostname exclusions apply only to connections made + * to hosts identified by name, and IP address exclusions apply only + * to connections made to hosts identified by address. That is, if + * <literal>example.com</literal> has an address of + * <literal>192.168.1.1</literal>, and the :ignore-hosts list + * contains only "<literal>192.168.1.1</literal>", then a connection + * to "<literal>example.com</literal>" (eg, via a #GNetworkAddress) + * will use the proxy, and a connection to + * "<literal>192.168.1.1</literal>" (eg, via a #GInetSocketAddress) + * will not. + * + * These rules match the "ignore-hosts"/"noproxy" rules most + * commonly used by other applications. + */ + + +/** * GSocket:broadcast: * - * Whether the socket should allow sending to and receiving from broadcast addresses. + * Whether the socket should allow sending to broadcast addresses. * * Since: 2.32 */ @@ -2366,6 +2544,15 @@ /** + * GSocketClient:proxy-resolver: + * + * The proxy resolver to use + * + * Since: 2.36 + */ + + +/** * GSocketService::incoming: * @service: the #GSocketService * @connection: a new #GSocketConnection object @@ -2392,6 +2579,41 @@ /** + * GTask: + * + * The opaque object representing a synchronous or asynchronous task + * and its result. + */ + + +/** + * GTaskThreadFunc: + * @task: the #GTask + * @source_object: (type GObject): @task's source object + * @task_data: @task's task data + * @cancellable: @task's #GCancellable, or %NULL + * + * The prototype for a task function to be run in a thread via + * g_task_run_in_thread() or g_task_run_in_thread_sync(). + * + * If the return-on-cancel flag is set on @task, and @cancellable gets + * cancelled, then the #GTask will be completed immediately (as though + * g_task_return_error_if_cancelled() had been called), without + * waiting for the task function to complete. However, the task + * function will continue running in its thread in the background. The + * function therefore needs to be careful about how it uses + * externally-visible state in this case. See + * g_task_set_return_on_cancel() for more details. + * + * Other than in that case, @task will be completed when the + * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls + * a <literal>g_task_return_</literal> function. + * + * Since: 2.36 + */ + + +/** * GTestDBus: * * The #GTestDBus structure contains only private data and @@ -3698,13 +3920,13 @@ * * for (l = self->priv->init_results; l != NULL; l = l->next) * { - * GSimpleAsyncResult *simple = l->data; + * GTask *task = l->data; * - * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * - * g_simple_async_result_complete (simple); - * g_object_unref (simple); + * if (self->priv->success) + * g_task_return_boolean (task, TRUE); + * else + * g_task_return_new_error (task, ...); + * g_object_unref (task); * } * * g_list_free (self->priv->init_results); @@ -3719,31 +3941,28 @@ * gpointer user_data) * { * Foo *self = FOO (initable); - * GSimpleAsyncResult *simple; + * GTask *task; * - * simple = g_simple_async_result_new (G_OBJECT (initable) - * callback, - * user_data, - * foo_init_async); + * task = g_task_new (initable, cancellable, callback, user_data); * * switch (self->priv->state) * { * case NOT_INITIALIZED: * _foo_get_ready (self); * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * self->priv->state = INITIALIZING; * break; * case INITIALIZING: * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * break; * case INITIALIZED: * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); + * g_task_return_new_error (task, ...); + * else + * g_task_return_boolean (task, TRUE); + * g_object_unref (task); * break; * } * } @@ -3753,14 +3972,9 @@ * GAsyncResult *result, * GError **error) * { - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (initable), foo_init_async), FALSE); + * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); * - * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), - * error)) - * return FALSE; - * - * return TRUE; + * return g_task_propagate_boolean (G_TASK (result), error); * } * * static void @@ -3780,7 +3994,7 @@ * SECTION:gasyncresult * @short_description: Asynchronous Function Results * @include: gio/gio.h - * @see_also: #GSimpleAsyncResult + * @see_also: #GTask * * Provides a base class for implementing asynchronous function results. * @@ -3812,7 +4026,7 @@ * |[ * void _theoretical_frobnitz_async (Theoretical *t, * GCancellable *c, - * GAsyncReadyCallback *cb, + * GAsyncReadyCallback cb, * gpointer u); * * gboolean _theoretical_frobnitz_finish (Theoretical *t, @@ -3853,6 +4067,16 @@ * The callback for an asynchronous operation is called only once, and is * always called, even in the case of a cancelled operation. On cancellation * the result is a %G_IO_ERROR_CANCELLED error. + * + * <para id="io-priority"><indexterm><primary>I/O + * priority</primary></indexterm> Many I/O-related asynchronous + * operations have a priority parameter, which is used in certain + * cases to determine the order in which operations are executed. They + * are <emphasis>not</emphasis> used to determine system-wide I/O + * scheduling. Priorities are integers, with lower numbers indicating + * higher priority. It is recommended to choose priorities between + * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a + * default. </para> */ @@ -3903,6 +4127,19 @@ /** + * SECTION:gbytesicon + * @short_description: An icon stored in memory as a GBytes + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon, #GBytes + * + * #GBytesIcon specifies an image held in memory in a common format (usually + * png) to be used as icon. + * + * Since: 2.38 + */ + + +/** * SECTION:gcancellable * @short_description: Thread-safe Operation Cancellation Stack * @include: gio/gio.h @@ -4211,7 +4448,10 @@ * </programlisting></example> * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. - * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead + * + * If the other peer is using GDBus, and has registered the association with + * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark + * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). * @@ -4545,7 +4785,7 @@ /** * SECTION:gdbusutils * @title: D-Bus Utilities - * @short_description: Various utilities related to D-Bus. + * @short_description: Various utilities related to D-Bus * @include: gio/gio.h * * Various utility routines related to D-Bus. @@ -4579,7 +4819,7 @@ * #GDrive is a container class for #GVolume objects that stem from * the same piece of media. As such, #GDrive abstracts a drive with * (or without) removable media and provides operations for querying - * whether media is available, determing whether media change is + * whether media is available, determining whether media change is * automatically detected and ejecting the media. * * If the #GDrive reports that media isn't automatically detected, one @@ -4726,7 +4966,7 @@ * File attributes in GIO consist of a list of key-value pairs. * * Keys are strings that contain a key namespace and a key name, separated - * by a colon, e.g. "namespace:keyname". Namespaces are included to sort + * by a colon, e.g. "namespace::keyname". Namespaces are included to sort * key-value pairs by namespaces for relevance. Keys can be retrived * using wildcards, e.g. "standard::*" will return all of the keys in the * "standard" namespace. @@ -4820,7 +5060,7 @@ * <para><table> * <title>GFileAttributes Built-in Keys and Value Types</title> * <tgroup cols='3' align='left'><thead> - * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row> + * <row><entry>Enum Value</entry><entry>Namespace::Key</entry><entry>Value Type</entry></row> * </thead><tbody> * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row> * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row> @@ -4932,6 +5172,17 @@ * version will return a list of #GFileInfo<!---->s, whereas the * synchronous will only return the next file in the enumerator. * + * The ordering of returned files is unspecified for non-Unix + * platforms; for more information, see g_dir_read_name(). On Unix, + * when operating on local files, returned files will be sorted by + * inode number. Effectively you can assume that the ordering of + * returned files will be stable between successive calls (and + * applications) assuming the directory is unchanged. + * + * If your application needs a specific ordering, such as by name or + * modification time, you will have to implement that in your + * application code. + * * To close a #GFileEnumerator, use g_file_enumerator_close(), or * its asynchronous version, g_file_enumerator_close_async(). Once * a #GFileEnumerator is closed, no further actions may be performed @@ -5129,12 +5380,22 @@ * * To check if two #GIcons are equal, see g_icon_equal(). * - * For serializing a #GIcon, use g_icon_to_string() and - * g_icon_new_for_string(). + * For serializing a #GIcon, use g_icon_serialize() and + * g_icon_deserialize(). + * + * If you want to consume #GIcon (for example, in a toolkit) you must + * be prepared to handle at least the three following cases: + * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make + * sense to have fast-paths for other cases (like handling #GdkPixbuf + * directly, for example) but all compliant #GIcon implementations + * outside of GIO must implement #GLoadableIcon. * * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). + * implementations you need to ensure that your new implementation also + * implements #GLoadableIcon. Additionally, you must provide an + * implementation of g_icon_serialize() that gives a result that is + * understood by g_icon_deserialize(), yielding one of the built-in icon + * types. */ @@ -5249,17 +5510,13 @@ * @short_description: I/O Scheduler * @include: gio/gio.h * + * <note><para> + * As of GLib 2.36, the <literal>g_io_scheduler</literal> methods + * are deprecated in favor of #GThreadPool and #GTask. + * </para></note> + * * Schedules asynchronous I/O operations. #GIOScheduler integrates * into the main event loop (#GMainLoop) and uses threads. - * - * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> - * Each I/O operation has a priority, and the scheduler uses the priorities - * to determine the order in which operations are executed. They are - * <emphasis>not</emphasis> used to determine system-wide I/O scheduling. - * Priorities are integers, with lower numbers indicating higher priority. - * It is recommended to choose priorities between %G_PRIORITY_LOW and - * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. - * </para> */ @@ -5523,7 +5780,7 @@ * * Unmounting a #GMount instance is an asynchronous operation. For * more information about asynchronous operations, see #GAsyncResult - * and #GSimpleAsyncResult. To unmount a #GMount instance, first call + * and #GTask. To unmount a #GMount instance, first call * g_mount_unmount_with_operation() with (at least) the #GMount instance and a * #GAsyncReadyCallback. The callback will be fired when the * operation has resolved (either with success or failure), and a @@ -5573,6 +5830,33 @@ /** + * SECTION:gnetworking + * @title: gnetworking.h + * @short_description: System networking includes + * @include: gio/gnetworking.h + * + * The <literal>gnetworking.h</literal> header can be included to get + * various low-level networking-related system headers, automatically + * taking care of certain portability issues for you. + * + * This can be used, for example, if you want to call setsockopt() + * on a #GSocket. + * + * Note that while WinSock has many of the same APIs as the + * traditional UNIX socket API, most of them behave at least slightly + * differently (particularly with respect to error handling). If you + * want your code to work under both UNIX and Windows, you will need + * to take these differences into account. + * + * Also, under glibc, certain non-portable functions are only visible + * in the headers if you define <literal>_GNU_SOURCE</literal> before + * including them. Note that this symbol must be defined before + * including <emphasis>any</emphasis> headers, or it may not take + * effect. + */ + + +/** * SECTION:gnetworkmonitor * @title: GNetworkMonitor * @short_description: Network status monitor @@ -5672,7 +5956,7 @@ /** * SECTION:gpollableutils - * @short_description: #GPollableInputStream / #GPollableOutputStream utilities + * @short_description: Utilities for pollable streams * @include: gio/gio.h * * Utility functions for #GPollableInputStream and @@ -5681,6 +5965,68 @@ /** + * SECTION:gpropertyaction + * @title: GPropertyAction + * @short_description: A GAction reflecting a GObject property + * + * A #GPropertyAction is a way to get a #GAction with a state value + * reflecting and controlling the value of a #GObject property. + * + * The state of the action will correspond to the value of the property. + * Changing it will change the property (assuming the requested value + * matches the requirements as specified in the #GParamSpec). + * + * Only the most common types are presently supported. Booleans are + * mapped to booleans, strings to strings, signed/unsigned integers to + * int32/uint32 and floats and doubles to doubles. + * + * If the property is an enum then the state will be string-typed and + * conversion will automatically be performed between the enum value and + * "nick" string as per the #GEnumValue table. + * + * Flags types are not currently supported. + * + * Properties of object types, boxed types and pointer types are not + * supported and probably never will be. + * + * Properties of #GVariant types are not currently supported. + * + * If the property is boolean-valued then the action will have a NULL + * parameter type, and activating the action (with no parameter) will + * toggle the value of the property. + * + * In all other cases, the parameter type will correspond to the type of + * the property. + * + * The general idea here is to reduce the number of locations where a + * particular piece of state is kept (and therefore has to be + * synchronised between). #GPropertyAction does not have a separate + * state that is kept in sync with the property value -- its state + * <em>is</em> the property value. + * + * For example, it might be useful to create a #GAction corresponding to + * the "visible-child-name" property of a #GtkStack so that the current + * page can be switched from a menu. The active radio indication in the + * menu is then directly determined from the active page of the + * #GtkStack. + * + * An anti-example would be binding the "active-id" property on a + * #GtkComboBox. This is because the state of the combobox itself is + * probably uninteresting and is actually being used to control + * something else. + * + * Another anti-example would be to bind to the "visible-child-name" + * property of a #GtkStack if this value is actually stored in + * #GSettings. In that case, the real source of the value is + * #GSettings. If you want a #GAction to control a setting stored in + * #GSettings, see g_settings_create_action() instead, and possibly + * combine its use with g_settings_bind(). + * + * Since: 2.38 + */ + + +/** * SECTION:gproxy * @short_description: Interface for proxy handling * @@ -5717,7 +6063,7 @@ /** * SECTION:gremoteactiongroup * @title: GRemoteActionGroup - * @short_description: a #GActionGroup that interacts with other processes + * @short_description: A GActionGroup that interacts with other processes * * The GRemoteActionGroup interface is implemented by #GActionGroup * instances that either transmit action invocations to other processes @@ -6095,7 +6441,7 @@ /** * SECTION:gsettingsschema - * @short_description: introspecting and controlling the loading of GSettings schemas + * @short_description: Introspecting and controlling the loading of GSettings schemas * * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a * mechanism for advanced control over the loading of schemas and a @@ -6221,10 +6567,12 @@ * @include: gio/gio.h * @see_also: #GAsyncResult * - * Implements #GAsyncResult for simple cases. Most of the time, this - * will be all an application needs, and will be used transparently. - * Because of this, #GSimpleAsyncResult is used throughout GIO for - * handling asynchronous functions. + * <note><para> + * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of + * #GTask, which provides a simpler API. + * </para></note> + * + * #GSimpleAsyncResult implements #GAsyncResult. * * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error * reporting, operation cancellation and the final state of an operation, @@ -6405,10 +6753,29 @@ /** + * SECTION:gsimpleproxyresolver + * @short_description: Simple proxy resolver implementation + * @include: gio/gio.h + * @see_also: g_socket_client_set_proxy_resolver() + * + * #GSimpleProxyResolver is a simple #GProxyResolver implementation + * that handles a single default proxy, multiple URI-scheme-specific + * proxies, and a list of hosts that proxies should not be used for. + * + * #GSimpleProxyResolver is never the default proxy resolver, but it + * can be used as the base class for another proxy resolver + * implementation, or it can be created and used manually, such as + * with g_socket_client_set_proxy_resolver(). + * + * Since: 2.36 + */ + + +/** * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable + * @see_also: #GInitable, <link linkend="gio-gnetworking.h">gnetworking.h</link> * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -6519,7 +6886,7 @@ * GSocketAddress *sockaddr; * GError *conn_error = NULL; * - * addr = g_network_address_new ("www.gnome.org", 80); + * addr = g_network_address_new (hostname, port); * enumerator = g_socket_connectable_enumerate (addr); * g_object_unref (addr); * @@ -6696,6 +7063,534 @@ /** + * SECTION:gtask + * @short_description: Cancellable synchronous or asynchronous task and result + * @include: gio/gio.h + * @see_also: #GAsyncResult + * + * <para> + * A #GTask represents and manages a cancellable "task". + * </para> + * <refsect2> + * <title>Asynchronous operations</title> + * <para> + * The most common usage of #GTask is as a #GAsyncResult, to + * manage data during an asynchronous operation. You call + * g_task_new() in the "start" method, followed by + * g_task_set_task_data() and the like if you need to keep some + * additional data associated with the task, and then pass the + * task object around through your asynchronous operation. + * Eventually, you will call a method such as + * g_task_return_pointer() or g_task_return_error(), which will + * save the value you give it and then invoke the task's callback + * function (waiting until the next iteration of the main + * loop first, if necessary). The caller will pass the #GTask back + * to the operation's finish function (as a #GAsyncResult), and + * you can use g_task_propagate_pointer() or the like to extract + * the return value. + * </para> + * <example id="gtask-async"><title>GTask as a GAsyncResult</title> + * <programlisting> + * typedef struct { + * CakeFrostingType frosting; + * char *message; + * } DecorationData; + * + * static void + * decoration_data_free (DecorationData *decoration) + * { + * g_free (decoration->message); + * g_slice_free (DecorationData, decoration); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * DecorationData *decoration = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) + * { + * g_object_unref (cake); + * /* g_task_return_error() takes ownership of error */ + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * g_task_return_pointer (result, cake, g_object_unref); + * g_object_unref (task); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * DecorationData *decoration; + * Cake *cake; + * + * task = g_task_new (self, cancellable, callback, user_data); + * if (radius < 3) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, + * "%ucm radius cakes are silly", + * radius); + * g_object_unref (task); + * return; + * } + * + * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); + * if (cake != NULL) + * { + * /* _baker_get_cached_cake() returns a reffed cake */ + * g_task_return_pointer (task, cake, g_object_unref); + * g_object_unref (task); + * return; + * } + * + * decoration = g_slice_new (DecorationData); + * decoration->frosting = frosting; + * decoration->message = g_strdup (message); + * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * </programlisting> + * </example> + * </refsect2> + * <refsect2> + * <title>Chained asynchronous operations</title> + * <para> + * #GTask also tries to simplify asynchronous operations that + * internally chain together several smaller asynchronous + * operations. g_task_get_cancellable(), g_task_get_context(), and + * g_task_get_priority() allow you to get back the task's + * #GCancellable, #GMainContext, and <link + * linkend="io-priority">I/O priority</link> when starting a new + * subtask, so you don't have to keep track of them yourself. + * g_task_attach_source() simplifies the case of waiting for a + * source to fire (automatically using the correct #GMainContext + * and priority). + * </para> + * <example id="gtask-chained"><title>Chained asynchronous operations</title> + * <programlisting> + * typedef struct { + * Cake *cake; + * CakeFrostingType frosting; + * char *message; + * } BakingData; + * + * static void + * decoration_data_free (BakingData *bd) + * { + * if (bd->cake) + * g_object_unref (bd->cake); + * g_free (bd->message); + * g_slice_free (BakingData, bd); + * } + * + * static void + * decorated_cb (Cake *cake, + * GAsyncResult *result, + * gpointer user_data) + * { + * GTask *task = user_data; + * GError *error = NULL; + * + * if (!cake_decorate_finish (cake, result, &error)) + * { + * g_object_unref (cake); + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * /* baking_data_free() will drop its ref on the cake, so + * * we have to take another here to give to the caller. + * */ + * g_task_return_pointer (result, g_object_ref (cake), g_object_unref); + * g_object_unref (task); + * } + * + * static void + * decorator_ready (gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * + * cake_decorate_async (bd->cake, bd->frosting, bd->message, + * g_task_get_cancellable (task), + * decorated_cb, task); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * bd->cake = cake; + * + * /* Bail out now if the user has already cancelled */ + * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task))) + * { + * g_object_unref (task); + * return; + * } + * + * if (cake_decorator_available (cake)) + * decorator_ready (task); + * else + * { + * GSource *source; + * + * source = cake_decorator_wait_source_new (cake); + * /* Attach @source to @task's GMainContext and have it call + * * decorator_ready() when it is ready. + * */ + * g_task_attach_source (task, source, + * G_CALLBACK (decorator_ready)); + * g_source_unref (source); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * gint priority, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * BakingData *bd; + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_priority (task, priority); + * + * bd = g_slice_new0 (BakingData); + * bd->frosting = frosting; + * bd->message = g_strdup (message); + * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * </programlisting> + * </example> + * </refsect2> + * <refsect2> + * <title>Asynchronous operations from synchronous ones</title> + * <para> + * You can use g_task_run_in_thread() to turn a synchronous + * operation into an asynchronous one, by running it in a thread + * which will then dispatch the result back to the caller's + * #GMainContext when it completes. + * </para> + * <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title> + * <programlisting> + * typedef struct { + * guint radius; + * CakeFlavor flavor; + * CakeFrostingType frosting; + * char *message; + * } CakeData; + * + * static void + * cake_data_free (CakeData *cake_data) + * { + * g_free (cake_data->message); + * g_slice_free (CakeData, cake_data); + * } + * + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * cancellable, &error); + * if (cake) + * g_task_return_pointer (task, cake, g_object_unref); + * else + * g_task_return_error (task, error); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * cake_data->radius = radius; + * cake_data->flavor = flavor; + * cake_data->frosting = frosting; + * cake_data->message = g_strdup (message); + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * </programlisting> + * </example> + * </refsect2> + * <refsect2> + * <title>Adding cancellability to uncancellable tasks</title> + * <para> + * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() + * can be used to turn an uncancellable operation into a + * cancellable one. If you call g_task_set_return_on_cancel(), + * passing %TRUE, then if the task's #GCancellable is cancelled, + * it will return control back to the caller immediately, while + * allowing the task thread to continue running in the background + * (and simply discarding its result when it finally does finish). + * Provided that the task thread is careful about how it uses + * locks and other externally-visible resources, this allows you + * to make "GLib-friendly" asynchronous and cancellable + * synchronous variants of blocking APIs. + * </para> + * <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title> + * <programlisting> + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * &error); + * if (error) + * { + * g_task_return_error (task, error); + * return; + * } + * + * /* If the task has already been cancelled, then we don't + * * want to add the cake to the cake cache. Likewise, we don't + * * want to have the task get cancelled in the middle of + * * updating the cache. g_task_set_return_on_cancel() will + * * return %TRUE here if it managed to disable return-on-cancel, + * * or %FALSE if the task was cancelled before it could. + * */ + * if (g_task_set_return_on_cancel (task, FALSE)) + * { + * /* If the caller cancels at this point, their + * * GAsyncReadyCallback won't be invoked until we return, + * * so we don't have to worry that this code will run at + * * the same time as that code does. But if there were + * * other functions that might look at the cake cache, + * * then we'd probably need a GMutex here as well. + * */ + * baker_add_cake_to_cache (baker, cake); + * g_task_return_pointer (task, cake, g_object_unref); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * /* ... */ + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_sync (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GError **error) + * { + * CakeData *cake_data; + * GTask *task; + * Cake *cake; + * + * cake_data = g_slice_new (CakeData); + * /* ... */ + * + * task = g_task_new (self, cancellable, NULL, NULL); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread_sync (task, bake_cake_thread); + * + * cake = g_task_propagate_pointer (task, error); + * g_object_unref (task); + * return cake; + * } + * </programlisting> + * </example> + * </refsect2> + * <refsect2> + * <title>Porting from <literal>GSimpleAsyncResult</literal></title> + * <para> + * #GTask's API attempts to be simpler than #GSimpleAsyncResult's + * in several ways: + * </para> + * <itemizedlist> + * <listitem><para> + * You can save task-specific data with g_task_set_task_data(), and + * retrieve it later with g_task_get_task_data(). This replaces the + * abuse of g_simple_async_result_set_op_res_gpointer() for the same + * purpose with #GSimpleAsyncResult. + * </para></listitem> + * <listitem><para> + * In addition to the task data, #GTask also keeps track of the + * <link linkend="io-priority">priority</link>, #GCancellable, and + * #GMainContext associated with the task, so tasks that consist of + * a chain of simpler asynchronous operations will have easy access + * to those values when starting each sub-task. + * </para></listitem> + * <listitem><para> + * g_task_return_error_if_cancelled() provides simplified + * handling for cancellation. In addition, cancellation + * overrides any other #GTask return value by default, like + * #GSimpleAsyncResult does when + * g_simple_async_result_set_check_cancellable() is called. + * (You can use g_task_set_check_cancellable() to turn off that + * behavior.) On the other hand, g_task_run_in_thread() + * guarantees that it will always run your + * <literal>task_func</literal>, even if the task's #GCancellable + * is already cancelled before the task gets a chance to run; + * you can start your <literal>task_func</literal> with a + * g_task_return_error_if_cancelled() check if you need the + * old behavior. + * </para></listitem> + * <listitem><para> + * The "return" methods (eg, g_task_return_pointer()) + * automatically cause the task to be "completed" as well, and + * there is no need to worry about the "complete" vs "complete + * in idle" distinction. (#GTask automatically figures out + * whether the task's callback can be invoked directly, or + * if it needs to be sent to another #GMainContext, or delayed + * until the next iteration of the current #GMainContext.) + * </para></listitem> + * <listitem><para> + * The "finish" functions for #GTask-based operations are generally + * much simpler than #GSimpleAsyncResult ones, normally consisting + * of only a single call to g_task_propagate_pointer() or the like. + * Since g_task_propagate_pointer() "steals" the return value from + * the #GTask, it is not necessary to juggle pointers around to + * prevent it from being freed twice. + * </para></listitem> + * <listitem><para> + * With #GSimpleAsyncResult, it was common to call + * g_simple_async_result_propagate_error() from the + * <literal>_finish()</literal> wrapper function, and have + * virtual method implementations only deal with successful + * returns. This behavior is deprecated, because it makes it + * difficult for a subclass to chain to a parent class's async + * methods. Instead, the wrapper function should just be a + * simple wrapper, and the virtual method should call an + * appropriate <literal>g_task_propagate_</literal> function. + * Note that wrapper methods can now use + * g_async_result_legacy_propagate_error() to do old-style + * #GSimpleAsyncResult error-returning behavior, and + * g_async_result_is_tagged() to check if a result is tagged as + * having come from the <literal>_async()</literal> wrapper + * function (for "short-circuit" results, such as when passing + * 0 to g_input_stream_read_async()). + * </para></listitem> + * </itemizedlist> + * </refsect2> + */ + + +/** * SECTION:gtcpconnection * @title: GTcpConnection * @short_description: A TCP GSocketConnection @@ -6711,7 +7606,7 @@ /** * SECTION:gtcpwrapperconnection * @title: GTcpWrapperConnection - * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams + * @short_description: Wrapper for non-GSocketConnection-based, GSocket-based GIOStreams * @see_also: #GSocketConnection. * * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is @@ -6729,7 +7624,83 @@ * @short_description: D-Bus testing helper * @include: gio/gio.h * - * Helper to test D-Bus code wihtout messing up with user' session bus. + * A helper class for testing code which uses D-Bus without touching the user's + * session bus. + * + * <refsect2 id="gio-D-Bus-Test-Scaffolding"> + * <title>Creating unit tests using GTestDBus</title> + * <para> + * Testing of D-Bus services can be tricky because normally we only ever run + * D-Bus services over an existing instance of the D-Bus daemon thus we + * usually don't activate D-Bus services that are not yet installed into the + * target system. The #GTestDBus object makes this easier for us by taking care + * of the lower level tasks such as running a private D-Bus daemon and looking + * up uninstalled services in customizable locations, typically in your source code tree. + * </para> + * <para> + * The first thing you will need is a separate service description file for the + * D-Bus daemon. Typically a 'services' subdirectory of your 'tests' directory + * is a good place to put this file. + * </para> + * <para> + * The service file should list your service along with an absolute path to the + * uninstalled service executable in your source tree. Using autotools we would + * achieve this by adding a file such as 'my-server.service.in' in the services + * directory and have it processed by configure. + * <informalexample><programlisting> + * [D-BUS Service] + * Name=org.gtk.GDBus.Examples.ObjectManager + * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server + * </programlisting></informalexample> + * You will also need to indicate this service directory in your test + * fixtures, so you will need to pass the path while compiling your + * test cases. Typically this is done with autotools with an added + * preprocessor flag specified to compile your tests such as: + * <informalexample><programlisting> + * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" + * </programlisting></informalexample> + * </para> + * <para> + * Once you have a service definition file which is local to your source tree, + * you can proceed to setup a GTest fixture using the GTestDBus scaffolding. + * <example id="gdbus-test-fixture"> + * <title>Test Fixture for D-Bus services</title> + * <programlisting> + * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-test-fixture.c"> + * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> + * </xi:include> + * </programlisting> + * </example> + * </para> + * <para> + * Note that these examples only deal with isolating the D-Bus aspect of your + * service. To successfully run isolated unit tests on your service you may need + * some additional modifications to your test case fixture. For example; if your + * service uses GSettings and installs a schema then it is important that your test service + * not load the schema in the ordinary installed location (chances are that your service + * and schema files are not yet installed, or worse; there is an older version of the + * schema file sitting in the install location). + * </para> + * <para> + * Most of the time we can work around these obstacles using the environment. Since the + * environment is inherited by the D-Bus daemon created by GTestDBus and then in turn + * inherited by any services the D-Bus daemon activates, using the setup routine for your + * fixture is a practical place to help sandbox your runtime environment. For the rather + * typical GSettings case we can work around this by setting GSETTINGS_SCHEMA_DIR to the + * in tree directory holding your schemas in the above fixture_setup() routine. + * </para> + * <para> + * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved + * by compiling the schemas locally as a step before running test cases, an autotools setup might + * do the following in the directory holding schemas: + * <informalexample><programlisting> + * all-am: + * $(GLIB_COMPILE_SCHEMAS) . + * + * CLEANFILES += gschemas.compiled + * </programlisting></informalexample> + * </para> + * </refsect2> */ @@ -6810,8 +7781,6 @@ * @title: GTlsBackend * @short_description: TLS backend implementation * @include: gio/gio.h - * - * */ @@ -6877,7 +7846,7 @@ * @include: gio/gio.h * * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is in interface which + * their certificate information from a file. It is an interface which * TLS library specific subtypes implement. * * Since: 2.30 @@ -7110,9 +8079,9 @@ * * Mounting a #GVolume instance is an asynchronous operation. For more * information about asynchronous operations, see #GAsyncResult and - * #GSimpleAsyncResult. To mount a #GVolume, first call - * g_volume_mount() with (at least) the #GVolume instance, optionally - * a #GMountOperation object and a #GAsyncReadyCallback. + * #GTask. To mount a #GVolume, first call g_volume_mount() with (at + * least) the #GVolume instance, optionally a #GMountOperation object + * and a #GAsyncReadyCallback. * * Typically, one will only want to pass %NULL for the * #GMountOperation if automounting all volumes when a desktop session @@ -8685,6 +9654,31 @@ /** + * _g_io_module_get_default_type: + * @extension_point: the name of an extension point + * @envvar: (allow-none): the name of an environment variable to override the default implementation. + * @is_supported_offset: a vtable offset, or zero + * + * Retrieves the default class implementing @extension_point. + * + * If @envvar is not %NULL, and the environment variable with that + * name is set, then the implementation it specifies will be tried + * first. After that, or if @envvar is not set, all other + * implementations will be tried in order of decreasing priority. + * + * If @is_supported_offset is non-zero, then it is the offset into the + * class vtable at which there is a function that takes no arguments and + * returns a boolean. This function will be called on each candidate + * implementation to check if it is actually usable or not. + * + * The result is cached after it is generated the first time, and + * the function is thread-safe. + * + * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations. + */ + + +/** * g_action_activate: * @action: a #GAction * @parameter: (allow-none): the parameter to the activation @@ -8695,6 +9689,8 @@ * the parameter type given at construction time). If the parameter * type was %NULL then @parameter must also be %NULL. * + * If the @parameter GVariant is floating, it is consumed. + * * Since: 2.28 */ @@ -9125,7 +10121,7 @@ /** * g_action_map_add_action_entries: * @action_map: a #GActionMap - * @entries: a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to the first item in an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated * @user_data: the user data for signal connections * @@ -9202,6 +10198,82 @@ /** + * g_action_name_is_valid: + * @action_name: an potential action name + * + * Checks if @action_name is valid. + * + * @action_name is valid if it consists only of alphanumeric characters, + * plus '-' and '.'. The empty string is not a valid action name. + * + * It is an error to call this function with a non-utf8 @action_name. + * @action_name must not be %NULL. + * + * Returns: %TRUE if @action_name is valid + * Since: 2.38 + */ + + +/** + * g_action_parse_detailed_name: + * @detailed_name: a detailed action name + * @action_name: (out): the action name + * @target_value: (out): the target value, or %NULL for no target + * @error: a pointer to a %NULL #GError, or %NULL + * + * Parses a detailed action name into its separate name and target + * components. + * + * Detailed action names can have three formats. + * + * The first format is used to represent an action name with no target + * value and consists of just an action name containing no whitespace + * nor the characters ':', '(' or ')'. For example: "app.action". + * + * The second format is used to represent an action with a target value + * that is a non-empty string consisting only of alphanumerics, plus '-' + * and '.'. In that case, the action name and target value are + * separated by a double colon ("::"). For example: + * "app.action::target". + * + * The third format is used to represent an action with any type of + * target value, including strings. The target value follows the action + * name, surrounded in parens. For example: "app.action(42)". The + * target value is parsed using g_variant_parse(). If a tuple-typed + * value is desired, it must be specified in the same way, resulting in + * two sets of parens, for example: "app.action((1,2,3))". A string + * target can be specified this way as well: "app.action('target')". + * For strings, this third format must be used if * target value is + * empty or contains characters other than alphanumerics, '-' and '.'. + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.38 + */ + + +/** + * g_action_print_detailed_name: + * @action_name: a valid action name + * @target_value: (allow-none): a #GVariant target value, or %NULL + * + * Formats a detailed action name from @action_name and @target_value. + * + * It is an error to call this function with an invalid action name. + * + * This function is the opposite of + * g_action_parse_detailed_action_name(). It will produce a string that + * can be parsed back to the @action_name and @target_value by that + * function. + * + * See that function for the types of strings that will be printed by + * this function. + * + * Returns: a detailed format string + * Since: 2.38 + */ + + +/** * g_app_info_add_supports_type: * @appinfo: a #GAppInfo. * @content_type: a string. @@ -9751,6 +10823,23 @@ /** + * g_application_command_line_create_file_for_arg: + * @cmdline: a #GApplicationCommandLine + * @arg: an argument from @cmdline + * + * Creates a #GFile corresponding to a filename that was given as part + * of the invocation of @cmdline. + * + * This differs from g_file_new_for_commandline_arg() in that it + * resolves relative pathnames using the current working directory of + * the invoking process rather than the local process. + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 + */ + + +/** * g_application_command_line_get_arguments: * @cmdline: a #GApplicationCommandLine * @argc: (out) (allow-none): the length of the arguments array, or %NULL @@ -9852,6 +10941,26 @@ /** + * g_application_command_line_get_stdin: + * @cmdline: a #GApplicationCommandLine + * + * Gets the stdin of the invoking process. + * + * The #GInputStream can be used to read data passed to the standard + * input of the invoking process. + * This doesn't work on all platforms. Presently, it is only available + * on UNIX when using a DBus daemon capable of passing file descriptors. + * If stdin is not available then %NULL will be returned. In the + * future, support may be expanded to other platforms. + * + * You must only call this function once per commandline invocation. + * + * Returns: (transfer full): a #GInputStream for stdin + * Since: 2.34 + */ + + +/** * g_application_command_line_getenv: * @cmdline: a #GApplicationCommandLine * @name: the environment variable to get @@ -10111,14 +11220,31 @@ /** + * g_application_mark_busy: + * @application: a #GApplication + * + * Increases the busy count of @application. + * + * Use this function to indicate that the application is busy, for instance + * while a long running operation is pending. + * + * The busy state will be exposed to other processes, so a session shell will + * use that information to indicate the state to the user (e.g. with a + * spinner). + * + * To cancel the busy indication, use g_application_unmark_busy(). + * + * Since: 2.38 + */ + + +/** * g_application_new: * @application_id: (allow-none): the application id * @flags: the application flags * * Creates a new #GApplication instance. * - * This function calls g_type_init() for you. - * * If non-%NULL, the application id must be valid. See * g_application_id_is_valid(). * @@ -10297,9 +11423,19 @@ * non-zero then the default main context is iterated until the use count * falls to zero, at which point 0 is returned. * - * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at - * use count of zero is delayed for a while (ie: the instance stays - * around to provide its <emphasis>service</emphasis> to others). + * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will + * run for as much as 10 seconds with a use count of zero while waiting + * for the message that caused the activation to arrive. After that, + * if the use count falls to zero the application will exit immediately, + * except in the case that g_application_set_inactivity_timeout() is in + * use. + * + * This function sets the prgname (g_set_prgname()), if not already set, + * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE + * is specified, the prgname is set to the application ID. The main + * impact of this is is that the wmclass of windows created by Gtk+ will + * be set accordingly, which helps the window manager determine which + * application is showing the window. * * Returns: the exit status * Since: 2.28 @@ -10386,6 +11522,22 @@ /** + * g_application_unmark_busy: + * @application: a #GApplication + * + * Decreases the busy count of @application. + * + * When the busy count reaches zero, the new state will be propagated + * to other processes. + * + * This function must only be called to cancel the effect of a previous + * call to g_application_mark_busy(). + * + * Since: 2.38 + */ + + +/** * g_async_initable_init_async: * @initable: a #GAsyncInitable. * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. @@ -10475,7 +11627,7 @@ * Finishes the async construction for the various g_async_initable_new * calls, returning the created object or %NULL on error. * - * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref(). + * Returns: (type GObject.Object) (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref(). * Since: 2.22 */ @@ -11117,6 +12269,28 @@ /** + * g_bytes_icon_get_bytes: + * @icon: a #GIcon. + * + * Gets the #GBytes associated with the given @icon. + * + * Returns: (transfer none): a #GBytes, or %NULL. + * Since: 2.38 + */ + + +/** + * g_bytes_icon_new: + * @bytes: a #GBytes. + * + * Creates a new icon for a bytes. + * + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given @bytes, or %NULL on error. + * Since: 2.38 + */ + + +/** * g_cancellable_cancel: * @cancellable: a #GCancellable object. * @@ -11736,6 +12910,23 @@ /** + * g_credentials_get_unix_pid: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. + * + * Tries to get the UNIX process identifier from @credentials. This + * method is only available on UNIX platforms. + * + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX process ID. + * + * Returns: The UNIX process ID, or -1 if @error is set. + * Since: 2.36 + */ + + +/** * g_credentials_get_unix_user: * @credentials: A #GCredentials * @error: Return location for error or %NULL. @@ -12386,6 +13577,23 @@ /** + * g_dbus_address_escape_value: + * @string: an unescaped string to be included in a D-Bus address as the value in a key-value pair + * + * Escape @string so it can appear in a D-Bus address as the value + * part of a key-value pair. + * + * For instance, if @string is <code>/run/bus-for-:0</code>, + * this function would return <code>/run/bus-for-%3A0</code>, + * which could be used in a D-Bus address like + * <code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>. + * + * Returns: (transfer full): a copy of @string with all non-optionally-escaped bytes escaped + * Since: 2.36 + */ + + +/** * g_dbus_address_get_for_bus_sync: * @bus_type: A #GBusType. * @cancellable: (allow-none): A #GCancellable or %NULL. @@ -12461,7 +13669,7 @@ * * Looks up the value of an annotation. * - * This cost of this function is O(n) in number of annotations. + * The cost of this function is O(n) in number of annotations. * * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. * Since: 2.26 @@ -12910,7 +14118,7 @@ * The implemented D-Bus API should be considered private. * It is subject to change in the future. * - * An object path can only have one action group exported on it. If this + * An object path can only have one menu model exported on it. If this * constraint is violated, the export will fail and 0 will be * returned (with @error set accordingly). * @@ -13545,6 +14753,11 @@ * tracking the name owner of the well-known name and use that when * processing the received signal. * + * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or + * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is + * interpreted as part of a namespace or path. The first argument + * of a signal is matched against that part as specified by D-Bus. + * * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). * Since: 2.26 */ @@ -14011,7 +15224,7 @@ * * Looks up information about a method. * - * This cost of this function is O(n) in number of methods unless + * The cost of this function is O(n) in number of methods unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14026,7 +15239,7 @@ * * Looks up information about a property. * - * This cost of this function is O(n) in number of properties unless + * The cost of this function is O(n) in number of properties unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14041,7 +15254,7 @@ * * Looks up information about a signal. * - * This cost of this function is O(n) in number of signals unless + * The cost of this function is O(n) in number of signals unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14209,7 +15422,7 @@ * @interface_: A #GDBusInterfaceSkeleton. * @connection: A #GDBusConnection. * - * Checks if @interface_ is export on @connection. + * Checks if @interface_ is exported on @connection. * * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. * Since: 2.32 @@ -15025,6 +16238,11 @@ * * Gets the name of the D-Bus interface the method was invoked on. * + * If this method call is a property Get, Set or GetAll call that has + * been redirected to the method call handler then + * "org.freedesktop.DBus.Properties" will be returned. See + * #GDBusInterfaceVTable for more information. + * * Returns: A string. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15054,6 +16272,11 @@ * * Gets information about the method call, if any. * + * If this method invocation is a property Get, Set or GetAll call that + * has been redirected to the method call handler then %NULL will be + * returned. See g_dbus_method_invocation_get_property_info() and + * #GDBusInterfaceVTable for more information. + * * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15094,6 +16317,27 @@ /** + * g_dbus_method_invocation_get_property_info: + * @invocation: A #GDBusMethodInvocation + * + * Gets information about the property that this method call is for, if + * any. + * + * This will only be set in the case of an invocation in response to a + * property Get or Set call that has been directed to the method call + * handler for an object on account of its property_get() or + * property_set() vtable pointers being unset. + * + * See #GDBusInterfaceVTable for more information. + * + * If the call was GetAll, %NULL will be returned. + * + * Returns: (transfer none): a #GDBusPropertyInfo or %NULL + * Since: 2.38 + */ + + +/** * g_dbus_method_invocation_get_sender: * @invocation: A #GDBusMethodInvocation. * @@ -15271,7 +16515,7 @@ * * Looks up information about an interface. * - * This cost of this function is O(n) in number of interfaces. + * The cost of this function is O(n) in number of interfaces. * * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. * Since: 2.26 @@ -15382,7 +16626,8 @@ * g_dbus_object_manager_client_get_name: * @manager: A #GDBusObjectManagerClient * - * Gets the name that @manager is for. + * Gets the name that @manager is for, or %NULL if not a message bus + * connection. * * Returns: A unique or well-known name. Do not free, the string belongs to @manager. * Since: 2.30 @@ -15508,7 +16753,7 @@ * g_dbus_object_manager_client_new_sync: * @connection: A #GDBusConnection. * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). + * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. * @object_path: The object path of the control object. * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. @@ -16435,6 +17680,36 @@ /** + * g_desktop_app_info_get_action_name: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from g_desktop_app_info_list_actions() + * + * Gets the user-visible display name of the "additional application + * action" specified by @action_name. + * + * This corresponds to the "Name" key within the keyfile group for the + * action. + * + * Returns: (transfer full): the locale-specific action name + * Since: 2.38 + */ + + +/** + * g_desktop_app_info_get_boolean: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a boolean value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: the boolean value, or %FALSE if the key is not found + * Since: 2.36 + */ + + +/** * g_desktop_app_info_get_categories: * @info: a #GDesktopAppInfo * @@ -16536,6 +17811,59 @@ /** + * g_desktop_app_info_get_string: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a string value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: a newly allocated string, or %NULL if the key is not found + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_has_key: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Returns whether @key exists in the "Desktop Entry" group + * of the keyfile backing @info. + * + * Returns: %TRUE if the @key exists + * Since: 2.26 + */ + + +/** + * g_desktop_app_info_launch_action: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from g_desktop_app_info_list_actions() + * @launch_context: (allow-none): a #GAppLaunchContext + * + * Activates the named application action. + * + * You may only call this function on action names that were + * returned from g_desktop_app_info_list_actions(). + * + * Note that if the main entry of the desktop file indicates that the + * application supports startup notification, and @launch_context is + * non-%NULL, then startup notification will be used when activating the + * action (and as such, invocation of the action on the receiving side + * must signal the end of startup notification when it is completed). + * This is the expected behaviour of applications declaring additional + * actions, as per the desktop file specification. + * + * As with g_app_info_launch() there is no way to detect failures that + * occur while using this function. + * + * Since: 2.38 + */ + + +/** * g_desktop_app_info_launch_uris_as_manager: * @appinfo: a #GDesktopAppInfo * @uris: (element-type utf8): List of URIs @@ -16552,21 +17880,36 @@ * launch applications. Ordinary applications should use * g_app_info_launch_uris(). * - * In contrast to g_app_info_launch_uris(), all processes created will - * always be run directly as children as if by the UNIX fork()/exec() - * calls. + * If the application is launched via traditional UNIX fork()/exec() + * then @spawn_flags, @user_setup and @user_setup_data are used for the + * call to g_spawn_async(). Additionally, @pid_callback (with + * @pid_callback_data) will be called to inform about the PID of the + * created process. * - * This guarantee allows additional control over the exact environment - * of the child processes, which is provided via a setup function - * @user_setup, as well as the process identifier of each child process - * via @pid_callback. See g_spawn_async() for more information about the - * semantics of the @user_setup function. + * If application launching occurs via some other mechanism (eg: D-Bus + * activation) then @spawn_flags, @user_setup, @user_setup_data, + * @pid_callback and @pid_callback_data are ignored. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** + * g_desktop_app_info_list_actions: + * @info: a #GDesktopAppInfo + * + * Returns the list of "additional application actions" supported on the + * desktop file, as per the desktop file specification. + * + * As per the specification, this is the list of actions that are + * explicitly listed in the "Actions" key of the [Desktop Entry] group. + * + * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL + * Since: 2.38 + */ + + +/** * g_desktop_app_info_lookup_get_default_for_uri_scheme: * @lookup: a #GDesktopAppInfoLookup * @uri_scheme: a string containing a URI scheme. @@ -17637,6 +18980,7 @@ * Finishes deleting a file started with g_file_delete_async(). * * Virtual: delete_file_finish + * Returns: %TRUE if the file was deleted. %FALSE otherwise. * Since: 2.34 */ @@ -17766,7 +19110,7 @@ * returned. * * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will - * be returned. If the file is not a directory, the %G_FILE_ERROR_NOTDIR + * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY * error will be returned. Other errors are possible too. * * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). @@ -17865,6 +19209,27 @@ /** + * g_file_enumerator_get_child: + * @enumerator: a #GFileEnumerator + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. + * + * Return a new #GFile which refers to the file named by @info in the source + * directory of @enumerator. This function is primarily intended to be used + * inside loops with g_file_enumerator_next_file(). + * + * This is a convenience method that's equivalent to: + * |[ + * gchar *name = g_file_info_get_name (info); + * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), + * name); + * ]| + * + * Returns: (transfer full): a #GFile for the #GFileInfo passed it. + * Since: 2.36 + */ + + +/** * g_file_enumerator_get_container: * @enumerator: a #GFileEnumerator * @@ -17906,6 +19271,9 @@ * returned from this function will contain attributes that match the * attribute string that was passed when the #GFileEnumerator was created. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * On error, returns %NULL and sets @error to the error. If the * enumerator is at the end, %NULL will be returned and @error will * be unset. @@ -17918,7 +19286,7 @@ * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request. + * @io_priority: the <link linkend="io-priority">io priority</link> of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -17927,6 +19295,9 @@ * When all i/o for the operation is finished the @callback will be called with * the requested information. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * The callback can be called with less than @num_files files in case of error * or at the end of the enumerator. In case of a partial error the callback will * be called with any succeeding items and no error, and on the next request the @@ -18466,6 +19837,19 @@ /** + * g_file_info_get_deletion_date: + * @info: a #GFileInfo. + * + * Returns the #GDateTime representing the deletion date of the file, as + * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the + * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. + * + * Returns: a #GDateTime, or %NULL. + * Since: 2.36 + */ + + +/** * g_file_info_get_display_name: * @info: a #GFileInfo. * @@ -19223,6 +20607,36 @@ /** + * g_file_make_directory_async: + * @file: input #GFile + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously creates a directory. + * + * Virtual: make_directory_async + * Since: 2.38 + */ + + +/** + * g_file_make_directory_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous directory creation, started with + * g_file_make_directory_async(). + * + * Virtual: make_directory_finish + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_make_directory_with_parents: * @file: input #GFile * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore @@ -19308,6 +20722,12 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * + * It does not make sense for @flags to contain + * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to + * directories. It is not possible to monitor all the files in a + * directory for changes made via hard links; if you want to do this then + * you must register individual watches with g_file_monitor(). + * * Virtual: monitor_dir * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). */ @@ -19344,6 +20764,14 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * + * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor + * will also attempt to report changes made to the file via another + * filename (ie, a hard link). Without this flag, you can only rely on + * changes made through the filename contained in @file to be + * reported. Using this flag may result in an increase in resource + * usage, and may not have any effect depending on the #GFileMonitor + * backend and/or filesystem type. + * * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). */ @@ -19507,6 +20935,28 @@ /** + * g_file_new_for_commandline_arg_and_cwd: + * @arg: a command line string + * @cwd: the current working directory of the commandline + * + * Creates a #GFile with the given argument from the command line. + * + * This function is similar to g_file_new_for_commandline_arg() except + * that it allows for passing the current working directory as an + * argument instead of using the current working directory of the + * process. + * + * This is useful if the commandline argument was given in a context + * other than the invocation of the current process. + * + * See also g_application_command_line_create_file_for_arg(). + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 + */ + + +/** * g_file_new_for_path: * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. * @@ -20492,7 +21942,7 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if there was any error, %FALSE otherwise. + * Returns: %FALSE if there was any error, %TRUE otherwise. */ @@ -20666,11 +22116,42 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * + * Virtual: trash * Returns: %TRUE on successful trash, %FALSE otherwise. */ /** + * g_file_trash_async: + * @file: input #GFile + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously sends @file to the Trash location, if possible. + * + * Virtual: trash_async + * Since: 2.38 + */ + + +/** + * g_file_trash_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous file trashing operation, started with + * g_file_trash_async(). + * + * Virtual: trash_finish + * Returns: %TRUE on successful trash, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_unmount_mountable: * @file: input #GFile * @flags: flags affecting the operation @@ -20850,6 +22331,17 @@ /** + * g_icon_deserialize: + * @value: a #GVariant created with g_icon_serialize() + * + * Deserializes a #GIcon previously serialized using g_icon_serialize(). + * + * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails. + * Since: 2.38 + */ + + +/** * g_icon_equal: * @icon1: (allow-none): pointer to the first #GIcon. * @icon2: (allow-none): pointer to the second #GIcon. @@ -20889,6 +22381,21 @@ /** + * g_icon_serialize: + * @icon: a #GIcon + * + * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved + * back by calling g_icon_deserialize() on the returned value. + * As serialization will avoid using raw icon data when possible, it only + * makes sense to transfer the #GVariant between processes on the same machine, + * (as opposed to over the network), and within the same file system namespace. + * + * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. + * Since: 2.38 + */ + + +/** * g_icon_to_string: * @icon: a #GIcon. * @@ -21342,7 +22849,7 @@ * similar to g_object_new() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error * Since: 2.22 */ @@ -21359,7 +22866,7 @@ * similar to g_object_new_valist() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error * Since: 2.22 */ @@ -21376,7 +22883,7 @@ * similar to g_object_newv() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error * Since: 2.22 */ @@ -21479,7 +22986,7 @@ /** * g_input_stream_read: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore @@ -21510,7 +23017,7 @@ /** * g_input_stream_read_all: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @bytes_read: (out): location to store the number of bytes that was read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -21537,7 +23044,7 @@ /** * g_input_stream_read_async: * @stream: A #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -22030,6 +23537,8 @@ * * A job is cancellable if a #GCancellable was passed into * g_io_scheduler_push_job(). + * + * Deprecated: You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler. */ @@ -22045,6 +23554,7 @@ * blocking the I/O job). * * Returns: The return value of @func + * Deprecated: Use g_main_context_invoke(). */ @@ -22064,6 +23574,8 @@ * on to this function you have to ensure that it is not freed before * @func is called, either by passing %NULL as @notify to * g_io_scheduler_push_job() or by using refcounting for @user_data. + * + * Deprecated: Use g_main_context_invoke(). */ @@ -22072,7 +23584,7 @@ * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * * Schedules the I/O job to run in another thread. @@ -22083,6 +23595,8 @@ * If @cancellable is not %NULL, it can be used to cancel the I/O job * by calling g_cancellable_cancel() or by calling * g_io_scheduler_cancel_all_jobs(). + * + * Deprecated: use #GThreadPool or g_task_run_in_thread() */ @@ -22508,6 +24022,16 @@ /** + * g_memory_output_stream_new_resizable: + * + * Creates a new #GMemoryOutputStream, using g_realloc() and g_free() + * for memory allocation. + * + * Since: 2.36 + */ + + +/** * g_memory_output_stream_steal_as_bytes: * @ostream: a #GMemoryOutputStream * @@ -23085,14 +24609,8 @@ * * Sets the "action" and possibly the "target" attribute of @menu_item. * - * If @detailed_action contains a double colon ("::") then it is used as - * a separator between an action name and a target string. In this - * case, this call is equivalent to calling - * g_menu_item_set_action_and_target() with the part before the "::" and - * with a string-type #GVariant containing the part following the "::". - * - * If @detailed_action doesn't contain "::" then the action is set to - * the given string (verbatim) and the target value is unset. + * The format of @detailed_action is the same format parsed by + * g_action_parse_detailed_name(). * * See g_menu_item_set_action_and_target() or * g_menu_item_set_action_and_target_value() for more flexible (but @@ -23106,6 +24624,28 @@ /** + * g_menu_item_set_icon: + * @menu_item: a #GMenuItem + * @icon: a #GIcon, or %NULL + * + * Sets (or unsets) the icon on @menu_item. + * + * This call is the same as calling g_icon_serialize() and using the + * result as the value to g_menu_item_set_attribute_value() for + * %G_MENU_ATTRIBUTE_ICON. + * + * This API is only intended for use with "noun" menu items; things like + * bookmarks or applications in an "Open With" menu. Don't use it on + * menu items corresponding to verbs (eg: stock icons for 'Save' or + * 'Quit'). + * + * If @icon is %NULL then the icon is unset. + * + * Since: 2.38 + */ + + +/** * g_menu_item_set_label: * @menu_item: a #GMenuItem * @label: (allow-none): the label to set, or %NULL to unset @@ -23485,6 +25025,16 @@ /** + * g_menu_remove_all: + * @menu: a #GMenu + * + * Removes all items in the menu. + * + * Since: 2.38 + */ + + +/** * g_mount_can_eject: * @mount: a #GMount. * @@ -24305,6 +25855,18 @@ /** + * g_networking_init: + * + * Initializes the platform networking libraries (eg, on Windows, this + * calls WSAStartup()). GLib will call this itself if it is needed, so + * you only need to call it if you directly call system networking + * functions (without calling any GLib networking functions first). + * + * Since: 2.36 + */ + + +/** * g_null_settings_backend_new: * * Creates a readonly #GSettingsBackend. @@ -25197,6 +26759,26 @@ /** + * g_property_action_new: + * @name: the name of the action to create + * @object: the object that has the property to wrap + * @property_name: the name of the property + * + * Creates a #GAction corresponding to the value of property + * @property_name on @object. + * + * The property must be existent and readable and writable (and not + * construct-only). + * + * This function takes a reference on @object and doesn't release it + * until the action is destroyed. + * + * Returns: a new #GPropertyAction + * Since: 2.38 + */ + + +/** * g_proxy_address_get_destination_hostname: * @proxy: a #GProxyAddress * @@ -27401,6 +28983,7 @@ * and adding them to the action group. * * Since: 2.30 + * Deprecated: 2.38: Use g_action_map_add_action_entries() */ @@ -27417,6 +29000,7 @@ * The action group takes its own reference on @action. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_add_action() */ @@ -27431,6 +29015,7 @@ * * Returns: (transfer none): a #GAction, or %NULL * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_lookup_action() */ @@ -27454,6 +29039,7 @@ * If no action of this name is in the group then nothing happens. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_remove_action() */ @@ -27520,6 +29106,8 @@ * property. Instead, they should call g_action_change_state() to * request the change. * + * If the @value GVariant is floating, it is consumed. + * * Since: 2.30 */ @@ -27884,6 +29472,73 @@ /** + * g_simple_proxy_resolver_new: + * @default_proxy: (allow-none): the default proxy to use, eg "socks://192.168.1.1" + * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses to not use a proxy for. + * + * Creates a new #GSimpleProxyResolver. See + * #GSimpleProxyResolver:default-proxy and + * #GSimpleProxyResolver:ignore-hosts for more details on how the + * arguments are interpreted. + * + * Returns: a new #GSimpleProxyResolver + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_default_proxy: + * @resolver: a #GSimpleProxyResolver + * @default_proxy: the default proxy to use + * + * Sets the default proxy on @resolver, to be used for any URIs that + * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set + * via g_simple_proxy_resolver_set_uri_proxy(). + * + * If @default_proxy starts with "<literal>socks://</literal>", + * #GSimpleProxyResolver will treat it as referring to all three of + * the <literal>socks5</literal>, <literal>socks4a</literal>, and + * <literal>socks4</literal> proxy types. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_ignore_hosts: + * @resolver: a #GSimpleProxyResolver + * @ignore_hosts: %NULL-terminated list of hosts/IP addresses to not use a proxy for + * + * Sets the list of ignored hosts. + * + * See #GSimpleProxyResolver:ignore-hosts for more details on how the + * @ignore_hosts argument is interpreted. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_uri_proxy: + * @resolver: a #GSimpleProxyResolver + * @uri_scheme: the URI scheme to add a proxy for + * @proxy: the proxy to use for @uri_scheme + * + * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme + * matches @uri_scheme (and which don't match + * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. + * + * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with + * "<literal>socks://</literal>", #GSimpleProxyResolver will treat it + * as referring to all three of the <literal>socks5</literal>, + * <literal>socks4a</literal>, and <literal>socks4</literal> proxy + * types. + * + * Since: 2.36 + */ + + +/** * g_socket_accept: * @socket: a #GSocket. * @cancellable: (allow-none): a %GCancellable or %NULL @@ -28030,14 +29685,20 @@ * In certain situations, you may also want to bind a socket that will be * used to initiate connections, though this is not normally required. * - * @allow_reuse should be %TRUE for server sockets (sockets that you will - * eventually call g_socket_accept() on), and %FALSE for client sockets. - * (Specifically, if it is %TRUE, then g_socket_bind() will set the - * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if - * that address was previously used by another socket that has not yet been - * fully cleaned-up by the kernel. Failing to set this flag on a server - * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if - * the server program is stopped and then immediately restarted.) + * If @socket is a TCP socket, then @allow_reuse controls the setting + * of the <literal>SO_REUSEADDR</literal> socket option; normally it + * should be %TRUE for server sockets (sockets that you will + * eventually call g_socket_accept() on), and %FALSE for client + * sockets. (Failing to set this flag on a server socket may cause + * g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server + * program is stopped and then immediately restarted.) + * + * If @socket is a UDP socket, then @allow_reuse determines whether or + * not other UDP sockets can be bound to the same address at the same + * time. In particular, you can have several UDP sockets bound to the + * same address, and they will all receive all of the multicast and + * broadcast packets sent to that address. (The behavior of unicast + * UDP packets to an address with multiple listeners is not defined.) * * Returns: %TRUE on success, %FALSE on error. * Since: 2.22 @@ -28397,6 +30058,19 @@ /** + * g_socket_client_get_proxy_resolver: + * @client: a #GSocketClient. + * + * Gets the #GProxyResolver being used by @client. Normally, this will + * be the resolver returned by g_proxy_resolver_get_default(), but you + * can override it with g_socket_client_set_proxy_resolver(). + * + * Returns: (transfer none): The #GProxyResolver being used by @client. + * Since: 2.36 + */ + + +/** * g_socket_client_get_socket_type: * @client: a #GSocketClient. * @@ -28466,6 +30140,8 @@ * #GProxyResolver to determine if a proxy protocol such as SOCKS is * needed, and automatically do the necessary proxy negotiation. * + * See also g_socket_client_set_proxy_resolver(). + * * Since: 2.26 */ @@ -28522,6 +30198,23 @@ /** + * g_socket_client_set_proxy_resolver: + * @client: a #GSocketClient. + * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the default. + * + * Overrides the #GProxyResolver used by @client. You can call this if + * you want to use specific proxies, rather than using the system + * default proxy settings. + * + * Note that whether or not the proxy resolver is actually used + * depends on the setting of #GSocketClient:enable-proxy, which is not + * changed by this function (but which is %TRUE by default) + * + * Since: 2.36 + */ + + +/** * g_socket_client_set_socket_type: * @client: a #GSocketClient. * @type: a #GSocketType @@ -29045,7 +30738,7 @@ * * Gets the broadcast setting on @socket; if %TRUE, * it is possible to send packets to broadcast - * addresses or receive from broadcast addresses. + * addresses. * * Returns: the broadcast setting on @socket * Since: 2.32 @@ -29165,6 +30858,34 @@ /** + * g_socket_get_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>) + * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>) + * @value: (out): return location for the option value + * @error: #GError for error reporting, or %NULL to ignore. + * + * Gets the value of an integer-valued option on @socket, as with + * <literal>getsockopt ()</literal>. (If you need to fetch a + * non-integer-valued option, you will need to call + * <literal>getsockopt ()</literal> directly.) + * + * The <link linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link> + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Note that even for socket options that are a single byte in size, + * @value is still a pointer to a #gint variable, not a #guchar; + * g_socket_get_option() will handle the conversion internally. + * + * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>getsockopt ()</literal> call. + * Since: 2.36 + */ + + +/** * g_socket_get_protocol: * @socket: a #GSocket. * @@ -29605,7 +31326,7 @@ /** * g_socket_receive: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29739,7 +31460,7 @@ /** * g_socket_receive_with_blocking: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29950,10 +31671,10 @@ /** * g_socket_set_broadcast: * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses + * @broadcast: whether @socket should allow sending to broadcast addresses * - * Sets whether @socket should allow sending to and receiving from - * broadcast addresses. This is %FALSE by default. + * Sets whether @socket should allow sending to broadcast addresses. + * This is %FALSE by default. * * Since: 2.32 */ @@ -30028,6 +31749,30 @@ /** + * g_socket_set_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>) + * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>) + * @value: the value to set the option to + * @error: #GError for error reporting, or %NULL to ignore. + * + * Sets the value of an integer-valued option on @socket, as with + * <literal>setsockopt ()</literal>. (If you need to set a + * non-integer-valued option, you will need to call + * <literal>setsockopt ()</literal> directly.) + * + * The <link linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link> + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>setsockopt ()</literal> call. + * Since: 2.36 + */ + + +/** * g_socket_set_timeout: * @socket: a #GSocket. * @timeout: the timeout for @socket, in seconds, or 0 for none @@ -30259,6 +32004,528 @@ /** + * g_task_attach_source: + * @task: a #GTask + * @source: the source to attach + * @callback: the callback to invoke when @source triggers + * + * A utility function for dealing with async operations where you need + * to wait for a #GSource to trigger. Attaches @source to @task's + * #GMainContext with @task's <link + * linkend="io-priority">priority</link>, and sets @source's callback + * to @callback, with @task as the callback's + * <literal>user_data</literal>. + * + * This takes a reference on @task until @source is destroyed. + * + * Since: 2.36 + */ + + +/** + * g_task_get_cancellable: + * @task: a #GTask + * + * Gets @task's #GCancellable + * + * Returns: (transfer none): @task's #GCancellable + * Since: 2.36 + */ + + +/** + * g_task_get_check_cancellable: + * @task: the #GTask + * + * Gets @task's check-cancellable flag. See + * g_task_set_check_cancellable() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_context: + * @task: a #GTask + * + * Gets the #GMainContext that @task will return its result in (that + * is, the context that was the <link + * linkend="g-main-context-push-thread-default">thread-default main + * context</link> at the point when @task was created). + * + * This will always return a non-%NULL value, even if the task's + * context is the default #GMainContext. + * + * Returns: (transfer none): @task's #GMainContext + * Since: 2.36 + */ + + +/** + * g_task_get_priority: + * @task: a #GTask + * + * Gets @task's priority + * + * Returns: @task's priority + * Since: 2.36 + */ + + +/** + * g_task_get_return_on_cancel: + * @task: the #GTask + * + * Gets @task's return-on-cancel flag. See + * g_task_set_return_on_cancel() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_source_object: + * @task: a #GTask + * + * Gets the source object from @task. Like + * g_async_result_get_source_object(), but does not ref the object. + * + * Returns: (transfer none) (type GObject): @task's source object, or %NULL + * Since: 2.36 + */ + + +/** + * g_task_get_source_tag: + * @task: a #GTask + * + * Gets @task's source tag. See g_task_set_source_tag(). + * + * Returns: (transfer none): @task's source tag + * Since: 2.36 + */ + + +/** + * g_task_get_task_data: + * @task: a #GTask + * + * Gets @task's <literal>task_data</literal>. + * + * Returns: (transfer none): @task's <literal>task_data</literal>. + * Since: 2.36 + */ + + +/** + * g_task_had_error: + * @task: a #GTask. + * + * Tests if @task resulted in an error. + * + * Returns: %TRUE if the task resulted in an error, %FALSE otherwise. + * Since: 2.36 + */ + + +/** + * g_task_is_valid: + * @result: (type Gio.AsyncResult): A #GAsyncResult + * @source_object: (allow-none) (type GObject): the source object expected to be associated with the task + * + * Checks that @result is a #GTask, and that @source_object is its + * source object (or that @source_object is %NULL and @result has no + * source object). This can be used in g_return_if_fail() checks. + * + * Returns: %TRUE if @result and @source_object are valid, %FALSE if not + * Since: 2.36 + */ + + +/** + * g_task_new: + * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * + * Creates a #GTask acting on @source_object, which will eventually be + * used to invoke @callback in the current <link + * linkend="g-main-context-push-thread-default">thread-default main + * context</link>. + * + * Call this in the "start" method of your asynchronous method, and + * pass the #GTask around throughout the asynchronous operation. You + * can use g_task_set_task_data() to attach task-specific data to the + * object, which you can retrieve later via g_task_get_task_data(). + * + * By default, if @cancellable is cancelled, then the return value of + * the task will always be %G_IO_ERROR_CANCELLED, even if the task had + * already completed before the cancellation. This allows for + * simplified handling in cases where cancellation may imply that + * other objects that the task depends on have been destroyed. If you + * do not want this behavior, you can use + * g_task_set_check_cancellable() to change it. + * + * Returns: a #GTask. + * Since: 2.36 + */ + + +/** + * g_task_propagate_boolean: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as a #gboolean. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %FALSE and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or %FALSE on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_int: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as an integer (#gssize). + * + * If the task resulted in an error, or was cancelled, then this will + * instead return -1 and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or -1 on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_pointer: + * @task: a #GTask + * @error: return location for a #GError + * + * Gets the result of @task as a pointer, and transfers ownership + * of that value to the caller. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %NULL and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: (transfer full): the task result, or %NULL on error + * Since: 2.36 + */ + + +/** + * g_task_report_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @error: (transfer full): error to report + * + * Creates a #GTask and then immediately calls g_task_return_error() + * on it. Use this in the wrapper function of an asynchronous method + * when you want to avoid even calling the virtual method. You can + * then use g_async_result_is_tagged() in the finish method wrapper to + * check if the result there is tagged as having been created by the + * wrapper method, and deal with it appropriately if so. + * + * See also g_task_report_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_report_new_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Creates a #GTask and then immediately calls + * g_task_return_new_error() on it. Use this in the wrapper function + * of an asynchronous method when you want to avoid even calling the + * virtual method. You can then use g_async_result_is_tagged() in the + * finish method wrapper to check if the result there is tagged as + * having been created by the wrapper method, and deal with it + * appropriately if so. + * + * See also g_task_report_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_boolean: + * @task: a #GTask. + * @result: the #gboolean result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error: + * @task: a #GTask. + * @error: (transfer full): the #GError result of a task function. + * + * Sets @task's result to @error (which @task assumes ownership of) + * and completes the task (see g_task_return_pointer() for more + * discussion of exactly what this means). + * + * Note that since the task takes ownership of @error, and since the + * task may be completed before returning from g_task_return_error(), + * you cannot assume that @error is still valid after calling this. + * Call g_error_copy() on the error if you need to keep a local copy + * as well. + * + * See also g_task_return_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error_if_cancelled: + * @task: a #GTask + * + * Checks if @task's #GCancellable has been cancelled, and if so, sets + * @task's error accordingly and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Returns: %TRUE if @task has been cancelled, %FALSE if not + * Since: 2.36 + */ + + +/** + * g_task_return_int: + * @task: a #GTask. + * @result: the integer (#gssize) result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_new_error: + * @task: a #GTask. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Sets @task's result to a new #GError created from @domain, @code, + * @format, and the remaining arguments, and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * See also g_task_return_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_pointer: + * @task: a #GTask + * @result: (allow-none) (transfer full): the pointer result of a task function + * @result_destroy: (allow-none): a #GDestroyNotify function. + * + * Sets @task's result to @result and completes the task. If @result + * is not %NULL, then @result_destroy will be used to free @result if + * the caller does not take ownership of it with + * g_task_propagate_pointer(). + * + * "Completes the task" means that for an ordinary asynchronous task + * it will either invoke the task's callback, or else queue that + * callback to be invoked in the proper #GMainContext, or in the next + * iteration of the current #GMainContext. For a task run via + * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this + * method will save @result to be returned to the caller later, but + * the task will not actually be completed until the #GTaskThreadFunc + * exits. + * + * Note that since the task may be completed before returning from + * g_task_return_pointer(), you cannot assume that @result is still + * valid after calling this, unless you are still holding another + * reference on it. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread. When @task_func returns, @task's + * #GAsyncReadyCallback will be invoked in @task's #GMainContext. + * + * This takes a ref on @task until the task completes. + * + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread_sync: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread, and waits for it to return or be + * cancelled. You can use g_task_propagate_pointer(), etc, afterward + * to get the result of @task_func. + * + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Normally this is used with tasks created with a %NULL + * <literal>callback</literal>, but note that even if the task does + * have a callback, it will not be invoked when @task_func returns. + * + * Since: 2.36 + */ + + +/** + * g_task_set_check_cancellable: + * @task: the #GTask + * @check_cancellable: whether #GTask will check the state of its #GCancellable for you. + * + * Sets or clears @task's check-cancellable flag. If this is %TRUE + * (the default), then g_task_propagate_pointer(), etc, and + * g_task_had_error() will check the task's #GCancellable first, and + * if it has been cancelled, then they will consider the task to have + * returned an "Operation was cancelled" error + * (%G_IO_ERROR_CANCELLED), regardless of any other error or return + * value the task may have had. + * + * If @check_cancellable is %FALSE, then the #GTask will not check the + * cancellable itself, and it is up to @task's owner to do this (eg, + * via g_task_return_error_if_cancelled()). + * + * If you are using g_task_set_return_on_cancel() as well, then + * you must leave check-cancellable set %TRUE. + * + * Since: 2.36 + */ + + +/** + * g_task_set_priority: + * @task: the #GTask + * @priority: the <link linkend="io-priority">priority</link> of the request. + * + * Sets @task's priority. If you do not call this, it will default to + * %G_PRIORITY_DEFAULT. + * + * This will affect the priority of #GSources created with + * g_task_attach_source() and the scheduling of tasks run in threads, + * and can also be explicitly retrieved later via + * g_task_get_priority(). + * + * Since: 2.36 + */ + + +/** + * g_task_set_return_on_cancel: + * @task: the #GTask + * @return_on_cancel: whether the task returns automatically when it is cancelled. + * + * Sets or clears @task's return-on-cancel flag. This is only + * meaningful for tasks run via g_task_run_in_thread() or + * g_task_run_in_thread_sync(). + * + * If @return_on_cancel is %TRUE, then cancelling @task's + * #GCancellable will immediately cause it to return, as though the + * task's #GTaskThreadFunc had called + * g_task_return_error_if_cancelled() and then returned. + * + * This allows you to create a cancellable wrapper around an + * uninterruptable function. The #GTaskThreadFunc just needs to be + * careful that it does not modify any externally-visible state after + * it has been cancelled. To do that, the thread should call + * g_task_set_return_on_cancel() again to (atomically) set + * return-on-cancel %FALSE before making externally-visible changes; + * if the task gets cancelled before the return-on-cancel flag could + * be changed, g_task_set_return_on_cancel() will indicate this by + * returning %FALSE. + * + * You can disable and re-enable this flag multiple times if you wish. + * If the task's #GCancellable is cancelled while return-on-cancel is + * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE + * again will cause the task to be cancelled at that point. + * + * If the task's #GCancellable is already cancelled before you call + * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the + * #GTaskThreadFunc will still be run (for consistency), but the task + * will also be completed right away. + * + * Returns: %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled. + * Since: 2.36 + */ + + +/** + * g_task_set_source_tag: + * @task: the #GTask + * @source_tag: an opaque pointer indicating the source of this task + * + * Sets @task's source tag. You can use this to tag a task return + * value with a particular pointer (usually a pointer to the function + * doing the tagging) and then later check it using + * g_task_get_source_tag() (or g_async_result_is_tagged()) in the + * task's "finish" function, to figure out if the response came from a + * particular place. + * + * Since: 2.36 + */ + + +/** + * g_task_set_task_data: + * @task: the #GTask + * @task_data: (allow-none): task-specific data + * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data + * + * Sets @task's task data (freeing the existing task data, if any). + * + * Since: 2.36 + */ + + +/** * g_tcp_connection_get_graceful_disconnect: * @connection: a #GTcpConnection * @@ -30395,7 +32662,7 @@ * @self: a #GTestDBus * * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this - * call, it is safe for unit tests to start sending messages on the session bug. + * call, it is safe for unit tests to start sending messages on the session bus. * * If this function is called from setup callback of g_test_add(), * g_test_dbus_down() must be called in its teardown callback. @@ -31318,7 +33585,7 @@ * Finish an asynchronous lookup of certificates. See * g_tls_database_lookup_certificates_issued_by() for more information. * - * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. + * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. * Since: 2.30 */ |